SFBConstants.h File Reference

Various constant definitions. More...

#include "SFBTypes.h"
#include "SFBMacros.h"

Include dependency graph for SFBConstants.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.


Good old fashioned pin states
#define HIGH   1
 High, set, logical 1 value.
#define LOW   0
 Low, clear, logical 0 value.
Wiring/Arduino/SFB 'print' method format codes
#define DEC   10
 Print in decimal, signed if negative (in most contexts).
#define HEX   16
 Print in hexadecimal (base 16, using 0-9A-Z), unsigned.
#define OCT   8
 Print in octal (base 8, using 0-7), unsigned.
#define BIN   2
 Print in binary (base 2, using 0-1), unsigned.
#define BYTE   0
 Print a single byte directly, as an unaltered 8 bit value.
#define BESHORT   -1
 (SFB only) Print a short (2 bytes) in big endian (network order)
#define BELONG   -2
 (SFB only) Print a long (4 bytes) in big endian (network order)
#define B36   36
 Print in base 36 ("hexatrigintimal"?, using 0-9A-Z), unsigned.
Wiring/Arduino/SFB pinMode direction modes
#define INPUT   0
 Pin is input, under sketch control.
#define OUTPUT   1
 Pin is output, under sketch control.
#define REFLEX_MODE   2
 (SFB only) Pin is under reflex control
#define HW_MODE   3
 (SFB only) Pin is under hardware control and shouldn't be messed with
SFB physical face indices.
Note these are ALSO the HW UART#'s of corresponding faces!

#define NORTH   0u
 Port number of the North Face.
#define SOUTH   1u
 Port number of the South Face.
#define EAST   2u
 Port number of the East Face.
#define WEST   3u
 Port number of the West Face.
#define FACE_COUNT   4
 The number of physical faces.
SFB 'extended' faces indices.
These codes are valid only in certain contexts (reflex triggering, printing, etc) depending on the specific code.

#define SPINE   4u
 All the spatial faces (NSEW) flow to here.
#define WMEM   5u
 Working memory: internal memorized packets.
#define BRAIN   6u
 SPINE+WMEM flows here: The last stop for reflex responses.
#define ALL_FACES   7u
#define NO_FACES   8u
 Implies no faces.
#define MIN_VIRTUAL_FACE   9u
 Lowest number corresponding to a user-defined 'virtual' face, valid in certain contexts (e.g., facePrintf).
 The number of virtual faces that can be defined.
 The overall count of possible face codes.
 A number that isn't a legal face code in any context.
Wiring/Arduino 'attachInterrupt' modes.
Note that mode 'LOW', meaning interrupt on low level, is not currently supported in the SFB.

#define RISING   0x01
 Interrupt on LOW to HIGH transition.
#define FALLING   0x02
 Interrupt on HIGH to LOW transition.
 Interrupt on either RISING or FALLING.
Wiring/Arduino 'shiftOut' bit orders.
Used by shiftOut().

#define LSBFIRST   0
 Ship the least-significant-bit (LSB) first.
#define MSBFIRST   1
 Ship the most-significant-bit (MSB) first.
SFB tertiary bootloader boot modes
 Boot mode not (yet) known.
#define RED_BOOT_MODE   1
 Red boot.
#define GREEN_BOOT_MODE   2
 Green boot.
#define BLUE_BOOT_MODE   3
 Blue boot.
#define MAX_BOOT_MODES   4
 Number of boot modes.
Packet flags.
The value returned by packetFlags() is the bitwise-OR of these values.

Warning: The PK_OVERRUN, PK_PARITY, PK_FRAMING, and PK_BREAK flag definitions match the corresponding conditions in LPC hardware registers (UxLSR) and so must not be changed!

#define PK_DELETED   0x01
 Packet deleted in buffer, do not dispatch (NYI).
#define PK_OVERRUN   0x02
 Packet byte(s) lost due to an overrun condition.
#define PK_PARITY   0x04
 Packet byte(s) had a parity error.
#define PK_FRAMING   0x08
 Packet byte(s) had a framing error.
#define PK_BREAK   0x10
 Break interrupt occurred during packet byte(s).
#define PK_BUFFER   0x20
 Packet exceeded max length, or packet buffer space exhausted.
#define PK_BAD_ESCAPE   0x40
 Packet had invalid escaping on some byte(s).
#define PK_RESERVED8   0x80
 Reserved; should be zero; should not be read.
Packet flag combinations
 If nonzero, some hardware UART per-byte error(s) occurred.
 If nonzero, some protocol or packet level error(s) occurred.
 If nonzero, some error(s) of any kind occurred in the packet.
Sizes and limits
#define MAX_PACKET_LENGTH   252
 The maximum size of a packet (just the raw packet data itself, not including packet framing overhead).
 Size of a standalone (non-FIFO) buffer for a single packet.
#define BYTE_BUFFER_BITS   10

Detailed Description

Various constant definitions.

David H. Ackley.
(C) 2008 All rights reserved.
Code License:
The GNU Lesser General Public License
License Note:
All code samples shown in documentation are placed into the public domain.

Define Documentation

#define ALL_FACES   7u


Special code, valid in certain contexts (e.g., facePrint())


#define BLUE_BOOT_MODE   3

Blue boot.

#define BRAIN   6u

SPINE+WMEM flows here: The last stop for reflex responses.

#define FACE_COUNT   4

The number of physical faces.

Although it is perfectly legal and acceptable to iterate over the physical faces using FACE_COUNT in the familiar way:

     for (u32 face = 0; face < FACE_COUNT; ++face) ..use face..;

