/* * Copyright (C) 2020 Inria * * This file is subject to the terms and conditions of the GNU Lesser * General Public License v2.1. See the file LICENSE in the top level * directory for more details. */ /** * @ingroup pkg_uwb_dw1000 * @{ * * @file * @brief SPI abstraction layer RIOT adaption * * @author Francisco Molina * @} */ #ifndef HAL_HAL_SPI_H #define HAL_HAL_SPI_H #include "periph/spi.h" #ifdef __cplusplus extern "C" { #endif /** SPI mode 0 */ #define HAL_SPI_MODE0 (SPI_MODE_0) /** SPI mode 1 */ #define HAL_SPI_MODE1 (SPI_MODE_1) /** SPI mode 2 */ #define HAL_SPI_MODE2 (SPI_MODE_2) /** SPI mode 3 */ #define HAL_SPI_MODE3 (SPI_MODE_3) /** * @brief Prototype for tx/rx callback */ typedef void (*hal_spi_txrx_cb)(void *arg, int len); /** * @brief since one spi device can control multiple devices, some configuration * can be changed on the fly from the hal */ struct hal_spi_settings { /** Data mode of SPI driver, defined by HAL_SPI_MODEn */ spi_mode_t data_mode; /** Baudrate in kHz */ spi_clk_t baudrate; }; /** * @brief Configure the spi. Must be called after the spi is initialized (after * hal_spi_init is called) and when the spi is disabled (user must call * hal_spi_disable if the spi has been enabled through hal_spi_enable prior * to calling this function). Can also be used to reconfigure an initialized * SPI (assuming it is disabled as described previously). * * @param spi_num The number of the SPI to configure. * @param psettings The settings to configure this SPI with * * @return int 0 on success, non-zero error code on failure. */ int hal_spi_config(int spi_num, struct hal_spi_settings *psettings); /** * @brief Sets the txrx callback (executed at interrupt context) when the * buffer is transferred by the master or the slave using the non-blocking API. * Cannot be called when the spi is enabled. This callback will also be called * when chip select is de-asserted on the slave. * * NOTE: This callback is only used for the non-blocking interface and must * be called prior to using the non-blocking API. * * @param spi_num SPI interface on which to set callback * @param txrx_cb Callback function * @param arg Argument to be passed to callback function * * @return int 0 on success, non-zero error code on failure. */ int hal_spi_set_txrx_cb(int spi_num, hal_spi_txrx_cb txrx_cb, void *arg); /** * @brief Enables the SPI. This does not start a transmit or receive operation; * it is used for power mgmt. Cannot be called when a SPI transfer is in * progress. * * @param spi_num * * @return int 0 on success, non-zero error code on failure. */ int hal_spi_enable(int spi_num); /** * @brief Disables the SPI. Used for power mgmt. It will halt any current SPI transfers * in progress. * * @param spi_num * * @return int 0 on success, non-zero error code on failure. */ int hal_spi_disable(int spi_num); /** * @brief Blocking interface to send a buffer and store the received values from the * slave. The transmit and receive buffers are either arrays of 8-bit (uint8_t) * values or 16-bit values depending on whether the spi is configured for 8 bit * data or more than 8 bits per value. The 'cnt' parameter is the number of * 8-bit or 16-bit values. Thus, if 'cnt' is 10, txbuf/rxbuf would point to an * array of size 10 (in bytes) if the SPI is using 8-bit data; otherwise * txbuf/rxbuf would point to an array of size 20 bytes (ten, uint16_t values). * * NOTE: these buffers are in the native endian-ness of the platform. * * MASTER: master sends all the values in the buffer and stores the * stores the values in the receive buffer if rxbuf is not NULL. * The txbuf parameter cannot be NULL. * SLAVE: cannot be called for a slave; returns -1 * * @param spi_num SPI interface to use * @param txbuf Pointer to buffer where values to transmit are stored. * @param rxbuf Pointer to buffer to store values received from peer. * @param cnt Number of 8-bit or 16-bit values to be transferred. * * @return int 0 on success, non-zero error code on failure. */ int hal_spi_txrx(int spi_num, void *txbuf, void *rxbuf, int cnt); /** * @brief Non-blocking interface to send a buffer and store received values. Can be * used for both master and slave SPI types. The user must configure the * callback (using hal_spi_set_txrx_cb); the txrx callback is executed at * interrupt context when the buffer is sent. * * The transmit and receive buffers are either arrays of 8-bit (uint8_t) * values or 16-bit values depending on whether the spi is configured for 8 bit * data or more than 8 bits per value. The 'cnt' parameter is the number of * 8-bit or 16-bit values. Thus, if 'cnt' is 10, txbuf/rxbuf would point to an * array of size 10 (in bytes) if the SPI is using 8-bit data; otherwise * txbuf/rxbuf would point to an array of size 20 bytes (ten, uint16_t values). * * NOTE: these buffers are in the native endian-ness of the platform. * * MASTER: master sends all the values in the buffer and stores the * stores the values in the receive buffer if rxbuf is not NULL. * The txbuf parameter cannot be NULL * SLAVE: Slave "preloads" the data to be sent to the master (values * stored in txbuf) and places received data from master in rxbuf * (if not NULL). The txrx callback occurs when len values are * transferred or master de-asserts chip select. If txbuf is NULL, * the slave transfers its default byte. Both rxbuf and txbuf cannot * be NULL. * * @param spi_num SPI interface to use * @param txbuf Pointer to buffer where values to transmit are stored. * @param rxbuf Pointer to buffer to store values received from peer. * @param cnt Number of 8-bit or 16-bit values to be transferred. * * @return int 0 on success, non-zero error code on failure. */ int hal_spi_txrx_noblock(int spi_num, void *txbuf, void *rxbuf, int cnt); #ifdef __cplusplus } #endif #endif /* HAL_HAL_SPI_H */