Preliminary Technical Data
UG-1828
Rev. PrC | Page 41 of 338
customer_LogWrite as it may be desirable to log messages of differing severity in different manners (e.g., insert a message prefix for each
level, log errors to standard error, etc.).
Error Handling
Each ADRV9001 API function returns an int32_t value representing a recovery action, with 0 being no action or success. Recovery
actions are divided into:
•
Warning actions are those that do not have an impact at the time of executing the device API but can cause performance issues or
logging problems. The value of this action is positive.
•
Error actions are those that cause API not to be able to run and an action is required for API to go back to a good state. The value of
this action is negative.
DEVELOPING THE APPLICATION
The user application needs to allocate the init (adi_adrv9001_Init_t) and device (adi_adrv9001_Device_t) structures. Users may want to
consider allocating memory from the heap for the adi_adrv9001_Device_t and adi_adrv9001_Init_t as the structures have members
expected to be on the order of TBD KB. As part of the SDK, there is a memory_profile.py script designed to profile the storage of
application variables. Customers who are concerned about memory usage or limitations may find this script beneficial. There is a section
of the README.md under the production\ folder dedicated to “Running the memory profiler”.
Note also, the ARM binary and Stream Image are now factored out into separate files, which should help mitigate memory concerns on
the part of the customer.
The adi_adrv9001_Init_t structure is used to contain the customer profile initialization settings to configure an ADRV9001 device. This
init structure is passed to the ADRV9001 API init functions during the initialization phase. This structure contains the device profile
settings, system clock settings, data interface settings, and ADRV9001 specific SPI slave controller settings. The application layer passes a
pointer to an instance of the adi_adrv9001_Init_t structure for a particular ADRV9001 device to handle the majority of the device core
initialization. After initialization is complete, the adi_adrv9001_Init_t structure may be deallocated if desired.
The adi_adrv9001_Device_t data structure contains information for a particular ADRV9001 device, including devHalInfo, error and
caching structures. To support multiple ADRV9001 devices, the Application would need to instantiate multiple adi_adrv9001_Device_t
structures to describe each physical ADRV9001 device. Multiple ADRV9001 devices can have their own adi_adrv9001_Init_t or can share
a common adi_adrv9001_Init_t if they are to be configurated identically.
devHalInfo
devHalInfo is a structure that allows the user to define and pass any platform hardware settings to the platform HAL layer functions. The
common device structure adi_common_Device_t contains devHalInfo. devHalInfo is passed to the platform specific HAL function as a
void *devHalCfg. ADRV9001 API functions shall not read or write the devHalInfo but pass it as parameter to all HAL function calls.
The application developer must define devHalInfo per system HAL implementation requirements. The Application developer may
implement any structure to pass any hardware configuration information that the hardware requires between the application layer and
platform layer. For example, devHalInfo contains SPI chip select information to be used for the physical ADRV9001 device.
Note that the API functions are shared across all instances of physical ADRV9001 devices. The devHalInfo structure defined by the
developer identifies which physical ADRV9001 device is targeted (SPI chip select) when a particular ADRV9001 API function is called.
The developer may need to store other hardware information unique to a particular ADRV9001 device in this structure such as timer
instances or log file information.
Note for ADRV9001 API there is a requirement that only one thread may control and configure a specific device instance at any given
time.
devStateInfo
The devStateInfo member is of type adi_adrv9001_Info_t and is a runtime state container for the ADRV9001 API. The application layer
must allocate memory for this structure, on the order of TBD KB, but only the ADRV9001 API writes to the structure. The application
layer should allocate the devStateInfo structure with all zeroes. The API uses the devStateInfo structure to keep up with the current state
of the API (has it been initialized, ARM loaded, etc.), as well as a debug store for any run-time data, such as error codes, error sources,
and so forth. It is not intended for the application layer to access the devStateInfo member directly because API functions are provided to
access information of the last error.
Private vs. Public API Functions
The API is made up of multiple .c and .h files. Since the API is written in C, there are no language modifiers to identify a function as
private or public as commonly used in object-oriented languages. Per the ADI coding standard, public API functions are denoted by the
