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.

Defines
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
	Implies NORTH+SOUTH+EAST+WEST.
#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).
#define	VIRTUAL_FACE_COUNT   32
	The number of virtual faces that can be defined.
#define	MAX_FACE_INDEX   (MIN_VIRTUAL_FACE+VIRTUAL_FACE_COUNT)
	The overall count of possible face codes.
#define	NOT_A_FACE   (MAX_FACE_INDEX)
	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.
#define	CHANGING   ((RISING)|(FALLING))
	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
#define	UNKNOWN_BOOT_MODE   0
	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
#define	PK_BYTE_ERROR   (PK_OVERRUN|PK_PARITY|PK_FRAMING|PK_BREAK)
	If nonzero, some hardware UART per-byte error(s) occurred.
#define	PK_PACKET_ERROR   (PK_BUFFER|PK_BAD_ESCAPE)
	If nonzero, some protocol or packet level error(s) occurred.
#define	PK_BROKEN   (PK_PACKET_ERROR|PK_BYTE_ERROR)
	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).
#define	SINGLE_PACKET_BUFFER_SIZE_WORDS   (((MAX_PACKET_LENGTH)>>2)+1)
	Size of a standalone (non-FIFO) buffer for a single packet.
#define	SINGLE_PACKET_BUFFER_SIZE_BYTES   (SINGLE_PACKET_BUFFER_SIZE_WORDS<<2)
#define	BYTE_BUFFER_BITS   10
#define	BYTE_BUFFER_BYTES   (1<<BYTE_BUFFER_BITS)
#define	BYTE_BUFFER_MASK   (BYTE_BUFFER_BYTES-1)

---

Detailed Description

Various constant definitions.

Author:

David H. Ackley.

Date:

(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

Implies NORTH+SOUTH+EAST+WEST.

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

Examples:

eeprom4.cpp.

#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.

#define MAX_FACE_INDEX   (MIN_VIRTUAL_FACE+VIRTUAL_FACE_COUNT)

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())

#define NOT_A_FACE   (MAX_FACE_INDEX)

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

#define RED_BOOT_MODE   1

Red boot.

#define SINGLE_PACKET_BUFFER_SIZE_WORDS   (((MAX_PACKET_LENGTH)>>2)+1)

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.

#define UNKNOWN_BOOT_MODE   0

Boot mode not (yet) known.

#define VIRTUAL_FACE_COUNT   32

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.

Examples:

fifthdirection.cpp.