IPC@CHIP® RTOS-LNX – API Documentation
1 Migrating from SC1x, SC2x, SC1x3 and SC2x3 systems
1.1 Data size
1.3 Data structure alignment
1.4 Bit numbering
1.5 Compatibility notes
1.6 Legacy API functions
1.7 Deprecated API functions
1.8 Unsupported SC1x, SC2x, SC1x3 and SC2x3 API functions
1.9 Task priorities
1.10 Task stack sizes
1.11 User names/Passwords
1.12 STDIO channel names
1.13 Floating point
1.14 Global variables
1.15 TCP/IP error codes
1.16 sockaddr / sockaddr_in struct members
1.20 fopen text mode
The following description should help you to manage the differences between the SC1x, SC2x, SC1x3 and SC2x3 systems and the SC1x8 and SC1x5 targets.
It's important to note that the data type int is a 16-Bit type on SC1x, SC2x and SC1x3, but a 32-Bit type on SC1x8 and SC1x5.
|Data type / Target||SC1x, SC2x and SC1x3||SC2x3||SC1x8 and SC1x5|
|char||1 Byte||1 Byte||1 Byte|
|short int||2 Byte||2 Byte||2 Byte|
|int||2 Byte||4 Byte||4 Byte|
|long||4 Byte||4 Byte||4 Byte|
|long long||n/a||8 Byte||8 Byte|
The SC1x, SC2x and SC1x3 systems use a little-endian 16-Bit x86 processor. The SC2x3 systems use a big-endian 32-bit PowerPC processor The SC1x8 and SC1x5 systems use a little-endian 32-bit ARM processor. The 32-bit value 0x12345678 is stored in memory as follows:
|Endianness / Address||0||1||2||3|
The @CHIP-RTOS-LNX defines some helper macros to deal with the endianness, see e.g. hostToLE16.
The SC1x, SC2x and SC1x3 RTOS uses byte alignment for his data structures. So the user applications must also be compiled with byte data alignment in order to interchange data structures with the operating system.
The SC1x8 and SC1x5 RTOS uses the alignment rules of the Embedded Application Binary Interface (EABI) standard for his data structures, if not otherwise documented. When interchanging data structures with other systems, get sure that both systems use the same data alignment. The alignment of data structures can be controlled with #pragma pack keywords surrounding the struct/union definition.
The IPC@CHIP® API calls use the "classic" numbering scheme, where LSB = Bit0. This is common to all targets.
Watch out for compatibility notes in the function documentations. Not all functions of the @CHIP-RTOS-LNX are also supported on the SC1x, SC2x, SC1x3 and SC2x3 systems.
Throughout the documentation you will see some functions/macros are marked with "Legacy API". In this case the functions/macros are provided for backwards compatibility to the SC1x, SC2x and SC1x3 systems.
See the Deprecated List for a list of all deprecated API functions.
See here for a list of further SC1x, SC2x, SC1x3 and SC2x3 API functions, which are no longer supported at the SC1x8 and SC1x5 RTOS API.
The task priority range has changed in the @CHIP-RTOS-LNX. For user program tasks the priorities 0-90 are available, where 0 is the highest priority.
The default task priorities of the built-in servers and the default priority of an application program has changed in the @CHIP-RTOS-LNX. See System Tasks description.
The @CHIP-RTOS-LNX uses the GLIBC as the C standard library. Some standard library functions, e.g. printf(), require a lot more stack space than the SC1x, SC2x, SC1x3 and SC2x3 systems did. That's the reason why you need to adapt your task stack sizes to the new system. The minimum stack size is now 32768 bytes. Please note that the @CHIP-RTOS-LNX provides a new feature in this context. The tkdStackBase member can be set to NULL. In this case the @CHIP-RTOS-LNX allocates the stack space.
The @CHIP-RTOS-LNX uses case sensitive user names and passwords in the CHIP.INI. On the SC1x, SC2x and SC1x3 systems RTOS this is not always the case.
The serial STDIO channel names have been renamed on the @CHIP-RTOS-LNX. The denotations "EXT" and "COM" are no longer used. The @CHIP-RTOS-LNX uses the denotations "UART1" and "UART3" for better understanding.
The SC1x5 systems are equipped with a hardware floating point unit, whereas the SC1x8 systems must use a software floating point math-emulation in the compiler. Previous precautions from the SC1x, SC2x and SC1x3 are no longer necessary.
The GCC compiler used in the ONE-Workbench is a high optimizing compiler. Therefore it's important that all global variables, that may be modified externally from another task or inside an interrupt function, are declared with the volatile keyword. Variables declared to be volatile will not be optimized by the compiler because the compiler must assume that their values can change at any time.
The error codes of the LEGACY_BECK_SOCKET_API_STYLE and the BSD44_SOCKET_API_STYLE are the same as on the SC1x, SC2x, SC1x3 and SC2x3 systems. E.g the error "operation would block" is defined as the number 235. As long as an application, that should be ported, only used these binary numbers, no porting problems should arise. However, if the application used a define for the comparison, e.g EWOULDBLOCK, some code changes need to be applied.
Due to the fact that these error code defines are defined by the C standard library and e.g. are used internally for the BSD44_LINUX_SOCKET_API_STYLE socket API, these error code defines do no longer match with the Beck style error codes. The Beck style error codes are available now with the BECK_ prefix, e.g. EWOULDBLOCK now becomes BECK_EWOULDBLOCK.
On the @CHIP-RTOS-LNX the TCP/IP structure sockaddr has no member sa_len and the structure sockaddr_in has no member sin_len.
At the legacy systems it was possible to bind a UDP socket to an IP and port and still receive broadcasts at this socket. If a specific IP address is given to the bind call at the @CHIP-RTOS-LNX, broadcasts will not be received. Instead the user needs to set the socket option
SO_BINDTODEVICE to achieve a similar behavior.
The standard library function mkdir() takes one additional parameter in comparison to the legacy systems.
Replace code like this:
The fopen() API does not support the text mode. This means that files that are opened with e.g. "r" are opened in binary mode. For portability it's a good idea to add a 'b' to the mode parameter, e.g. "rb", if your program may be ported to non-UNIX environments.
Here are some notes concerning the application programs which can be executed on the @CHIP-RTOS-LNX.
The executable files have the *.BEX extension. These files are industry standard ELF files.
CAUTION: The @CHIP-RTOS-LNX uses virtual addresses. Consequently, pointers must not be passed between programs (unlike was possible in the legacy systems).
The CLIB on the @CHIP-RTOS-LNX is provided as a shared library that comes with the @CHIP-RTOS-LNX version. We try to keep the CLIB ABI compatible with newer @CHIP-RTOS-LNX versions. This means that a program compiled against older CLIB headers should still work on a newer @CHIP-RTOS-LNX version. However, the CLIB has some dependencies to other libraries, e.g. OpenSSL. If such a dependency library becomes ABI incompatible, the CLIB can also be affected. In such a case the claim that a old program should still work is no longer true. In such a case we increase the major @CHIP-RTOS-LNX version number. Especially, this was the case for the V2.00 @CHIP-RTOS-LNX release, where we changed the OpenSSL version to 1.1.1. To improve the situation for future releases, we changed the linking rules. Now the libraries, that the CLIB depends on, are added during the CLIB build and not on the final user application.
This section list some known problems with this @CHIP-RTOS-LNX release.
This section list some facts about the TCP/IP stack of the @CHIP-RTOS-LNX.
The TCP/IP stack of the @CHIP-RTOS-LNX supports multiple interfaces and multiple IPs on the same physical interface. Anyhow, there are some restrictions that should be noticed.
|Valid configuration||Invalid configuration|
This section list some facts about the flash memory of the @CHIP-RTOS-LNX.
From the total flash memory, some memory is reserved by the @CHIP-RTOS-LNX for the bootloader, the OS, device information and user persistent data. The remainder is available for the drive A:.
|@CHIP-RTOS-LNX||Reserved for system||Available for drive A:|
|SC145||~31,25 MB (32768000 Bytes)||~32,65 MB (34340864 Bytes), see NOTE below.|
|SC165||~224,75 MB (235667456 Bytes), see NOTE below.|
|SC128/SC158/SC168||~80,25 MB (84148224 Bytes)||~1791,75 MB (1878786048 Bytes)|
NOTE: The flash file system used for the SC1x5 drive A: uses compression. The total amount of storage space an this drive is therefore normally greater than the number listed here. It highly depends on the possible compression rate of the stored data.