because there are several different ranges of "more or less real" faces (see, e.g., MAX_FACE_INDEX), the SFB library codebase itself more often writes:

     for (u32 face = NORTH; face <= WEST; ++face) ..use face..;

to stress the specific range of face values being visited. Because the numeric values of NORTH, SOUTH, EAST, and WEST map directly to the underlying UART hardware registers, it is fair to consider the iteration order of the physical faces as "frozen in stone".

#define GREEN_BOOT_MODE   2

Green boot.

#define MAX_BOOT_MODES   4

Number of boot modes.


The overall count of possible face codes.

This includes the FACE_COUNT physical faces, the "extended face codes" such as BRAIN, and the up to VIRTUAL_FACE_COUNT "virtual faces".

#define MAX_PACKET_LENGTH   252

The maximum size of a packet (just the raw packet data itself, not including packet framing overhead).

There are a lot of arguments going into the MAX_PACKET_LENGTH (MPL) value, favoring big (+), small (-), and other (o):

  • o Artificial limits are bad; the only limit should be total RAM.

  • + Failing that, MPL should be as big as possible.

  • o Total RAM _is_ an artificial limit like any other. And for a packet communications protocol, there should always be _some_ size that's guaranteed to fit; MPL is really a 'minimum maximum size' guarantee.

  • - RAM is a precious resource in the SFB with many demands on it, and the SFB library minimum RAM requirements just for packet buffers grows as 9MPL. (4 UART * 2MPL per UART buffer + 1 MPL shared dispatch buffer).

  • + MPL should be at _least_ 270 or so, because 256 is the minimum size of an IAP 'Copy RAM to flash' operation, so a packet should have enough room for 256 data bytes plus addressing, checksum, and packet overhead.

  • - Well, that would be nice, but unfortunately the current scheme breaks if MPL is 252 or higher, because then a packet length doesn't fit in a u8 and can't be (easily) stored in the data stream as it currently is.

  • + Well, gah, you could halfword-align the packet header in the packet buffer, at a cost of at most one more byte per packet of overhead, and then manipulate the packet length in place via *(u16*) stuff. Probably wouldn't cost a cycle, in the fast path, on a nice 32 bit machine like this. So that's a phony argument for MPL size restriction.

  • + And, furthermore, for no more than two bytes more per packet, more you could guarantee that every packet would start out word-aligned, which could then be counted on during packet design. So that, for example, would allow dispatch code to do a 'Copy RAM to Flash' _directly_ from the packet buffer

  • o (Except that, gah, it turns out the frickin IAP routines require it be _user_ RAM for 'Copy RAM to Flash' operations! So we _cannot_ burn directly from the packet buffer, regardless of packet size or alignment!)

UPDATE Mon Apr 13 07:24:13 2009 Note: 288 is the maximum size that allows 7 max-length packets to fit in a 2K buffer (including the 4 byte per packet overhead).

UPDATE Thu Jul 2 03:23:46 2009 Note: Considering that we cannot, it turns out, burn directly from packet memory anyway (not without trying to bypass IAP anyway), we _have_ to have an (at least) 256 byte buffer in fastram, which means there's no essential programming advantage to a packet size big enough to hold 256 data bytes plus overhead all at once. We could reduce the programming data unit to 128 bytes per packet with little added inefficiency.

Given that, and given the fact that 288 is so minimally larger than 252, we have to ask whether the advantages of going a handful a bytes over 252 are worth it. In particular, if we cut back to max 252, we can go back to a u8 for length, which frees up an entire byte in the packet header -- which is room enough for a whole nother length field.

And with a second length field, we could add a 'read index' or 'cursor' to a packet, allowing a packet to be treated as an input stream, with all the extreme handiness and clean code that offers. In particular, we could have a reasonably non-gross packetScanf..

Hmm. Hmm...

But we'd have to rewrite the programming packet code down to 128 data bytes before we could even try it..

UPDATE Fri Jul 3 09:31:22 2009 Well we did that and it wasn't that bad; and now we've really gone for it: We've abandoned the four byte alignment requirement as well. After all, that was only really there to facilitate embedding structs in packets, but because of endianness that's frankly something we don't want to encourage. Things like facePrintf() (and the to-come packetScanf()) is the way.

So now the MPL doesn't even need to be a multiple of four. But leaving it at 252 since that's the size that produces most complete worst-case use of power-of-2 buffer sizes.

#define NO_FACES   8u

Implies no faces.

Special code, valid in certain contexts (e.g., facePrint())


A number that isn't a legal face code in any context.

#define RED_BOOT_MODE   1

Red boot.


Size of a standalone (non-FIFO) buffer for a single packet.

Note that since a single packet buffer doesn't wrap (unlike the main rolling buffers), for a standalone single packet buffer we need three extra words beyond the packet data size: One for the header at the front, one to guarantee room for null-termination at the back, and one more so that we can accomodate arbitrary packet offsets and still use word-aligned copying rather than going byte by byte.

#define SPINE   4u

All the spatial faces (NSEW) flow to here.


Boot mode not (yet) known.


The number of virtual faces that can be defined.

Legal virtual face codes start at MIN_VIRTUAL_FACE and end just below MAX_FACE_INDEX. Increased from 16 to 32 as of 0.9.18

#define WMEM   5u

Working memory: internal memorized packets.


Generated on Fri Apr 22 06:55:02 2011 for SFB by doxygen 1.5.9