Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:otlib:buffer

Buffer Module (OTlib)

The Buffer Module is very simple. It is used by OpenTag to reserve buffer data, usually FIFOs, for all the I/O processes that OpenTag needs to do. When configuring OpenTag at compile-time, a certain amount of total SRAM will go to the buffer space, and the Buffer Module will break it up into the necessary sub-buffers at runtime initialization (i.e. at startup).

Buffers

The Buffer Module references the Queue Module, as the “Queue” is the basic data structure used by OpenTag to manage FIFOs. The Queue is specifically designed to buffer protocol data.

Queues Declare by Buffer Module

  • RX (rxq): DASH7 RX FIFO
  • TX (txq): DASH7 TX FIFO
  • Dir In (dir_in): Directive Input pipe
  • Dir Out (dir_out): Directive Output pipe

RX & TX Queues

The DASH7 RX & TX queues should be self-explanatory. Each one is designed to hold one frame of RX or TX data, and thus shall be at least 127 bytes in length. Typically, RX and TX queues are 256 bytes in length, meaning that the RX+TX queue system requires 512 bytes of SRAM. For certain devices, such as remote endpoints, these will be the only queues the Buffer Module implements.

Directive Queues

The Directive Queues are used for various purposes, but in all cases they are involved in multi-processing. They are, effectively, process pipes. For example, MPipe uses them for client-server communication, and DASH7 can use the Dir Out queue for assembling multi-frame packets. Additionally, application processes implemented by the user – which may running entirely in parallel with OpenTag and have no hooks to OpenTag functions or data elements – can supply API commands into the Dir Out queue. The Dir In queue is primarily for Mpipe for saving incoming data.

Data Requirements

Queue Min Typ Max Notes
RX 127 256 256 Required by all devices that receive DASH7 packets
TX 127 256 256 Required by all devices that transmit DASH7 packets
Dir In 261 264 Required by devices that have MPipe
Dir Out 261 264 Required by devices that have MPipe, support multi-frame packets, or otherwise use the ALP API

The RX & TX queues never need to be larger than 256 bytes – making them larger than this is superfluous, because DASH7 does not use frames larger than 255 bytes. The Directive queues, however, can benefit from being large. If you want to support large multiframe packets or long streams of API commands passed over MPipe, you can increase the size of the Dir Out. Dir In does not really need to be larger than 261 bytes (implemented often as word-aligned 264), but for unusual implementations of MPipe, it could made larger.

Examples: A CC430F5137 gateway implementation will often use 256+256+262+262=1036 bytes for the buffer (MSP430 has 2 byte words). An STM32L151 gateway has more SRAM and it might use 256+256+264+2296=3072 bytes for the Buffer Module.

Overlapping Dir In, Dir Out Buffers

In the common interface, the Dir In and Dir Out buffers actually overlap (they occupy the same space). Thus the Dir In and Dir Out Queues may define the boundaries fluidly. For example, there are circumstances where MPipe can be blocked, and thus the Dir Out Queue can use some extra buffer memory that would otherwise go unused. Alternatively, in a system that gets plugged-in occasionally to use MPipe, but otherwise is detached and has no connection to MPipe, the Dir In buffer space will not be wasted. The advantage of this method is most profound on memory limited systems like the CC430.

OTlib/buffers.h

Here is the code for buffers.h. You may also refer to the doxygen code documentation.

#include "OT_types.h"
#include "OT_config.h"
#include "queue.h"


/** Buffer Allocation definitions
  * These may also be defined in OT_config.h unless otherwise noted.  The
  * definitions in OT_config.h take priority over these.
  */

#define BUF0_ALLOC  256
#define BUF1_ALLOC  256
#define BUF2_ALLOC  (OT_FEATURE(BUFFER_SIZE) - 512)


/// Buffer Partitions
/// Number of partitions allowed is the total allocated size divided by 256.
/// Partitions, hence, are always 256 bytes.
#define BUF_PARTITIONS      (OT_FEATURE(BUFFER_SIZE)/256)
#define BUF_PARTITION(VAL)  (otbuf+(256*VAL))


// Legacy defines for certain hacks that may still be in the codebase. 
// Usage of these is deprecated
#define txq_data    (otbuf)
#define rxq_data    (otbuf+BUF0_ALLOC)


/// Common start points for queues in the buffer
#define ot_buf0     (otbuf)
#define ot_buf1     (otbuf+BUF0_ALLOC)
#define ot_buf2     (otbuf+BUF0_ALLOC+BUF1_ALLOC)


/// Main Buffer (encapsulates buffers for all supported Queues)
extern ot_u8 otbuf[OT_FEATURE(BUFFER_SIZE)];


#if (OT_FEATURE(SERVER) == ENABLED)
    /// Required Queues (on server side): rxq and txq are used for DASH7 I/O
    extern Queue rxq;
    extern Queue txq;
#endif

#if (   (OT_FEATURE(NDEF)  == ENABLED) || \
        (OT_FEATURE(ALP)   == ENABLED) || \
        (OT_FEATURE(MPIPE) == ENABLED) )
    /// Directive Queues: optional, used for ALP processing and usually also 
    /// NDEF record usage (if enabled)
    extern Queue dir_in;
    extern Queue dir_out;
#endif




/** @brief Initializes the System Queues to defaults
  * @param none
  * @retval none
  * @ingroup Buffers
  *
  * The System Queues (rxq, txq, dir_in, dir_out) can be manipulated to point
  * to different data elements during the course of their usage.  This function
  * will reset them to their defaults.  Use it whenever you want to reset the
  * queues or during boot-up.
  */
void buffers_init();
opentag/otlib/buffer.txt · Last modified: 2012/03/08 20:33 by jpnorair