HAL Unique-ID

This section contains definitions for supporting the optional Unique-ID access in an architecture neutral fashion. Not all variants, or platforms, will provide a mechanism for accessing device-specific Unique-ID data, in which case the macros as documented in this section will not be defined.

The required definitions are normally referenced via the header file cyg/hal/hal_io.h. This file itself contains macros that are generic to the configured architecture. If there are variant or platform specific Unique-ID access macros then these will be found in cyg/hal/var_io.h and cyg/hal/plf_io.h in the variant or platform HALs respectively. These files are included automatically by the architecture header, so need not be included explicitly.

HAL_UNIQUE_ID_LEN

HAL_UNIQUE_ID_LEN( CYG_WORD32 maxlen )

This macro, when defined, provides a mechanism for ascertaining the maximum number of bytes of Unique-ID data available.

For most implementations this macro will return a build-time constant value in the passed maxlen parameter, but some systems may have a run-time calculated limit.

HAL_UNIQUE_ID

HAL_UNIQUE_ID( CYG_BYTE *buffer, CYG_WORD32 bufflen )

This macro, when defined, provides a mechanism for filling the passed buffer parameter with upto bufflen bytes of Unique-ID data. If the implementation provides fewer that bufflen bytes of unique information then only the available data will be copied to the destination buffer.

The use of returned Unique-ID data is application specific, but examples may include use for USB device serial# identification, Ethernet MAC addresses, cryptography seeds, etc.

When a valid buffer parameter is passed then the bufflen parameter indicates how many bytes are available. This bufflen size may be less than the total amount of Unique-ID information available, with the variant/platform implementation only copying the requested amount.

Note: This “always-copy” model is used since it allows the same API to be used for systems where the ID information is not held in CPU addressable memory, or where multiple sources are concatenated by an implementation to provide a larger Unique-ID value.

2017-02-09
Documentation license for this page: Open Publication License