IPC@CHIP® RTOS-LNX – API Documentation

Header image

Main page


Programming notes

1 Migrating from SC1x, SC2x, SC1x3 and SC2x3 systems
    1.1 Data size
    1.2 Endianess
    1.3 Data structure alignment
    1.4 Bit numbering
    1.5 Compatibility
    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.17 bind
    1.18 mkdir

2 Application Programs
    2.1 Executable File Format
    2.2 Communication between Programs

3 Known problems
    3.1 Known issues

4 TCP/IP stack
    4.1 IP addresses and multihoming

5 Flash memory
    5.1 @CHIP-RTOS-LNX-reserved memory


1. Migrating from SC1x, SC2x, SC1x3 and SC2x3 systems

The following description should help you to manage the differences between the SC1x, SC2x, SC1x3 and SC2x3 systems and the SC1x8 and SC1x5 targets.

1.1 Data size

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

1.2 Endianness

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
Big Endian 0x12 0x34 0x56 0x78
Little Endian 0x78 0x56 0x34 0x12

The @CHIP-RTOS-LNX defines some helper macros to deal with the endianness, see e.g. hostToLE16.

1.3 Data structure alignment

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 operation 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.

1.4 Bit numbering

The IPC@CHIP® API calls use the "classic" numbering scheme, where LSB = Bit0. This is common to all targets.

1.5 Compatibility

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.

1.6 Legacy API functions

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.

1.7 Deprecated API functions

See the Deprecated List for a list of all deprecated API functions.

1.8 Unsupported SC1x, SC2x, SC1x3 and SC2x3 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.

1.9 Task priorities

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.

1.10 Task stack sizes

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.

1.11 User names/Passwords

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.

1.12 STDIO channel names

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.

1.13 Floating point

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.

1.14 Global variables

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.

1.15 TCP/IP error codes

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 comparision, 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 libary 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.

1.16 sockaddr / sockaddr_in struct members

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.

1.17 bind

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.

1.18 mkdir

The standard library function mkdir() takes one additional parameter in comparision to the legacy systems.
Replace code like this:
         mkdir(pathName);
with this:
         mkdir(pathName, 0775);


2. Application Programs

Here are some notes concerning the application programs which can be executed on the @CHIP-RTOS-LNX.

2.1 Executable File Format

The executable files have the *.BEX extension. These files are industry standard ELF files.

2.2 Communication between Programs

Several mechanisms are available to provide communication between application programs. These include the Message Exchange and public data API.

CAUTION: The @CHIP-RTOS-LNX uses virtual addresses. Consequently, pointers must not be passed between programs (unlike was possible in the legacy systems).


3. Known problems

This section list some known problems with this @CHIP-RTOS-LNX release.

3.1 Known issues


4. TCP/IP stack

This section list some facts about the TCP/IP stack of the @CHIP-RTOS-LNX.

4.1 IP addresses and multihoming

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.

5. Flash memory

This section list some facts about the flash memory of the @CHIP-RTOS-LNX.

5.1 @CHIP-RTOS-LNX-reserved memory

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 (34240864 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.






Top of page | Main page

Copyright © 2018 Beck IPC GmbH
Generated on Fri Jun 8 2018 12:48:20 by Doxygen 1.8.13