Model for the network stack

Class diagram

A preliminary class diagram can be found in at here:

https://drive.google.com/file/d/0Bw4T8Mqih7-oc2FpN01pMmVPQ0E/view

(can be opened at with the web application draw.io

Use-cases for the packet buffer

Allocate packet

• Use case ID: pkt0001
• Application: Packet buffer
• Use case description: Allocate space for a packet in packet buffer
• Primary actor: packet buffer
• Precondition: —
• Trigger: allocate packet program of packet buffer is started
• Basic flow:
  1. packet buffer checks if space for packet is left
  2. if so: packet buffer allocates packet space
  3. packet buffer marks allocated packet space as processed (pkt0005)
  4. packet buffer returns newly allocated packet
• Alternate flow:
  1. packet buffer checks if space for packet is left
  2. if not: packet buffer signals to caller, that space is not available

Re-allocate packet

• Use case ID: pkt0002
• Application: Packet buffer
• Use case description: Re-sizes allocated space for a packet in packet buffer
• Primary actor: packet buffer
• Precondition: —
• Trigger: reallocate packet program of packet buffer is started
• Basic flow:
  1. packet buffer checks if given packet is in it
  2. if so: packet buffer checks if re-sized packet would fit into the same space
  3. if so: packet buffer re-sizes packet
  4. packet buffer returns original pointer to packet
• Alternate flow:
  • given packet not in packet buffer
    1. packet buffer checks if given packet is in it
    2. if not: pkt0001
  • re-sized packet does not fit into old space
    1. packet buffer checks if given packet is in it
    2. if so: packet buffer checks if re-sized packet would fit into the same space
    3. if not: allocate new packet space (pkt0001)
    4. if new space is available: copy data and headers from old space to new (pkt0004)
    5. remove allocation for old space (pkt0006)
    6. packet buffer returns pointer to new space
  • re-sized packet does not fit into old space and no new space available
    1. packet buffer checks if given packet is in it
    2. if so: packet buffer checks if re-sized packet would fit into the same space
    3. if not: allocate new packet space (pkt0001)
    4. if no new space is available: packet buffer signals to caller, that space is not available

Insert packet

• Use case ID: pkt0003
• Application: Packet buffer
• Use case description: Allocate space for a packet in packet buffer and fill it with given data
• Primary actor: packet buffer
• Precondition: —
• Trigger: insert packet program of packet buffer is started
• Basic flow:
  1. packet buffer allocates packet (pkt0001)
  2. if space available: packet buffer copies given data into allocated space (pkt0004)
  3. packet buffer returns newly allocated packet
• Alternate flow:
  1. packet buffer allocates packet (pkt0001)
  2. if space available: packet buffer signals to caller, that space is not available

Copy packet

• Use case ID: pkt0004
• Application: Packet buffer
• Use case description: Fill a given packet with given data
• Primary actor: packet buffer
• Precondition: —
• Trigger: copy packet program of packet buffer is started
• Basic flow:
  1. packet buffer checks if given packet is in it
  2. if so: packet buffer checks if given data would fit into packet
  3. if so: packet buffer copies given data into allocated space
  4. packet buffer signals success to caller
• Alternate flow:
  • given packet is not in packet buffer
    1. packet buffer checks if given packet is in it
    2. if not: pkt0003
    3. packet buffer signals success or failure of pkt0003 to caller
  • given data is to long for given packet:
    1. packet buffer checks if given packet is in it
    2. if so: packet buffer checks if given data would fit into packet
    3. if not: packet buffer signals to caller that packet space is too small

Hold packet

• Use case ID: pkt0005
• Application: Packet buffer
• Use case description: Increment processing counter of packet
• Primary actor: packet buffer
• Precondition: packet is in packet buffer
• Trigger: hold packet program of packet buffer is started
• Basic flow:
  1. increment processing counter of packet

Release packet

• Use case ID: pkt0006
• Application: Packet buffer
• Use case description: Decrement processing counter of packet
• Primary actor: packet buffer
• Precondition: packet is in packet buffer
• Trigger: release packet program of packet buffer is started
• Basic flow:
  1. decrement processing counter of packet
  2. if processing == 0 remove packet from packet buffer

Use-cases for general network devices

(partly modeled as sequence diagrams at https://drive.google.com/file/d/0Bw4T8Mqih7-oa3VYeFpWMW9zeHM/view?usp=sharing)

Initialize network device

• Use case ID: netdev0001
• Application: RIOT network stack
• Use case description: Initialize a network device
• Primary actor: network device driver
• Precondition: network device driver is known and initialized set statically for network device
• Trigger: initialization program of network device driver is started
• Basic flow:
  1. network device driver sets type of network device
  2. network device driver sets event handler of network device to current thread PID
  3. network device driver sets initial state
  4. network device driver sets initial option values
• Alternate flow: —

Register receive callback to network device driver

• Use case ID: netdev0002
• Application: RIOT network stack
• Use case description: Registers a receive callback to the network device driver to allow for further handling of received data
• Primary actor: network device driver
• Precondition:
  • receive callback is defined
  • network device is initialized (netdev0001)
• Trigger: registration program of network device driver is started
• Basic flow:
  1. network device driver receives receive callback
  2. network device driver checks if space is available to register receive callback
  3. if so network device driver registers receive callback to itself
• Alternate flow:
  1. network device driver receives receive callback
  2. network device driver checks if space is available to register receive callback
  3. if not network device driver inform caller about unavailable space

Unregister receive callback from network device driver

• Use case ID: netdev0003
• Application: RIOT network stack
• Use case description: Unregister a receive callback to the network device driver to prevent further handling of received data as defined by the callback
• Primary actor: network device driver
• Precondition:
  • receive callback is defined
  • network device is initialized (netdev0001)
• Trigger: unregistration program of network device driver is started
• Basic flow:
  1. network device driver receives receive callback
  2. network device driver checks if receive callback is registered
  3. if so network device driver removes receive callback from its registry
• Alternate flow:
  1. network device driver receives receive callback
  2. network device driver checks if receive callback is registered
  3. if not network device driver disregards call silently

Handle event from hardware

• Use case ID: netdev0004
• Application: RIOT network stack
• Use case description: RIOT receives an event from the network device via interrupt and handles it in the context of an event handling thread.
• Primary actor: network device driver
• Precondition:
  • event handler PID is known (see netdev0001)
• Trigger: interrupt to notify about event.
• Basic flow:
  1. Network device driver gets called in ISR by hardware about an event and receives network device as argument.
  2. Network device driver notifies event handler thread of network device from ISR with value identifying the event type.
  3. Event handler thread calls event handler subroutine with identifying value of the network device driver in its own process context.
  4. Network device driver reidentifies event type by given value.
  5. Network device driver handles event in event handler thread's process context.

Receive packet from hardware

• Use case ID: netdev0005
• Application: RIOT network stack
• Use case description: RIOT receives a packet from network device via SPI or similar device
• Primary actor: network device driver
• Precondition:
  • at least one receive callback to network device driver (netdev0002)
  • network device driver knows ID of receive event from network device
  • Packet buffer is initialized
  • event handler PID is known (see netdev0001)
• Trigger: interrupt to notify about RX event.
• Basic flow: 2. Network device driver handles RX event (netdev0004) internally identified as RX_EVENT 5. Network device driver copies received data from network device buffer into packet buffer 6. Network device driver calls receive callbacks
• Alternate flow: —

Send packet to hardware

• Use case ID: netdev0006
• Application: RIOT network stack
• Use case description: RIOT sends a packet to network device
• Primary actor: network device driver
• Precondition:
  • Packet buffer is initialized
  • Packet is in packet buffer Packet buffer
  • network device is initialized (netdev0001)
• Trigger: send program of network device driver is started
• Basic flow:
  1. Network device driver checks destination address length and payload length and they are correct
  2. Network device driver sends radio's header
  3. Network device driver iterates over Packet headers and sends them in-order
  4. Network device driver sends payload data
• Alternate flow:
  • Address length not supported:
    1. Network device driver checks destination address length and payload length and destination address length not supported
    2. Network device driver informs caller that address length is not supported
  • Data length not supported:
    1. Network device driver checks destination address length and payload length and data length not supported
    2. Network device driver informs caller that data length is not supported

Get device option

• Use case ID: netdev0007
• Application: RIOT network stack
• Use case description: Get an option from the network device (e.g. radio channel)
• Primary actor: network device driver
• Precondition:
  • network device is initialized (netdev0001)
• Trigger: get option program of network device driver is started
• Basic flow:
  1. Network device driver checks if option type is supported
  2. if so: network device driver checks available space in given value buffer
  3. if long enough: network device driver resets length of given value buffer to actual length of value
  4. network device driver copies value data into value buffer
• Alternate flow:
  • option type is not supported:
    1. Network device driver checks if option type is supported
    2. if not: network device driver signals that option type is not supported to caller
  • available space in given value buffer is not long enough
    1. Network device driver checks if option type is supported
    2. if so: network device driver checks available space in given value buffer
    3. if too short: network device driver signals to caller that value buffer space is too short

Set device option

• Use case ID: netdev0008
• Application: RIOT network stack
• Use case description: Set an option to the network device (e.g. radio channel)
• Primary actor: network device driver
• Precondition:
  • network device is initialized (netdev0001)
• Trigger: set option program of network device driver is started
• Basic flow:
  1. Network device driver checks if option type is supported
  2. if so: network device driver checks length of given value buffer
  3. if short enough: network device driver copies data from value buffer to option register
• Alternate flow:
  • option type is not supported:
    1. Network device driver checks if option type is supported
    2. if not: network device driver signals to caller that option type is not supported
  • length of given value buffer is too long
    1. Network device driver checks if option type is supported
    2. if so: network device driver checks length of given value buffer
    3. if too long: network device driver signals to caller that value in value buffer would overflow

Get device state

• Use case ID: netdev0009
• Application: RIOT network stack
• Use case description: Get state from the network device (e.g. low-power mode)
• Primary actor: network device driver
• Precondition:
  • network device is initialized (netdev0001)
• Trigger: get state program of network device driver is started
• Basic flow:
  1. network device driver returns current state
• Alternate flow: —

Set device state

• Use case ID: netdev0010
• Application: RIOT network stack
• Use case description: Set state from the network device (e.g. low-power mode)
• Primary actor: network device driver
• Precondition:
  • network device is initialized (netdev0001)
• Trigger: set state program of network device driver is started
• Basic flow:
  1. network device driver checks if given state is supported
  2. if so: network device driver sets new state of device
• Alternate flow:
  1. network device driver checks if given state is supported
  2. if not: network device driver signals to caller that state is not supported

Use-cases for the network stack

Receive IPv4/IPv6 packet

• Use case ID: net0001
• Application: RIOT network stack
• Use case description: Receive an IPv4/IPv6 packet and deliver it to right transport layer protocol
• Primary actor: IPv6 layer
• Precondition:
  • —
• Trigger: IPv6 packet received from MAC layer through network interface
• Basic flow:
  1. IPv6 layer checks if receiving interface is the receiver.
  2. if so: read next header field (NH) of IPv4/IPv6 header.
  3. check if handler for NH is registered (for external NHs: identified by demux_ctx field of NETAPI_CMD_REG command).
  4. if so: hand over to NH handler.
• Alternate flow:
  • Node is not destination of packet
    1. IPv6 layer checks if receiving interface is the receiver
    2. if not: forward packet.
  • No handler for next header registered
    1. IPv6 layer checks if receiving interface is the receiver.
    2. if so: read next header field (NH) of IPv4/IPv6 header.
    3. check if handler for NH is registered.
    4. if not: notify MAC layer about missing NH handler and drop packet.