T-Kernel 2.0 Extension Specification (TEF020-S009
Total Page:16
File Type:pdf, Size:1020Kb
T-Kernel2.0EXtension T-Kernel 2.0 Extension Specification December 2012 T-Engine Forum http://www.t-engine.org/ TEF020-S009-02.00.00/en Copyright (c) 2012 by T-Engine Forum T-Kernel 2.0 Extension Specification (Ver.2.00.00) ------------------------------------------- Copyright (c) 2012 by T-Engine Forum You should not transcribe the content, duplicate a part of this specification, etc. without the consent of T-Engine Forum. For improvement, etc., information in this specification is subject to change without notice. For information about this specification, please contact the following: T-Engine Forum Secretariat In YRP Ubiquitous Networking Laboratory 28th Kowa Building, 2-20-1 Nishi-gotanda Shinagawa, Tokyo Japan 141-0031 +81-(0)-3-5437-0572 +81-(0)-3-5437-2399 [email protected] Note In this specification, POSIX means Portable Operating System Interface, specifically the so-called UNIX system Operating System Interface defined in the following standards. ISO/IEC/IEEE 9945 Information technology - Portable Operationg System Interface (POSIX) Base Specifications, Issue 7 The standard C library referred to in the chapter for the Standard C Compatible Library means the above POSIX as well as the library functions defined in the following standard. JIS X 3010:2003 (ISO/IEC 9899:1999) Programming Language C Considering the programming ease and portability at some degree of affinity with POSIX, this specification follows the standard C library specifications almost as is so that programs using the standard C library may easily be ported. This specification quotes some descriptions from the above standards with permission from IEC. This specification is an extension of the underlying T-Kernel 2.0, which is an operating system of a totally different nature from POSIX. This specification does not guarantee the compatibility with POSIX. In addition, it is not guaranteed that C language programs written as per this specification are compliant with the JIS C standard. IEC: International Electrotechnical Commission ISO: International Organization for Standardization JIS: Japanese Industrial Standards The function declarations, structure definitions, and numerical values in this specification are written according to the C language syntax. Copyright © 2012 by T-Engine Forum. All rights reserved. i TEF020-S009-02.00.00/en Table of Contents 1. T-Kernel 2.0 Extension Overview 1 1.1 Overview 1 1.2 T-Kernel 2.0 Extension Features 1 1.3 Relationship with T-Kernel 2 1.4 Relationship with POSIX 3 1.5 Dependencies between Function Modules 4 2. Common Rule 5 2.1 Data Types 5 2.2 String 6 2.3 Valid Context 6 2.4 Usage of T-Kernel 2.0 API 6 2.5 Error Codes 7 2.6 Thread-Safe 8 3. Memory Protection Function 9 3.1 Overview 9 3.2 Memory Protection Model 9 4. File Management Function 13 4.1 Overview 13 4.2 Definition 13 4.3 Unupported Functions 18 4.4 API 18 4.5 File System Implementation Part 42 5. Network Communication Function 54 5.1 Overview 54 5.2 Terms Used in This Section 54 5.3 Unsupported Functions 61 5.4 Data Type Definitions 61 5.5 API 65 5.6 Operation for Routing Socket 101 6. Calendar Function 107 6.1 Overview 107 6.2 Definition 107 6.3 API 109 7. Program Load Function 120 7.1 Overview 120 7.2 Regular Program Module 120 7.3 System Program Module 121 7.4 Data Type Definition 121 7.5 API 122 8. Standard C Compatible Library 126 8.1 Overview 126 8.2 Compatibility 126 8.3 arpa/inet.h - BSD Socket 130 8.4 assert.h - Testing Function 133 8.5 complex.h - Complex Calculation 134 8.6 ctype.h - Character Type Classification 145 8.7 dirent.h - Directory Reading 146 8.8 errno.h - Error Number Definition 150 8.9 float.h - Floating Point Limit Value 153 8.10 inttypes.h - Integer Type Format Conversion 155 8.11 iso646.h -Alternate Spellings 158 8.12 limits.h - Various Limit Values 159 8.13 math.h - Numeric Operation 161 8.14 netinet/in.h - BSD Socket 193 8.15 search.h - Search 194 8.16 stdarg.h - Variable Number Actual Argument 199 8.17 stdbool.h - Boolean Type and Boolean Value 201 8.18 stddef.h - Standard Definition 202 8.19 stdint.h - Integer Type 203 8.20 stdio.h - Standard Input/Output 206 8.21 stdlib.h - General Utility 233 8.22 string.h - String Operation 247 8.23 strings.h - Byte Sequence Operation 259 8.24 time.h - Date and Time 262 Copyright © 2012 by T-Engine Forum. All rights reserved. ii TEF020-S009-02.00.00/en 8.25 wchar.h - Multibyte and Wide Character Extension 267 Appendix A.1 System Setting 268 A.2 Usage Examples of Break Function 269 A.3 Usage Example of Regular Program Module Function 270 Copyright © 2012 by T-Engine Forum. All rights reserved. iii TEF020-S009-02.00.00/en Chapter 1 T-Kernel 2.0 Extension Overview 1.1. Overview T-Kernel 2.0 Extension ("T2EX" below) is the T-Kernel 2.0 feature expansion program. Making the most of light-weight, high-speed, and real-time properties of T-Kernel, a real-time operating system, T2EX is designed as a light-weight extension to realize advanced embedded systems. The functions provided to applications by T2EX consist of extended SVCs (extended system call), library functions, and macros. These functions and application interfaces altogether are called API (Application Programming Interface). The T2EX specification is defined by the T2EX API. Each one of the individual system calls, library functions, and macros in the API is called an "API call". The whole of the file management function API calls, for example, is called the "file management function API". Figure 1.1 shows the software architecture including T2EX. This extension is positioned as an extension available as an additional T-Kernel 2.0 function (addon), allowing you to build application programs using both the T-Kernel 2.0 and T2EX APIs. <file:figure1_1.png> (Figure1.1: T-Kernel 2.0 Extension configuration and positioning) To support the advanced embedded system development, T2EX provides the following functions. - Memory Protection Function - File Management Function - Network Communication Function - Calendar Function - Program Load Function - Standard C Compatible Library Each function is provided as a module by functional unit, allowing you to use some of them and unuse (remove) any unnecessary function modules as needed. The T-Engine forum implements standard T2EX codes on T-Kernel 2.0 on the T-Engine reference board as an extension and discloses the source codes together with the specifications. This implementation is called the "T2EX reference implementation". This specification also describes how implementation-dependent items are implemented in the T2EX reference implementation. 1.2. T-Kernel 2.0 Extension Features Following the existing T-Kernel 2.0 performances and maximizing its light-weight, high-speed, and real-time properties, T2EX is designed to meet the requirement for additional functions in embedded systems that has become larger and more sophisticated. The main features of T2EX are described below. Copyright © 2012 by T-Engine Forum. All rights reserved. 1 TEF020-S009-02.00.00/en Processless, light-weight extension T2EX does not provide the process function to make the entire system light-weight. The process function is effective when developing programs for relatively large systems on a module-by-module basis. However, it does not go together with light-weight and high-speed properties of the entire system, due to large overhead in inter-process communication and resource switching resulting from the split resource. Aiming at lightweight, T2EX assumes the entire system to be built without processes, allowing various extended functions, including file management and network communication, to be used by directly calling them from the task instead of a process. This direct availability of extended functions from the T-Kernel 2.0 task allows you to realize advanced functions while making the most use of the T-Kernel 2.0 real-time property. Effective memory protection function independent of virtual memory General process-based memory protections are based on multiple logical spaces with large overhead in execution when switching the spaces. T-Kernel 2.0 task-based programs often exchange information among multiple tasks via variables (memory). Simply divided logical spaces would increase the inter-process communication overhead. Aiming at lightweight, T2EX provides an effectively feasible two-level ring protection at the system and user levels. This ensures necessary and sufficient reliability for a relatively complex case in a specific-purpose embedded system, which is a main target of this extension. Modular T2EX provides many functions including file management and network communication. Each of them is separated on a module-by-module basis, allowing you to use only the selected necessary modules and remove the rest. This can reduce use of RAM and ROM by unnecessary functions. More affinity with standard C and POSIX specifications Many of the functions targeted by this extension, such as C language standard input/output and network communication functions, have the de facto standard. The T2EX API design orients toward the optimum format as a T-Kernel task-based programming API while it considers affinity with the standard C library and the POSIX specification in terms of code reusability and reduced learning cost. Specific elaborations include: - Integration of the standard C library and POSIX specification error numbers (errno) into the error codes (ER type) The T-Kernel 2.0 error codes are extended so that the error numbers (errno) can be handled as is in the T-Kernel 2.0 error code system. This eliminates confusions when using the standard C and POSIX specification error numbers (errno_t type) together with the error codes (ER type).