Support for EUI-64 retrieval. More...

#include <bsp430/core.h>

Data Structures
union	uBSP430eui64

struct	uBSP430eui64::as48

Macros
#define	configBSP430_EUI64 0

#define	BSP430_EUI64 (configBSP430_EUI64 - 0)

#define	configBSP430_EUI64_USE_PLATFORM 1

#define	configBSP430_EUI64_USE_GENERIC 1

#define	BSP430_EUI64_PERM 0

#define	BSP430_EUI64_RANDOM 1

#define	BSP430_EUI64_STOLEN 2

#define	BSP430_EUI64_MASK_GROUP 0x01

#define	BSP430_EUI64_MASK_LOCAL 0x02

#define	BSP430_EUI64_IS_NULL(h_)

#define	BSP430_EUI64_IS_INVALID(h_)

#define	BSP430_EUI64_INVALIDATE(h_)

#define	BSP430_EUI64_AS_TEXT_LENGTH sizeof("01-02-03-04-05-06-07-08")

Typedefs
typedef union uBSP430eui64	uBSP430eui64

typedef uBSP430eui64 *	hBSP430eui64

Functions
int	iBSP430eui64 (hBSP430eui64 eui64)

int	iBSP430eui64Parse (const char *cfp, size_t len, hBSP430eui64 eui64)

char *	xBSP430eui64AsText (hBSP430eui64 eui64, char *buffer)

Detailed Description

Support for EUI-64 retrieval.

An Extended Unique Identifier in 64-bits (EUI-64) is a 64-bit value intended to uniquely identify a device. In some cases uniqueness may be restricted to instances of a given device type. These values are commonly used for interface identifiers in IPv6 and other situations where it is necessary to distinguish between nodes in a system.

Note: The EUI-64 guidelines specify two distinct null values: all bits zero and all bits 1. BSP430 standard practice is to denote the all-zero version as a null EUI-64 which no data has yet been surveyed, and the all-ones version as invalid to denote inability to obtain EUI-64 information. Thus, a null-initialized object containing a uBSP430eui64 object is cleared and ready for assignment, perhaps to an invalid value.

See also: https://standards.ieee.org/develop/regauth/tut/eui64.pdf

Homepage: http://github.com/pabigot/bsp430

Copyright: Copyright 2013-2014, Peter A. Bigot. Licensed under BSD-3-Clause

Macro Definition Documentation

#define BSP430_EUI64 (configBSP430_EUI64 - 0)

Indicate that the EUI-64 interface is available on the platform. This is normally set to reflect whether configBSP430_EUI64 was requested, but it may be explicitly set to false by the platform if it does not support the EUI-64 functionality.

This flag is defined only if configBSP430_EUI64 is true.

Dependency:: configBSP430_EUI64

Platform-Based Value:: Undefined here; include <bsp430/platform.h> to obtain the correct value of this macro.

#define BSP430_EUI64_AS_TEXT_LENGTH sizeof("01-02-03-04-05-06-07-08")

Expected length for a buffer used by xBSP430eui64AsText().

This macro may be used to allocate such a buffer.

#define BSP430_EUI64_INVALIDATE ( h_ )

Value:

do { \
    hBSP430eui64 const h = (h_);         \
    h->ints[0] = -1;                     \
    h->ints[1] = -1;                     \
    h->ints[2] = -1;                     \
    h->ints[3] = -1;                     \
  } while (0)

Reset an EUI-64 to the distinct identifier with all bits set.

This is suitable when it is necessary to represent that the EUI-64 is invalid, most likely because the device does not

#define BSP430_EUI64_IS_INVALID ( h_ )

Value:

((-1 == (h_)->ints[0])    \
                                     & (-1 == (h_)->ints[1])  \
                                     & (-1 == (h_)->ints[2])  \
                                     & (-1 == (h_)->ints[3]))

Test whether an EUI-64 is the distinct identifier with all bits set.

See also: BSP430_EUI64_INVALIDATE()

#define BSP430_EUI64_IS_NULL ( h_ )

Value:

((0 == (h_)->ints[0])    \
                                  & (0 == (h_)->ints[1])  \
                                  & (0 == (h_)->ints[2])  \
                                  & (0 == (h_)->ints[3]))

Test whether an EUI-64 is the distinct identifier with all bits clear

#define BSP430_EUI64_MASK_GROUP 0x01

Bit mask for first octet in canonical-order EUI-64, identifying the individual/group marker. The bit is set to indicate group, and cleared to indicate individual.

#define BSP430_EUI64_MASK_LOCAL 0x02

