Analog Devices ADRV9001 User Manual page 41

Reference Manual ADRV9001
SOFTWARE INTEGRATION
The application developer must define the 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 and platform layer.
For example, the devHalInfo contains SPI chip select information to use 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 the ADRV9001 API, only one thread must 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 run-time state container for the ADRV9001 API. The application layer
must allocate memory for this structure, but only the ADRV9001 API writes to the structure. The application layer allocates the devStateInfo
structure with all zeroes. The API uses the devStateInfo structure to keep up with the current state of the API (is it initialized, ARM loaded,
etc.), as well as a debug store for any run-time data, such as error codes, error sources, and so forth. The application layer must not access the
devStateInfo member directly because there are API functions to access the information of the last error.
Private vs. Public API Functions
The API is made up of multiple .c and .h files. As 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, the public API functions are denoted by the function name
prefixed with adi_adrv9001_ (for example, adi_adrv9001_Rx_Gain_Set()). The private helper functions lack the adi_ prefix and are not to be
called by the user application.
Most functions in the ADRV9001 API are prefixed with adi_adrv9001_ and are for the public use. However, many of these functions are
never called directly from the application. The utility functions that abstract some common operations, specifically the initialization of the
ADRV9001, are provided in adi_adrv9001_utilities.c. So, much of the initialization and other helper functions are separated from the top-level
adi_adrv9001.c/ adi_adrv9001.h files to help the developer focus on the functions most commonly used by the application.
Include Files
For each major function block, there are generally three files: adi_[feature].c, adi_[feature].h, and adi_[feature]_types.h. The ADRV9001
API places 'typedef' definitions in files with _types suffix such as adi_adrv9001_types.h. These _types.h files are included within their
corresponding .h files and do not need to be manually included in the application layer code.
Note that the adi_adrv9001_user.h contains the #defines for API timeouts and SPI read intervals, which may be set as needed by the user
platform. The ADRV9001 user files are the only API files the developer may change.
Restrictions
Analog Devices maintains the code in the /c_src/devices/* folders. Application developers must not modify this code. Direct SPI read/write
operation is forbidden when configuring an ADRV9001 or any other ADI devices used to evaluate the ADRV9001. Developers should only use
the high-level API functions defined in the public *.h files. Developers should not directly use any SPI read/write functions in the application for
the ADRV9001 configuration or control. Analog Devices does not support any application containing SPI writes reverse engineered from the
original ADRV9001 API.
Delays, Waits, and Sleeps
A subset of the ADRV9001 APIs requires delays to allow the hardware to complete internal configurations. These ADRV9001 APIs request
the system to perform a wait or sleep by calling the HAL interface function adi_common_Wait_us. If the target platform's HAL interface
implementation chooses to implement a thread-sleep, the application is not permitted to call another API targeting the same ADRV9001 device.
The application must wait/sleep for the API to complete before continuing with the configuration of the device.
Wait/sleep periods are defined in the adi_adrv9001_user.h. The timeout period values are the recommended period required to complete the
operation. Modifying these values is not recommended and may impact performance. During this timeout period, the status of the ADRV9001 is
polled. The frequency of the polling the status during this timeout period may be modified by adjusting the value of the polling interval.
analog.com Rev. 0 | 41 of 351