Porting FreeRTOS+TCP to a New Embedded C Compiler
Summary Bullet Points
The FreeRTOS+TCP source code has two compiler dependencies:
How the compiler is told to pack C structures (that is,
not leave any alignment bytes between the members of the
C structure). Packing
structures is very important to ensure data appears
correctly in the TCP, UDP, IP and Ethernet frames.
- How the compiler and MCU RTOS port define an interrupt service routine (ISR). The embedded IP stack only uses interrupts to manage the Ethernet driver, and so this topic is not covered here.
- How the compiler is told to pack C structures (that is, not leave any alignment bytes between the members of the C structure). Packing structures is very important to ensure data appears correctly in the TCP, UDP, IP and Ethernet frames.
The syntax used to ensure C structures are packed correctly is
placed in a compiler specific header file to ensure the non-portable
code is not included in the core embedded IP stack source code.
Two header files are required for each embedded C compiler.
pack_struct_start.h contains the keywords required
to appear before the definition of a C structure that
must be packed.
pack_struct_end.h contains the keywords required
to appear after the definition of a C structure that
must be packed.
- pack_struct_start.h contains the keywords required to appear before the definition of a C structure that must be packed.
Compiler specific header files that ship with the embedded TCP/IP
stack are located in the FreeRTOS-Plus/FreeRTOS-Plus-TCP/portable/Compiler
The first three members are 8 bits each, and will most likely appear in three consecutive bytes of the same 32-bit word. The forth member is 32-bits, and can be accessed most efficiently (dependent on the MCU, but in most cases) if it is placed on a 32-bit (four byte) boundary. Therefore, without the structure being packets, the compiler will most likely add a ‘padding’ byte between Member3 and Member4 to move the start address of Member4 up one byte and so onto a 32-bit boundary. The structure will then appear in memory as follows:
However, the TCP/IP protocol headers do not have padding bytes, so the compiler must be instructed not to add them additional bytes into structures that map onto the IP protocol headers that a written to or read from Ethernet frames. Structures that do not contain padding bytes are said to be ‘packed’. The syntax required to ensure structures are packed depends on the embedded C compiler. The FreeRTOS+TCP implementation cannot use any C compiler specific syntax in the common (not MCU port specific) files, and instead allows users to define their own packing directives in two very simple header files that are then included from the C files.
Structures that require packing appear in the FreeRTOS+TCP code as follows:
A version of pack_struct_start.h and pack_struct_end.h that contains compiler specific syntax can then be provided for each compiler.
For example, the directory FreeRTOS-Plus/FreeRTOS-Plus-UDP/portable/Compiler/GCC contains definitions suitable for use with the GCC compiler. pack_struct_start.h is empty because GCC does not require any special syntax at the start of the structure. pack_struct_end.h contains the following single line of code:
__attribute__( (packed) );So, after pre-processing the C source code appears to the compiler as shown below, which is valid GCC syntax:
FreeRTOS-Plus/FreeRTOS-Plus-TCP/portable/Compiler/GCC is already included in the FreeRTOS+TCP download and can be used as a refeference when porting to other embedded C compilers.
pack_struct_end.h must, as a minimum, contain at least a semicolon ( ; ) to mark the end of the structure definition. It is sometimes valid for pack_struct_start.h to be empty, but it is never valid for pack_struct_end.h to be completely empty.