no-OS
Functions
no_os_hal.c File Reference

No-OS Hardware Abstraction Layer. More...

#include <stdio.h>
#include "adi_hal.h"
#include "parameters.h"
#include "no_os_spi.h"
#include "spi_extra.h"
#include "no_os_gpio.h"
#include "gpio_extra.h"
#include "no_os_error.h"
#include "no_os_delay.h"
Include dependency graph for no_os_hal.c:

Functions

adiHalErr_t ADIHAL_setTimeout (void *devHalInfo, uint32_t halTimeout_ms)
 Sets the a timeout duration for the HAL functions. More...
 
adiHalErr_t ADIHAL_openHw (void *devHalInfo, uint32_t halTimeout_ms)
 Performs a platform hardware initialization for the ADI Device. More...
 
adiHalErr_t ADIHAL_closeHw (void *devHalInfo)
 Closes any platform hardware drivers, handles, etc that were necessary for the ADI Device. More...
 
adiHalErr_t ADIHAL_resetHw (void *devHalInfo)
 Performs a hardware reset on the ADI Device. More...
 
adiHalErr_t ADIHAL_sysrefReq (void *devHalInfo, sysrefReqMode_t mode)
 Performs a SYSREF request to the clock generation device. More...
 
adiHalErr_t ADIHAL_spiWriteByte (void *devHalInfo, uint16_t addr, uint8_t data)
 Performs a Single SPI write to an ADI Device. More...
 
adiHalErr_t ADIHAL_spiWriteBytes (void *devHalInfo, uint16_t *addr, uint8_t *data, uint32_t count)
 Writes an array of SPI writes to an ADI Device. More...
 
adiHalErr_t ADIHAL_spiReadByte (void *devHalInfo, uint16_t addr, uint8_t *readdata)
 Performs a Single SPI Read from an ADI Device. More...
 
adiHalErr_t ADIHAL_spiReadBytes (void *devHalInfo, uint16_t *addr, uint8_t *readdata, uint32_t count)
 Performs a Multi SPI Read from an ADI Device. More...
 
adiHalErr_t ADIHAL_spiWriteField (void *devHalInfo, uint16_t addr, uint8_t fieldVal, uint8_t mask, uint8_t startBit)
 Performs a write to the specified field in a SPI register. More...
 
adiHalErr_t ADIHAL_spiReadField (void *devHalInfo, uint16_t addr, uint8_t *fieldVal, uint8_t mask, uint8_t startBit)
 Performs a read from a particular bit field in a SPI register. More...
 
adiHalErr_t ADIHAL_wait_us (void *devHalInfo, uint32_t time_us)
 Delay or sleep for the specified number of microseconds. More...
 
adiHalErr_t ADIHAL_writeToLog (void *devHalInfo, adiLogLevel_t logLevel, uint32_t errorCode, const char *comment)
 Writes a character array to a log file to facilitate debugging. More...
 
adiHalErr_t ADIHAL_setLogLevel (void *devHalInfo, uint16_t logLevel)
 Writes a character array to a log file to facilitate debugging. More...
 

Detailed Description

No-OS Hardware Abstraction Layer.

Author
DBogdan (drago.nosp@m.s.bo.nosp@m.gdan@.nosp@m.anal.nosp@m.og.co.nosp@m.m)

Copyright 2018(c) Analog Devices, Inc.

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL ANALOG DEVICES BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, INTELLECTUAL PROPERTY RIGHTS, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Function Documentation

◆ ADIHAL_closeHw()

adiHalErr_t ADIHAL_closeHw ( void *  devHalInfo)

Closes any platform hardware drivers, handles, etc that were necessary for the ADI Device.

This function shall shutdown all external hardware resources required by ADI Device for correct functionality such as SPI drivers, GPIOs, clocks as as per the targeted platform and target ADI Device. It should close and free any resources assigned in ADIHAL_openHw(void *devHalInfo)

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function is called last to terminate the use of device instance and its hardware resources. ADIHAL_openHw for the same device instance prior to calling ADIHAL_closeHw

Dependencies –Application and Platform Specific modules defined by devHalInfo

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_SPI_FAILif function failed to close SPI driver for the device
ADIHAL_GPIO_FAIL,iffunction failed to release GPIO resources
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging

◆ ADIHAL_openHw()

adiHalErr_t ADIHAL_openHw ( void *  devHalInfo,
uint32_t  halTimeout_ms 
)

Performs a platform hardware initialization for the ADI Device.

