Notes for Developers

Coding Style & Conventions

Layout, Comments, and Pretty Things

• The code MUST use only C style comments, ie:

      /* This is a C Style comment */
      //Do NOT use these, which are C++ Style Comments
  

• Bracket style is as:

      if (something == this)
      {
          Do some stuff;
      }
      else if (otherstuff == whatever)
      {
          Do some more stuff;
      }
      

• To remove sections of code, use the preprocessor instead of commenting out the area. Any recent code editor should be able to understand and colour-code this area to make it obvious you have removed this section.

      #if 0
      int functionGoesHere(void)
      {
          return;
      }
      #endif
      

• When defining structures, ideally use 'typedef struct', instead of seperate struct & typedef. Also include documentation for each element structure. :

      typedef struct
      {
          unsigned char     element;          /**< Document this element */ 
          unsigned int      anotherElement;   /**< Document this element */
      } struct_name_t;
      

• Do not use the tab character. Indent with spaces, set the tab character in your editor to 4 spaces

• Lines should be around 80 characters in length maximum. This is not a strict requirement however, and just a guideline.

Cross-Platform Considerations

• Don't use the types in stdint.h unless you actually require a specific bit alignment or size. Using an unsigned int allows a 32-bit machine to use naturally aligned words for instance, as it can use a 32-bit unsigned int. Typically structs which are part of a protocol will require the use of stdint.h types (uint8_t, uint16_t, etc)

• Use the full stdint.h type, and not shorter versions (ie: don't typedef uint8_t u8 for laziness). This is more cosmetic.

• Do not use bitfields when order matters, their layout is not standard. C99 6.7.2.1, paragraph 10 says:

      The order of allocation of bit-fields within a unit (high-order to
      low-order or low-order to high-order) is implementation-defined.
      

• ONLY pack structures which require it on 32-bit machines. Typically this means structs which hold network protocols etc. Around the entire structure put _PACKSTART and _PACKEND, and before the name of the structure put _PS. For example:

      /// Router Solicitation Message Type
      _PACKSTART
      typedef struct {
          uint8_t     type;               /**< ICMPv6 Type (133) */
          uint8_t     code;               /**< ICMPv6 Code (0) */
          uint16_t    checksum;           /**< ICMPv6 Checksum */
          uint32_t    reserved;           /**< Reserved field */ 
      } _PS fip_nd6_rs_t;
      _PACKEND
      

• Enumerated types are used all over the place. Enumerated types are much easier to debug, as you can see the value of the variable as a type, rather than an integer which requires you to look up what that number means in a define. When compiling for 8-bit targets with GCC, you should use the -fshort-enums option so the enum is not allocated in an integer (ie: 16 bits) but may fit in something smaller.

• When defining a macro that is more than (or could be expanded to) more than one line, always include curly brackets. This ensures that if the macro is ever used in an IF statement without such brackets it would not have side effects. Example:

      #define do_something(a, b)  {a = b + 5;\
                                   b = 6 * a;}
      

Global Variable/Function/File Names

The naming convention is based on hierarchy of any item. Underscores denote a change in hierarchy. Thus almost everything which is global starts out with fip_, as they are all part of the fip module. Consider the macro fip_packet_getFromIP6Hdr_nextHeader() :

    fip_packet_getFromIP6Hdr_nextHeader()
     ^    ^         ^             ^
     |    |         |             |
     |    |         |             +---- Operates on the next header field
     |    |         |
     |    |         +------------------ Gets a certain field from the IPv6 header. There may
     |    |                             be a number of macros/functions in the 'getFromIP6Hdr'
     |    |                             series, getting different fields.
     |    |
     |    +---------------------------- Part of the packet buffer module. Should be found in
     |                                  either fip_packet.c or fip_packet.h
     |
     +--------------------------------- FIP is highest-level module  

Include Files

• fip.h should work for most general-purpose code, fip.h should define most commonly-used functions, or include the proper header otherwise

Global Variables / States

• The active packet buffer SHOULD be used to store any message specific states. A OS could thus save the packet buffer when switching threads. You can use the 'scratchpad' of the packet buffer to store extra information about the current message.
• Global variables MUST NOT be used to store message-specific states. These would need to be saved when context switching, which would be complicated. If message-specific states are put on the stack, the OS should at least save the stack during the course of normal processing.