Analog Devices ADRV9001 User Manual page 35

Preliminary Technical Data UG-1828
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
function name prepended with "adi_adrv9001_" (for example, adi_adrv9001_Rx_Gain_Set()). Private helper functions lack the adi_
prefix and are not intended to be called by the customer application.
Most functions in the ADRV9001 API are prefixed with "adi_adrv9001_" and are for public use. However, many of these functions are
never called directly from the application. Utility functions that abstract some common operations, specifically initialization of the
ADRV9001, are provided in adi_adrv9001_utilities.c. For this reason, much of the initialization and other helper functions have been
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 postfix such as adi_adrv9001_types.h. These _types.h files are included within their
corresponding .h files and do no need to be manually included in the application layer code.
Note that the adi_adrv9001_user.h contain the #defines for API timeouts and SPI read intervals which may be set as needed by the
customer platform. The ADRV9001 user files are the only API files that the developer may change.
Restrictions
Analog Devices maintains the code in the /c_api/devices/* folders. Modification of this code by Application developers is forbidden.
Direct SPI read/write operation is forbidden when configuring an ADRV9001 or any other ADI devices used for the evaluation of
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 ADRV9001 configuration or control. ADI does not support any application
containing SPI writes that are reverse engineered from the original ADRV9001 API.
Delays, Waits, and Sleeps
A subset of ADRV9001 APIs require 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/adi_common_Wait_ms. If the target
platform's HAL interface implementation chooses to implement a thread-sleep, it is not permitted for the application to call another API
targeting the same ADRV9001 device. The application is required to wait/sleep and the API to complete before continuing with the
configuration of the device.
Wait/sleep periods are defined in 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 time-out period, the status of
ADRV9001 is polled. The frequency of the polling the status during this timeout period may be modified by the user by adjusting the
value of the polling interval.
Rev. PrA | Page 35 of 253