This function shall initialize all external hardware resources required by ADI Device for correct functionality such as SPI drivers, GPIOs, clocks (if necessary), as per the target platform and target ADI Device. At minimum any SPI driver for the ADI Device must be initialized here in order for the SPI writes within the API to function.

The API based on the required operation shall set the value timeout parameter. Once this value is set it shall be the timeout requirement for all HAL operations. It is the responsibility of the HAL implementation to maintain this timeout value as a reference. The HAL implementation must use this value to ensure the HAL function do not block longer than this time interval.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This API should be called before calling any other ADIHAL functions.

Dependencies –Application and Platform Specific modules defined by devHalInfo

Parameters
devHalInfoA void pointer to the targeted device state container. The Platform HAL defined structure containing hardware settings describing the device of interest.
halTimeout_msA positive integer value to set the HAL function timeout interval.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_SPI_FAILif function failed to open SPI driver for the device
ADIHAL_GPIO_FAIL,iffunction failed to access GPIO resources
ADIHAL_TIMER_FAIL,iffunction failed to access timer resources
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging

◆ ADIHAL_resetHw()

adiHalErr_t ADIHAL_resetHw ( void *  devHalInfo)

Performs a hardware reset on the ADI Device.

ADI Devices have a RESETB pin. This function shall toggle the appropriate ADI Device RESETB pin according to the specifications outlined in the ADI Device Data Sheet for the targeted Device.

ADI does not define the structure members in devHalInfo. The user developing the platform layer of code is required to reset the correct device based on some identifying information within their devHalInfo structure such as a spi chip select or other device id in devHalInfo.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function may be called at any time to reset the device after the required GPIO drivers and resources are opened by the ADIHAL_openHw function call. and not after ADIHAL_closeHW.

Dependencies –Application and Platform Specific modules defined by devHalInfo

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest and required hardware references to toggle RESETB pin of the ADI device.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_GPIO_FAILif GPIO hardware to toggle ADI reset pin unavailable
ADIHAL_WAIT_TIMEOUTif HAL timeout expired before reset pin toggle could be completed.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging

◆ ADIHAL_setLogLevel()

adiHalErr_t ADIHAL_setLogLevel ( void *  devHalInfo,
uint16_t  halLogLevel 
)

Writes a character array to a log file to facilitate debugging.

This function uses the logLevel parameter to specify what type of message / warning / error to write to the log file. This function uses enums in adiLogLevel_t to set the log level. ADIHAL_LOG_NONE = 0x0, ADIHAL_LOG_MSG = 0x1, ADIHAL_LOG_WARN = 0x2, ADIHAL_LOG_ERR = 0x4, ADIHAL_LOG_SPI = 0x8, ADIHAL_LOG_ALL = 0xF

The user implementation may choose to allow a feature to filter the level of message to log. This could allow only logging errors for instance.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function should be used when setting up and configuring the system

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
halLogLevelThe type of message to log.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.

◆ ADIHAL_setTimeout()

adiHalErr_t ADIHAL_setTimeout ( void *  devHalInfo,
uint32_t  halTimeout_ms 
)

Sets the a timeout duration for the HAL functions.

This function shall set the timeout duration for the HAL functions. If the HAL operation exceed this time the function shall return with the ADIHAL_WAIT_TIMEOUT error. This value shall be set by the API based on the desired required operation. Once this value is set it shall be the timeout requirement for all HAL operations.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function can be called at anytime to change the timeout duration for the HAL functions. However, it is typically used during initialization.

Dependencies –Application and Platform Specific modules defined by devHalInfo

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
halTimeout_msA positive integer value to set the HAL function timeout interval.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown. eg devHalInfo

◆ ADIHAL_spiReadByte()

adiHalErr_t ADIHAL_spiReadByte ( void *  devHalInfo,
uint16_t  addr,
uint8_t *  readdata 
)

Performs a Single SPI Read from an ADI Device.

This function shall perform a single SPI read from an ADI Device. The SPI read implementation must support 16 bit addressing and 8-bit data bytes.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function may only be used after the required SPI drivers and resources are opened by the ADIHAL_openHw() function call and not after ADIHAL_closeHW.

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
addrThe 16-bit address to read from the SPI device. Actual address can not exceed 15-bits since MSB bit is used for Read/Write bit in platform layer.
readdataThe 8-bit data value returned from SPI register addr
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_SPI_FAILif function failed to complete SPI transaction
ADIHAL_WAIT_TIMEOUTif HAL timeout expired before SPI transaction could be completed.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging
Here is the caller graph for this function:

◆ ADIHAL_spiReadBytes()

