Introduction

The NetMsgs package provides both build-time and run-time support of networked messaging presented in a format that is both machine architecture independent and language independent. The messages can sent between networked nodes over a communication channel. In the OSI Model, the NetMsgs package supports the Presentation Layer. The lower communication levels and the Application Layer are not in the scope of NetMsgs.

Each packed transmitted and unpacked received message may have an application- layer header followed by a series of zero or more message fields. The message header semantics are not defined here, may contain fields specifying message length, addressing, transaction ids, sequencing, and synchronization fields.

Communicating networked nodes can reside on separate, phyisically distinct hardware, different processor cores on one the physical node, or separate processing threads. The applcation defines the interconnects.

The NetMsgs package provides support for various message encodings and byte orderings as described in following sections.

The NetMsgs package comprises of of three major subpackages detailed below:

NetMsgs XML Specification
Run-Time C Library
NetMsgs Python Package

Minimum Node Architecture

The node architecture may be either a big-endian or little-endian architecture. Other, exotic byte-ordering architectures are not currently supported. It is required that 1, 2, and 4 byte (unsigned) integers and 4 byte floats be supported. For systems that do not support 8 byte (unsigned) integers, 8 byte floating-point numbers, or 8-byte pointers, promotion will be done in software. However, on unpacking, rounding or truncation will occur if the unpacked element exceeds the 4 byte limits.

Floats are expected to be in IEEE 754 32-bit or 64-bit format.

The implementation of the NetMsgs code is light-weight. Therefore, it can be readily ported to embedded processors that may have only 8, 14, or 16 bit word sizes and may only have floating-point emulation.

Messsage Encodings

The NetMsgs package provides support for following message encodings.

Id-Type-Value Messsage Encoding

The Id-Type-Value message encoding is a structured, binary message encoding. The ITV encoding provides a message header plus a field header for each packed field. Fields can be in any order and are identified by a 1 byte id. On the message packing node, any deprecated fields will be skipped. On the unpacking node, any unrecognized fields will be ignored. Deprected field ids should not be reused to avoid misidentification, unless the application implements a message versioning protocol (outside the scope of NetMsgs). See Packed Message Backus-Naur Form for more details on the ITV message encoding.

Both big and small endian byte orderings are supported.

ITV Field Format
Identifier	A 1 byte, (sub)message-unique field id.
Type	A 1 byte, field type (see below)
Value	An n byte field value. Value may contain a subheader

Flat Messsage Encoding

The Flat message encoding is a binary message encoding with the message fields formatted in a fixed order without any identification or type tagging. The fields are all of fixed length. Flat message encodings are idea for communication with embedded nodes over channels such as I²C and serial. See Packed Message Backus-Naur Form for more details on the Flat message encoding.

Both big and small endian byte orderings are supported.

CLI Messsage Encoding

The Command-Line Interface encoding is an ASCII message encoding with messages fields separatated by Inter-Field Separators (usually white space) and terminated by End-Of-Line sequences (usually CR, LF, or CR-LF).

The CLI encoding is planned to be supported at some future time.

Byte Orderings

The NetMsgs package provides support for following message field byte orderings:

Field Byte Orderings
big endian	Field bytes are packed/unpacked Most-Significant Byte first.
little endian	Field bytes are packed/unpacked Least-Significant Byte first.
native	Field bytes are packed/unpacked native node architecture order.

The NetMsgs XML Specification

The application message set is defined from a RoadNarrows NetMsgs XML specification file. NetMsgs XML provides a tight, language-independent mechanism to extend NetMsgs built-in field types and define messsages. Meta-data elements are also available to supply information for language-dependent build-time generation. See NetMsgs XML Format more details.

The Run-Time C library

The libnetmsgs library provides run-time support for applications to provide packing, unpacking, and tracing operations for NetMsgs generated messages.

The library interface is defined in the rnr/netmsgs.h header file.

All libnetmsgs diagnostics logging is at diagnostics level 3.

The NetMsgs Python Package.

The NetMsgs python package serves two functions:

Source Code Generation

From a NetMsgs XML file, language-specific source file(s) can be generated. The executable python script netmsgsgent provides a command-line interface to the NetMsgs modules that generate the source code. See netmsgsgen Man Page for the NetMsg language generation tool manpage.

Typically, the source code dependencies are made in a makefile. An example makefile target:

# NetMsgs XML pattern rule
include/%.h: %.xml
  netmsgsgen --lang=c --xml=$(<) $(@) $(addsuffix .c,$(basename $(<)))

A summary of the supported and planned language-specific source code generation is listed in the table below.

