IPC@CHIP® RTOS-PPC – API Documentation
1 Migrating from SC1x, SC2x and SC1x3 systems
1.1 Data size
1.3 Data structure alignment
1.4 Bit numbering
1.6 Legacy API functions
1.7 Deprecated API functions
1.8 Incompatible API groups
1.9 Further unsupported SC1x, SC2x and SC1x3 API functions
1.10 Task priorities
1.11 User names/Passwords
1.12 STDIO channel names
1.13 Floating point
1.14 Global variables
The following description should help you to manage the differences between the SC1x, SC2x and SC1x3 systems and the SC2x3 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 SC2x3.
SC1x, SC2x and SC1x3
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 32-bit value 0x12345678 is stored in memory as follows:
The @CHIP-RTOS-PPC 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 operation system.
The SC2x3 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. The PowerPC architecture numbering scheme, where MSB = Bit0 is not used in the API documentation.
Watch out for compatibility notes in the function documentations. Not all functions of the @CHIP-RTOS-PPC are also supported on the SC1x, SC2x and SC1x3 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.
The following listed API groups are in general no longer compatible with the API functions of the SC1x, SC2x and SC1x3 RTOS:
See here for a list of further SC1x, SC2x and SC1x3 API functions, which are no longer supported at the SC2x3 RTOS API.
The default task priorities of the built-in servers and the default priority of an application program has changed in the @CHIP-RTOS-PPC. The task priorities have been spread better throughout the available range of priorities. See Tasks description
The SC2x3 RTOS 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 SC2x3 RTOS. The denotations "EXT" and "COM" are no longer used. The SC2x3 RTOS uses the denotations "UART1" and "UART3" for better understanding.
The SC2x3 systems are equipped with a hardware floating point unit, whereas the SC1x, SC2x and SC1x3 systems must use a software floating point math-emulation in the compiler. Due to the hardware floating point unit most of the previous precautions are no longer necessary.
Notes: Violation of any of the following rules can result in damage to the floating-point context of a task.
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 ONE-Workbench uses the Red Hat newlib implementation of the standard library functions. This implementation ensures that whenever possible, these library functions are reentrant. However, there are some functions that can not be trivially made reentrant. The newlib provides hooks to allow to use these functions in a fully reentrant fashion.
All functions which must manipulate global information are available in two versions in the newlib. The first version has the usual name (e.g. fopen()). The second has a different name, normally formed by prepending '_' and appending '_r', and takes a pointer to the particular reentrancy structure to use. Important: The CLIB has already filled-in the necessary hooks to make the standard name functions (e.g. fopen()) reentrant. There's normally no need to call the second version name of a function (e.g. fopen_r()) within a user program.
Here are some notes concerning the application programs which can be executed on the @CHIP-RTOS-PPC.
The executable files have the *.BEX extension. These files are derived from the industry standard ELF files by the GenBEX build tool.
Each application program contains a set of constants used by the system at program launch time to determine the size of that program's stack and heap space. The privilege mode of operation is also determined by these constants. The programmer can adjust these application program configuration constants during the build process.
The default program heap size is 4096 bytes. This can be overridden with the setHeapInitialSize macro.
The program's standard C-library heap functions such as
malloc() are re-entrant.
Several heap options can be controlled by the user.
Programs may make calls into one another's exported functions, as done by the example program shown here.
This section list some known problems with this @CHIP-RTOS-PPC release.
This section list some facts about the TCP/IP stack of the @CHIP-RTOS-PPC.
The TCP/IP stack of the @CHIP-RTOS-PPC supports multiple interfaces and multiple IPs on the same physical interface. Anyhow, there are some restrictions that should be noticed.
The amount of dynamic memory required by the TCP/IP stack depends on the number of open sockets and the size and number of data packets transported.
During system start a big buffer is allocated inside the @CHIP-RTOS-PPC system heap for usage with the TCP/IP stack. The size of this buffer can be configured by the user. The TCP/IP stack uses his own memory management within this buffer. The TCPIPMEM command and the Get_TCPIP_Memory_Status() API will show how much memory the TCP/IP stack uses from this pre-allocated buffer. When any block is released by the TCP/IP stack, it will be recycled internally. The amount of "used" memory that is displayed will normally not decrease and therefore should be regarded as a maximum used value.
For faster allocations the recycled blocks are stored in lists that hold a set of memory blocks of a particular fixed size (32, 64, 128, .. 4096 bytes). (Allocations bigger than 4096 bytes will not be made from the preallocated block, instead they will be directly allocated and freed from the RTOS system heap.) Depending on the application it can take some time until the TCP/IP memory reaches a steady state and all recycle lists hold enough buffers of the needed sizes.
If the size of the preallocated buffer is not big enough for the application needs or a memory leak exist, the free memory gets exhausted. In this case the stack frees all blocks in his internal recycle lists. That's the only instance where the amount of "used" memory that is displayed at the TCPIPMEM command will decrease. Anyhow, it's not guaranteed that this operation is successful. It's recommended that the user installs an error handler for this case.