adiHalErr_t ADIHAL_spiReadBytes ( void *  devHalInfo,
uint16_t *  addr,
uint8_t *  readdata,
uint32_t  count 
)

Performs a Multi SPI Read from an ADI Device.

This function shall perform multi SPI read from an ADI Device. The SPI read implementation must support 16 bit addressing and 8-bit data bytes.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function may only be used after the required SPI drivers and resources are opened by the ADIHAL_openHw() function call and not after ADIHAL_closeHW.

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
*addrAn array of 15-bit addresses of SPI registers to read from. 15-bit SPI register Addresses (MSB bit in lower layers sets read/write bit)
*readdataThe 8-bit data value returned from SPI register addr
countThe number of SPI Reads to transfer. Must be equal to the size of the addr and data arrays.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_SPI_FAILif function failed to complete SPI transaction
ADIHAL_WAIT_TIMEOUTif HAL timeout expired before SPI transaction could be completed.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging

◆ ADIHAL_spiReadField()

adiHalErr_t ADIHAL_spiReadField ( void *  devHalInfo,
uint16_t  addr,
uint8_t *  fieldVal,
uint8_t  mask,
uint8_t  startBit 
)

Performs a read from a particular bit field in a SPI register.

This function shall perform a single SPI read from an ADI Device. Before the SPI read value is returned, it is masked and bit-shifted to return only a desired subset of bits - the desired bit field.

Any necessary SPI drivers or resources are expected to have already been opened by the ADIHAL_openHw() function call.

The mask parameter is applied to the entire 8-bit SPI read back value. The startBit parameter shifts the desired subset of bits down to the zero bit position.

Desired Operation: readVal = SPI read of a 8-bit SPI register return (readVal & mask) >> startBit

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function may only be used after the required SPI drivers and resources are opened by the ADIHAL_openHw() function call and not after ADIHAL_closeHW.

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
addrThe 16-bit address to read/modify/write from the SPI device. Actual address can not exceed 15-bits since MSB bit is used for Read/Write bit in platform layer.
fieldVal8-bit value: Readback value of a bitfield (subset) of the SPI register masked and shifted down to the bit 0 position
mask8-bit mask of bits to readback (if a bit = 1, that bit can be read)
startBitstarting LSB bit of the fieldVal in the SPI reg. Bit shifts the fieldVal down to that bit before returning in fieldVal
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_SPI_FAILif function failed to complete SPI transaction
ADIHAL_WAIT_TIMEOUTif HAL timeout expired before SPI transaction could be completed.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging

◆ ADIHAL_spiWriteByte()

adiHalErr_t ADIHAL_spiWriteByte ( void *  devHalInfo,
uint16_t  addr,
uint8_t  data 
)

Performs a Single SPI write to an ADI Device.

This function shall perform a single SPI write to an ADI Device. The SPI write implementation must support 15 bit addressing and 8-bit data bytes.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function may only be used after the required SPI drivers and resources are opened by the ADIHAL_openHw() function call and not after ADIHAL_closeHW.

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
addr15-bit SPI register Address (MSB bit in lower layers sets read/write bit)
data8-bit data value to write to the SPI address specified.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_SPI_FAILif function failed to complete SPI transaction
ADIHAL_WAIT_TIMEOUTif HAL timeout expired before SPI transaction could be completed.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging
Here is the caller graph for this function:

◆ ADIHAL_spiWriteBytes()

adiHalErr_t ADIHAL_spiWriteBytes ( void *  devHalInfo,
uint16_t *  addr,
uint8_t *  data,
uint32_t  count 
)

Writes an array of SPI writes to an ADI Device.

This function allows improved performance to write large sets of SPI registers to a single device by passing the SPI Write address and data to the platform driver in an array instead of many individual calls.

If the platform layer SPI driver has no way to write an array to the SPI driver, have this function call ADIHAL_spiWriteByte in a for loop.

Each address element corresponds to the same index element in the data array. addr[0] is the SPI address for data[0], addr[1] is the SPI addr for data[1], etc.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function may only be used after the required SPI drivers and resources are opened by the ADIHAL_openHw() function call and not after ADIHAL_closeHW.

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
addrAn array of 15-bit addresses of SPI register to write. 15-bit SPI register Addresses (MSB bit in lower layers sets read/write bit)
dataAn array of 8-bit data values to write to the SPI addresses in the addr array.
countThe number of SPI Writes to transfer. Must be smaller or equal to the size of the addr and data arrays.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_SPI_FAILif function failed to complete SPI transaction
ADIHAL_WAIT_TIMEOUTif HAL timeout expired before SPI transaction could be completed.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging

