IPC@CHIP® RTOS-PPC – API Documentation

Header image

Main page


Programming notes

1 Migrating from SC1x, SC2x and SC1x3 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 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
    1.15 Reentrancy

2 Application Programs
    2.1 Executable File Format
    2.2 Program Configuration Constants
    2.3 Heap Manager
    2.4 Communication between Programs

3 Known problems
    3.1 Known issues

4 TCP/IP stack
    4.1 IP addresses and multihoming
    4.2 TCP/IP memory usage


1. Migrating from SC1x, SC2x and SC1x3 systems

The following description should help you to manage the differences between the SC1x, SC2x and SC1x3 systems and the SC2x3 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 SC2x3.

Data type

SC1x, SC2x and SC1x3

SC2x3

char

1 Byte

1 Byte

short int

2 Byte

2 Byte

int

2 Byte

4 Byte

long

4 Byte

4 Byte

long long

n/a

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 32-bit value 0x12345678 is stored in memory as follows:

Address

0

1

2

3

Big Endian

0x12

0x34

0x56

0x78

Little Endian

0x78

0x56

0x34

0x12

The @CHIP-RTOS-PPC 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 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.

1.4 Bit numbering

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.

1.5 Compatibility

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.

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 Incompatible API groups

The following listed API groups are in general no longer compatible with the API functions of the SC1x, SC2x and SC1x3 RTOS:

1.9 Further unsupported SC1x, SC2x and SC1x3 API functions

See here for a list of further SC1x, SC2x and SC1x3 API functions, which are no longer supported at the SC2x3 RTOS API.

1.10 Task priorities

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

1.11 User names/Passwords

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.

1.12 STDIO channel names

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.

1.13 Floating point

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.

  1. It's not permitted to use any floating point operation inside interrupt service procedures.
  2. Changing the CPU's Machine State Register (MSR) while external interrupts are enabled is not permitted.

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 Reentrancy

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.


2. Application Programs

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

2.1 Executable File Format

The executable files have the *.BEX extension. These files are derived from the industry standard ELF files by the GenBEX build tool.

2.2 Program Configuration Constants

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.

2.3 Heap Manager

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.

2.4 Communication between Programs

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

Programs may make calls into one another's exported functions, as done by the example program shown here.


3. Known problems

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

3.1 Known issues


4. TCP/IP stack

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

4.1 IP addresses and multihoming

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.

4.2 TCP/IP memory usage

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.






Top of page | Main page

Copyright © 2017 Beck IPC GmbH
Generated on Thu Jan 26 16:21:35 2017 by Doxygen 1.6.1