Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:otlib:ot_utils

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

opentag:otlib:ot_utils [2012/03/26 20:09] (current)
jpnorair created
Line 1: Line 1:
 +====== OT_utils (OTlib) ======
 +[[opentag:​main|OpenTag]] contains some utility functions and features stored in the OT_utils module of [[opentag:​otlib|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 [[opentag:​otlib:​ot_types_h|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;​).
 +<​code>​
 +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);
 +</​code>​
 +
 +==== Timeout Conversion Functions ====
 +[[dash7_mode_2:​main|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 [[http://​en.wikipedia.org/​wiki/​Duff%27s_device|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 [[opentag:​otlib:​ot_platform_h|Platform Module]], or, if available on the [[opentag:​platforms:​main|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''​. ​
 +<​code>​
 +#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
 +</​code>​
  
opentag/otlib/ot_utils.txt ยท Last modified: 2012/03/26 20:09 by jpnorair