Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:otlib:ot_utils

OT_utils (OTlib)

OpenTag contains some utility functions and features stored in the OT_utils module of OTlib. These are functions and features that allow tighter (or better) code, which simply do not belong anywhere else.

Functions

OT_utils.h specifies a few functions. Most of these are actually just null callbacks – in other words, callbacks that return nothing but which can be assigned to prevent segmentation faults via null memory access. If a callback function pointer is not assigned to a valid function and it gets called, bad things happen.

Null Callbacks

The callback function pointer types defined in OT_types.h have null callback functions implemented in OT_utils. The prototypes are listed below. There is no point in ever calling these functions directly, because they do not do anything. Assign them to callbacks that are unused, (e.g. unused_signal = &otutils_sig_null;).

void otutils_null(void);
void otutils_sig_null(ot_int a);
void otutils_sig2_null(ot_int a, ot_int b);
void otutils_sigv_null(void* a);

Timeout Conversion Functions

DASH7 Mode 2 uses a 1-byte exponent+mantissa format for timeouts in several places (namely channel scanning and response window control via M2QP). The exponent (EXP) is a 3 bit number stored in b6:4, and the mantissa (MANT) is a 4 bit numebr stored in b3:0. b7 is a control bit that is used by the protocol in different ways, but which is discarded when calculating the timeout. The expression is piece-wise:

timeout = { MANT            : EXP=0 }
          { (4^EXP)(MANT+1) : EXP>0 }

OT_utils implements two functions, one for turning an encoded exp+mant value into a timeout value, and one for turing a timeout value into an encoded exp+mant value. The usage should be self-explanatory to any C developer.

ot_u16 otutils_calc_timeout(ot_u8 timeout_code);
ot_u8 otutils_encode_timeout(ot_u16 timeout_ticks);

Macros

OT_utils also implements a few macros in OTlib/OT_utils.h for simplifying some tasks that are common to OpenTag and embedded projects in general.

Duff's Devices

8 and 16-way Duff's Devices are implemented as macros. If you are thinking about using one of these to improve the performance of a memory copy, use platform_memcpy() instead. platform_memcpy() is implemented as an 8-way Duff Device in the Platform Module, or, if available on the platform, via a DMA (which will yield maximum performance). However, since they are macros, you can load in C expressions as arguments, in which case the Duff's Devices can be used for any type of clever loop unrolling.

DUFFLOOP_16(aCount, aAction)
DUFFLOOP_8(aCount, aAction)

Binary Value Shortcuts

Embedded developers know that sometimes it is nice to use binary instead of hex or decimal. OT_utils has definitions for all binary values between 0 and 255 – any number of bits. The syntax is bXXX, where XXX is some binary string. The binary string can be 1 to 8 bits in length. A snippet of OT_utils.h is shown below, to give a more direct example. There are, in total 511 definitions from b0 to b11111111.

#define b1010 10
#define b1011 11
#define b1100 12
#define b1101 13
#define b1110 14
#define b1111 15 

#define b00000 0
#define b00001 1
#define b00010 2
#define b00011 3
opentag/otlib/ot_utils.txt · Last modified: 2012/03/26 20:09 by jpnorair