Bit mask for first octet in canonical-order EUI-64, identifying the universal/local marker. The bit is set to indicate local, and cleared to indicate universal.

#define BSP430_EUI64_PERM 0

Value indicating stored EUI-64 is valid and was permanently assigned by something that guarantees uniqueness within the platform.

#define BSP430_EUI64_RANDOM 1

Value indicating stored EUI-64 was randomly generated. Uniqueness is not guaranteed. If this value was returned by iBSP430eui64(), there is no guarantee that a subsequent invocation of the function will return the same EUI-64.

#define BSP430_EUI64_STOLEN 2

Value indicating stored EUI-64 was generated from non-random data but may not be unique.

#define configBSP430_EUI64 0

Define to a true value to indicate intent to use the EUI-64 interface.

C Preprocessor Only:: This macro may have a value that restricts its use to C preprocessor conditional directives.

Defaulted:: The value here is superseded by previously encountered definitions.

#define configBSP430_EUI64_USE_GENERIC 1

Define to a true value to use the generic EUI-64 infrastructure.

The utility/eui64 module provides a default implementation of iBSP430eui64() that generates a value by hashing bytes from the TLV structures or possibly other device-specific data. This is used as the implementation when configBSP430_EUI64_USE_PLATFORM is true but the platform does not provide an alternative implementation.

C Preprocessor Only:: This macro may have a value that restricts its use to C preprocessor conditional directives.

Defaulted:: The value here is superseded by previously encountered definitions.

#define configBSP430_EUI64_USE_PLATFORM 1

Define to a true value to use the platform-provided EUI-64 infrastructure.

Many platforms will provide an implementation of iBSP430eui64(), either the common one that creates a value from device-specific calibration data or a custom one derived from available peripherals like a DS18B20. If this macro is defined as false by the application these platform-provided implementations will be omitted during builds, allowing the application to provide its own implementation.

Note: If you define this to 0 be sure to define MODULE_EUI64 in your application Makefile to be empty or the name of the source file that provides the function.

C Preprocessor Only:: This macro may have a value that restricts its use to C preprocessor conditional directives.

Defaulted:: The value here is superseded by previously encountered definitions.

Typedef Documentation

typedef uBSP430eui64* hBSP430eui64

A handle for an EUI64.

typedef union uBSP430eui64 uBSP430eui64

A type holding the EUI-64 in canonical form.

Function Documentation

int iBSP430eui64 ( hBSP430eui64 eui64 )

Obtain an EUI-64 for the board.

This routine is provided by the platform implementation and returns a 64-bit value consistent with IEEE EUI-64 standards. Whether the returned value is a valid EUI-64 or is (partially) randomly generated depends on the platform. The default implementation generates an EUI-64 by performing an XOR of whatever flash region contains device-specific values such as calibration constants. If successful this EUI-64 will characterized as BSP430_EUI64_STOLEN.

The value returned by this function may be recalculated on each call. Under normal circumstances the function should be invoked once and the eui64 contents retained for the life of the program.

Note: This is an EUI-64, not the modified EUI-64 expected by Appendix A of RFC 4291. To convert between them invert BSP430_EUI64_MASK_LOCAL.

Parameters

eui64 a pointer to a memory location into which the EUI-64 will be written.

Returns: A negative value to indicate an error, or one of BSP430_EUI64_PERM, BSP430_EUI64_RANDOM, or BSP430_EUI64_STOLEN.

Dependency:: BSP430_EUI64

int iBSP430eui64Parse	(	const char *	cfp,
		size_t	len,
		hBSP430eui64	eui64
	)

Parse a canonical-form EUI-64.

This routine recognizes eight octets separated by dashes as an EUI-64. Each octet is expressed by zero, one, or two hexadecimal digits; if zero digits are present, the octet is given the value 0.

For example, the string "1-2--a-bc-d-32-" is translated into the EUI-64 with canonical form 01-02-00-0A-BC-0D-32-00.

Such a routine may be useful in conjunction with Extracting Data from User Input.

Parameters

cfp	pointer to text supposedly expressing an EUI-64
len	number of bytes of text that belong to the EUI-64
eui64	where the extracted value should be stored

Returns: 0 if the parsing was successful and the value stored; a negative value if the text was syntactically invalid.

char* xBSP430eui64AsText	(	hBSP430eui64	eui64,
		char *	buffer
	)

Convert an EUI64 to its canonical text representation.

Parameters

eui64	the EUI64 value to be converted
buffer	a sequence that can hold at least BSP430_EUI64_AS_TEXT_LENGTH characters

Returns: buffer if successful, or a null pointer if eui64 is null.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation