Stack

Stack Organization

Overview

Protocol layers are wired together to form a stack. Click on the image to the right to see the stack organization diagram of the OpenWSN protocol stack. Send functions are used to push packets down the stack; Receive functions to pull them up. The bytes of a packet live in the OpenQueue component. A packet is a variable of type OpenQueueEntry_t and is defined in openwsn.h; components pass a pointer to an OpenQueueEntry_t variables in the Send and Receive functions.

OpenQueueEntry_t and metadata

An OpenQueueEntry_t consists of the actual bytes in the packet, plus a number of metadata fields. Metadata is used for an upper (resp. lower) layer to set parameters a lower (resp. upper) layer will need, when sending a packet down (resp. up) the stack. One example is that the MAC layer sets l1_channel to instruct the driver about which channel it needs to transmit the packet on. Another example is that RPL layer specifies l2_nextORpreviousHop, indicating to the MAC layer to which neighbor this packet needs to go.

No parameters are sent in the Send interfaces other than the pointer to the OpenQueueEntry_t. All Send interfaces have the same two functions:

error_t send    (OpenQueueEntry_t* msg);
void    sendDone(OpenQueueEntry_t* msg, error_t error);

Similarly, when receiving:

void receive(OpenQueueEntry_t* msg);

Instead of adding and adding parameters in the interface, they go as metadata as are attached to the OpenQueueEntry_t variable. A packet is thereby self-contained: a component should never have to maintain state linked to a particular packet.

Metadata fields have names which indicates which layer should use them, from l7_ for the application to l1_ for the radio driver. Some field are used for administration by all the layers:

• creator indicates the component which created this packet, i.e. which requested an unused OpenQueueEntry_t to the OpenQueue component. When sending a packet down the stack, the convention is that only the creator of a packet can free that packet, i.e. instruct the OpenQueue component it doesn't need it anymore. Typically, OpenQueueEntry_t variables will be created by all application-layer component when sending a packet, or by the drivers when receiving.
• owner indicates the components which currently holds the packet. The convention is that a component can only change the content of an OpenQueueEntry_t if it is currently the owner.
• The packet part of the OpenQueueEntry_t holds the actual bytes of the packet. Because OpenWSN does not allow for dynamic memory allocation, packet is the maximal allowed size. payload is a pointer to the first used by in packet; length indicates how many bytes are used.

Adding/removing protocol headers

When a component requests an unused OpenQueueEntry_t from the OpenQueue component, payload points to the end packet and length is zero. If a components needs to add n bytes of data to the packet pkt, it calls:

packetfunctions_reserveHeaderSize(OpenQueueEntry_t* pkt, uint8_t header_length)

This function modifies the payload and length fields of the OpenQueueEntry_t to make space for a header of header_length bytes. After this function is called, you can write a header starting at the byte pointed at by pkt->payload, of exactly header_length bytes.

Similarly, when a components needs to remove n bytes of data from the packet pkt, it does:

void packetfunctions_tossHeader(OpenQueueEntry_t* pkt, uint8_t header_length)

In practice, fixed-length header might be defined in a header file. The TCP header, for example, is defined in tcp.h as

typedef struct {
   uint16_t source_port;
   uint16_t destination_port;
   uint32_t sequence_number;
   uint32_t ack_number;
   uint8_t  data_offset;
   uint8_t  control_bits;
   uint16_t window_size;
   uint16_t checksum;
   uint16_t urgent_pointer;
} tcp_ht;

tcp.c, which implements the TCP protocol, reserves space for the header by calling:

packetfunctions_reserveHeaderSize(msg,sizeof(tcp_ht));

Story of a packet

This section tells the story about what each layer does in the OpenWSN implementation, including which layers read and write metadata. There are two parts: one which details what happens when a packet is generated at the application layer, and travels down the stack until the drivers; one the other way.

Each of these sections end with a table stating which layer write (w) or read (r) which metadata.

• Down the stack*

• Application
  • gets a free OpenQueueEntry_t
  • fills in the following metadata:
    • creator (to itself)
    • owner (to itself)
    • l4_source_port (to be used by self to route to appropriate L4)
    • l4_destination_port (to be used by L4 to build header)
    • l3_destinationORsource ADDR_128B (to be used by RPL to find next hop)
  • fills in the payload according to its own format
  • sends to L4
• L4(TCP or UDP)
  • fills in the following metadata:
    • owner (to itself)
    • l4_payload (to remember where the l4 payload starts, in case needs to resend)
    • l4_length (to remember where the l4 payload starts, in case needs to resend)
  • adds transport header based on:
    • l4_source_port (filled in by Application)
    • l4_destination_port (filled in by Application)
  • sends to RPL
• RPL
  • fills in the following metadata:
    • owner (to itself)
    • l2_nextORpreviousHop (which is obtains by calling getNextHop)
  • sends to IPHC
• IPHC
  • fills in the following metadata:
    • owner (to itself)
  • add 6LoWPAN header
  • sends to RES
• RES
  • fills in the following metadata:
    • owner (to itself)
    • l2_frameType (to data if from above, to beacon if from Neighbors)
  • sends to MAC
• MAC(IEEE802154E or stupidMAC)
  • fills in the following metadata:
    • owner (to itself)
    • l2_retriesLeft
    • l1_txPower
    • l1_channel
  • adds the MAC header based on:
    • l2_nextORpreviousHop (filled in by RPL)
    • l2_frameType (filled in by RES)
  • sends to drivers
• drivers
  • does not put owner to itself to allow MAC to retransmit (in case something goes wrong in the drivers)
  • configures the radio according to:
    • l1_txPower (set by MAC)
    • l1_channel (set by MAC)

• Up the stack*

• drivers
  • gets a free an OpenQueueEntry_t
  • fills in the following metadata:
    • creator (to itself)
    • owner (to itself)
    • l1_rxTimestamp (for the MAC layer to possibly resynchronize)
    • l1_crc (in fact always true as in the current drivers a packet with a false CRC is discarded)
    • l1_lqi (not used in upper layers, for the moment)
    • l1_rssi (used by the Neighbors components to select stable neighbors)
  • sends to MAC
• MAC(IEEE802154E or stupidMAC)
  • fills in the following metadata:
    • owner (to itself)
    • l2_frameType
    • l2_nextORpreviousHop to the 64b/16b address of the previous hop
  • if IEEE802.15.4E, resynchronizes using l1_rxTimestamp filled in by the drivers
  • removes the MAC header
  • sends to RES
• RES
  • fills in the following metadata:
    • owner (to itself)
  • filters using l2_frameType filled in by MAC
  • sends to IPHC
• IPHC
  • fills in the following metadata:
    • owner (to itself)
  • inflates the IPv6 header
  • removes the 6LoWPAN header
  • sends the message with the inflated IPv6 header to RPL
• RPL
  • fills in the following metadata:
    • owner (to itself)
    • l4_protocol (according to the next_header field in the inflated IPv6 header provided by the IPHC componnent)
  • sends to the appropriate L4 according to l4_protocol
• L4(TCP or UDP)
  • fills in the following metadata:
    • owner (to itself)
    • l4_source_port
    • l4_destination_port
  • remove the L4 header
  • sends to App
• Application
  • discards the packet