Generated Source Code
Language	Supported	Generated Files
c	yes	xmlfile -> hfile,cfile
python	yes	xmlfile -> pyfile
C++	future	xmlfile -> hfile,cppfile

Run-Time Support

The NetMsgs.NetMsgsLib module supports run-time python packing, unpacking, and tracing operations. See NetMsgs.NetMsgsLib.

Message Built-In Field Types.

NetMsgs built-in field types can be divided into two classes: simple and compound. Simple field types have solitary values (e.g. an integer), while compound types have mulitple fields and/or have extended lengths. Compound types can be nested. Messages are compound types.

Supported built-in field types are detailed below. Developers may readily extend the types by defining them under the <field_types> section element in the XML file.

Simple Types:

XML Ftype Attr		ITV Type		Value		C Mapped Type		Comments
Value	Alias	Code	Hex	IsA	Bytes	Type Specifier	RNR Typedef	Comments
pad		x	0x77	0	1	N/A		Message buffer padded with 0's (see NMFVAL_PAD). No field id or type is present in the buffer. No underlining variable is mapped.
bool		?	0x3f	boolean	1	int	bool_t	0 is false, 1 (non-zero) is true.
char		c	0x63	character	1	char		8-bit ASCII character.
s8	schar	b	0x62	integer	1	signed char		8-bit signed integer.
u8	byte	B	0x42	integer	1	unsigned char	byte_t	8-bit unsigned integer
s16	short	h	0x68	integer	2	short		16-bit signed integer.
u16	ushort	H	0x48	integer	2	unsigned short	ushort_t	16-bit unsigned integer.
s32	int	i	0x69	integer	4	int		32-bit signed integer.
u32	uint	I	0x49	integer	4	unsigned int	uint_t	32-bit unsigned integer.
s64	longlong	q	0x71	integer	8	long long		64-bit signed long long integer. On 32-bit long long machines, the 4 MSB's are padded with zero's when packed, and truncated when unpacked.
u64	ulonglong	Q	0x51	integer	8	unsigned long long	ulonglong_t	64-bit unsigned long long integer. On 32-bit long long machines, the 4 MSB's are padded with zero's when packed, and truncated when unpacked.
f32	float	f	0x66	floating-point number	4	float		32-bit IEEE 754 floating-point number. On 64-bit FPN machines, the 32-bit FPN is rounded down when packed and converted to IEEE 754 64-bit standard when unpacked.
f64	double	F	0x46	floating-point number	8	double		64-bit IEEE 754 floating-pointer number. On 32-bit FPN machines, the 32-bit FPN is converted to IEEE 754 64-bit standard when packed and rounded down when unpacked.
p32	pointer	p	0x6c	pointer	4	(typecasted) void *		32-bit native pointer. On 64-bit pointer machines, the 4 MSB's are truncated when packed and padded with zero's when unpacked.
p64	longpointer	P	0x4c	pointer	8	(typecasted) void *		64-bit native pointer. On 32-bit pointer machines, the 4 MSB's are padded with zero's when packed, and truncated when unpacked.

Compound Types:

XML Ftype Attr		ITV Type		Value		C Mapped Type		Comments
Value	Alias	Code	Hex	SubHeader	Bytes	Type Specifier	RNR Typedef	Comments
string		s	0x73	count	variable	char[]		Field of count ASCII bytes. The terminating null is not packed. A terminating null is appended to the unpacked variable.
struct		{	0x7b	count	variable	struct		Extended or inline structure of count fields.
vtype[]		[	0x5b	count vtype	variable	vtype[]		One-dimensional array of count items of vtype type.

Requirements

librnr	RNR standard libray 1.
xml	Python XML package.
struct	Python packing package.

Supported Platforms

i386	any Linux Intel (backwards) compatible 32-bit architecures
x86_64	any Linux AMD 64-bit architectures
armang	Angstrom Linux Intel XScale PXA Arm architecures.
armpxa	Familiar Linux Intel XScale PXA Arm architecures.
cygwin	Windows systems with installed cygwin.
osx	Mac OS-X architectures

Tested Systems

Fedora Core	Fedora Core 5 and 6 Linux for the i386 and x86_64 architectures.
Ubuntu	Ubuntus 9.10 Linux for the i386 and x86_64 architectures.
Angstrom	Angstrom Linux 2.6 (K-Team KoreBot2 version) for the XScale PXA 255 Arm.
Familiar	Familiar Linux 2.4 (K-Team KoreBot version) for the XScale PXA 255 Arm.
Windows	Windows XP with Cygwin for Intel processors.
Mac	Mac OS-X 10.x for Intel processors.

Todo:

Cross-field conditional field packing/unpacking.

Support disposition deprecated/active at the fielddef level.

Support disposition deprecated/active at the msgdev level.