◆ ADIHAL_spiWriteField()

adiHalErr_t ADIHAL_spiWriteField ( void *  devHalInfo,
uint16_t  addr,
uint8_t  fieldVal,
uint8_t  mask,
uint8_t  startBit 
)

Performs a write to the specified field in a SPI register.

This function shall perform a Read/Modify/Write of a single SPI read from an bits in the register, and writing the value back to the SPI register. ADI Device. The mask and startBit parameters allow modifying some or all

The mask is expected to be applied to the complete 8-bit read back SPI register value. The startBit parameter is used to shift the fieldVal parameter to the correct starting bit in the SPI register.

Desired Operation: readVal = Read 8-bit SPI register value

Modify Clear bits in readVal for enabled mask bits (readVal & ~mask) Set bits in field based on mask and startBit ((fieldVal << startBit) & mask)

Write the modified value back to the SPI register

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function may only be used after the required SPI drivers and resources are opened by the ADIHAL_openHw() function call and not after ADIHAL_closeHW.

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
addrThe 16-bit address to read/modify/write from the SPI device. Actual address can not exceed 15-bits since MSB bit is used for Read/Write bit in platform layer.
fieldVal8-bit value to update in a bitfield (subset) of the SPI register
mask8-bit mask of bits to modify (if a bit = 1, that bit can be modified)
startBitstarting bit of the fieldVal in the SPI reg. Bit shifts the fieldVal up to that bit before masking and modifying the SPI reg.
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_SPI_FAILif function failed to complete SPI transaction
ADIHAL_WAIT_TIMEOUTif HAL timeout expired before SPI transaction could be completed.
ADIHAL_WARNINGif function failed to access non-critical resource eg logging

◆ ADIHAL_sysrefReq()

adiHalErr_t ADIHAL_sysrefReq ( void *  devHalInfo,
sysrefReqMode_t  mode 
)

Performs a SYSREF request to the clock generation device.

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest and required hardware references to toggle SYSREF pin of the ADI device.
modeSYSREF request mode.
Precondition
This function may be called at any time to issue a SYSREF request after the required GPIO drivers and resources are opened by the ADIHAL_openHw function call and not after ADIHAL_closeHW.

Dependencies –Application and Platform Specific modules defined by devHalInfo

Return values
ADIHAL_OKif function completed successfully.
ADIHAL_ERRORif wrong mode is provided.
Here is the caller graph for this function:

◆ ADIHAL_wait_us()

adiHalErr_t ADIHAL_wait_us ( void *  devHalInfo,
uint32_t  time_us 
)

Delay or sleep for the specified number of microseconds.

Performs a thread blocking/sleeping delay of the specified time in us. Function should wait at least for the specified amount of time.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function can be used at any time to create a delay

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
time_usThe amount of time in microseconds to block - thread sleep for
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_TIMER_FAILif function delay function failed to complete
ADIHAL_WARNINGif function failed to access non-critical resource eg logging

◆ ADIHAL_writeToLog()

adiHalErr_t ADIHAL_writeToLog ( void *  devHalInfo,
adiLogLevel_t  logLevel,
uint32_t  errorCode,
const char *  comment 
)

Writes a character array to a log file to facilitate debugging.

This function uses the logLevel parameter to specify what type of message / warning / error to write to the log file. This function uses enums in adiLogLevel_t to set the log level.

The user implementation may choose to allow a feature to filter the level of message to log. This could allow only logging errors for instance.

Returns an error of type adiHalErr_t. Error returned will depend on platform specific implementation. API expects ADIHAL_OK if function completed successfully. Any other value represents an error or warning to the API. Error return list below provides possible errors from customer implementation.

Precondition
This function can be used at anytime once the required logging resources are opened by the ADIHAL_openHw() function call and not after ADIHAL_closeHW. The log level should also be set prior to calling this function via ADIHAL_setLogLevel.

Dependencies –Application and Platform Specific modules

Parameters
devHalInfoPointer to Platform HAL defined structure containing hardware settings describing the device of interest.
logLevelThe type of message to log. ADIHAL_LOG_MSG, ADIHAL_LOG_WARN, ADIHAL_LOG_ERR, ADIHAL_LOG_SPI,
errorCodeAn error code value to designate a particular error
commentThe character array describing the error
Return values
ADIHAL_OKif function completed successfully.
ADIHAL_GEN_SWif device references is unknown.
ADIHAL_WARNINGif log message cannot be completed