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( 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( CYG_BYTE *buffer, CYG_WORD32 bufflen )
This macro, when defined, provides a mechanism for filling the
buffer parameter with
bufflen bytes of Unique-ID data. If the
implementation provides fewer that
bytes of unique information then only the available data will be
copied to the destination
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
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.