Introduction to Utility Functions

19

19.1 Overview

This section defines general utility functions (library functions) and macros available to UDI drivers. UDI utility functions, whether defined in this section or elsewhere, are functions that are not in any way platform or environment implementation dependent, and therefore could have been coded in the driver itself, but are provided by the environment for driver writers' convenience. Placing these functions in the environment instead of each individual device driver also improves the degree of code sharing.

All environments shall provide utility functions for binary portability of drivers, even if they implement those utilities as macros as well.

Because UDI utilities have no platform dependencies (they may be implemented differently in different environments, but not in a way that affects cross-platform portability), the UDI utility functions may be implemented as macros without affecting binary portability. In other words, the utility can be implemented in various ways in the C language, but the functionality provided by the utility is in no way platform dependent and will therefore not break binary portability if implemented as a macro.

Note, however, that for utilities defined as functions, all environments must provide external function versions of these utilities even if they provide macro-ized versions of them. The function versions are needed for example if a driver is compiled in an environment in which the utilities are environment functions (external function declarations in udi.h), and then loaded into an environment in which the utilities (in its udi.h) are macros.

Note - Unless otherwise stated, the results of passing a NULL or other invalid pointer to a utility function are unspecified.

The utility functions in this section are divided into three categories:

1. String/Memory Utility Functions
2. Queue Management Utility Functions
3. Endianness Management Utility Functions

Non-utility functions can have platform dependencies and therefore must generally be implemented as external function calls. However, an ABI may specify that some functional interfaces may be partially implemented as macros. Such macros would in turn call ABI-specified external functions to perfom any environment-specific functionality that would not be portable across UDI environments that support this ABI. For example, ABIs might specify udi_assert as a macro that performs the assertion check and calls an ABI-specified function if the assertion fails.

See Section 33.4, "Binary Bindings to the Source-Level Specifications", for additional information.