ad_spi.h

Go to the documentation of this file.

 
/*
 *
 * Terminology:
 *      Adapter:    A middleware abstraction layer for using a controller. It provides the following services:
 *                  - Arbitration in accessing the controller (between multiple masters, multiple tasks)
 *                  - Configuration of the controller
 *                  - Block sleep while the controller is in use
 *      Controller: Top level view of SPI peripheral, including the complete configuration needed for being fully functional (IOs, DMAs, Driver configuration)
 *      Driver:     The Low Level Driver associated with the controller
 *      SPI:        The controller name (e.g SPI1, SPI2)
 *
 * API example usage:
 *      ad_spi_init():           Called by the system on power up for initializing the adapter. It should NOT be called by the application
 *      ad_spi_io_config():      Called by the application for configuring the controller interface before powering up the external connected devices (e.g sensors)
 *
 *      ad_spi_open();           Called by the application for starting a transaction. The sleep is blocked until ad_spi_close() is called. No other task or master can start a new transaction using the same controller instance
 *      ad_spi_write();          Blocking write - caller task will block until the resource becomes available
 *      ad_spi_read();           Blocking read  - caller task will block until the resource becomes available
 *      ad_spi_reconfig();
 *      ad_spi_write_async();    Non blocking write - caller task should retry until function returns no error. It will then be notified when transaction is completed
 *      ad_spi_read_async();     Non blocking read  - caller task should retry until function returns no error. It will then be notified when transaction is completed
 *      ad_spi_close();          Called by the application for releasing the resource. System is allowed to go to sleep (if no other module blocks sleep)
 *
 *
 *
 * */
 
#ifndef AD_SPI_H_
#define AD_SPI_H_
 
#if dg_configSPI_ADAPTER
 
#include "ad.h"
#include "hw_spi.h"
#include "hw_gpio.h"
#include "osal.h"
#include "resmgmt.h"
#include "sdk_defs.h"
#include <stdbool.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#ifndef CONFIG_SPI_USE_ASYNC_TRANSACTIONS
# define CONFIG_SPI_USE_ASYNC_TRANSACTIONS      (1)
#endif
 
#ifndef CONFIG_SPI_USE_SYNC_TRANSACTIONS
# define CONFIG_SPI_USE_SYNC_TRANSACTIONS       (1)
#endif
 
#if (CONFIG_SPI_USE_SYNC_TRANSACTIONS == 0) && (CONFIG_SPI_USE_ASYNC_TRANSACTIONS == 0)
#error "At least one macro CONFIG_SPI_USE_SYNC_TRANSACTIONS or CONFIG_SPI_USE_ASYNC_TRANSACTIONS must be set"
#endif
 
/*
 * Data types definitions section
 */
 
typedef void *ad_spi_handle_t;
 
typedef struct {
        ad_io_conf_t spi_do;            
        ad_io_conf_t spi_clk;           
        ad_io_conf_t spi_di;            
        const uint8_t cs_cnt;           
        ad_io_conf_t* spi_cs;           
}  ad_spi_io_conf_t;
 
 
typedef struct {
        hw_spi_config_t spi;            
} ad_spi_driver_conf_t;
 
typedef struct {
        const HW_SPI_ID                 id;         
        const ad_spi_io_conf_t          *io;        
        const ad_spi_driver_conf_t      *drv;       
} ad_spi_controller_conf_t;
 
 
typedef enum {
        AD_SPI_ERROR_NONE                              =  0,
        AD_SPI_ERROR_HANDLE_INVALID                    = -1,
        AD_SPI_ERROR_ADAPTER_NOT_OPEN                  = -2,
        AD_SPI_ERROR_CONFIG_SPI_ROLE_INVALID           = -3,
        AD_SPI_ERROR_CONFIG_DMA_CHANNEL_INVALID        = -4,
        AD_SPI_ERROR_CONFIG_SPI_CS_INVALID             = -5,
        AD_SPI_ERROR_TRANSF_IN_PROGRESS                = -6,
        AD_SPI_ERROR_NO_SPI_CLK_PIN                    = -7,
        AD_SPI_ERROR_DRIVER_CLOCK_DIV_INVALID          = -8,
        AD_SPI_ERROR_DRIVER_CONF_INVALID               = -9,
        AD_SPI_ERROR_IO_CFG_INVALID                    = -10,
        AD_SPI_ERROR_CONFIG_RX_TX_TL_INVALID           = -11,
} AD_SPI_ERROR;
 
/*
 * Adapters mandatory function prototypes section
 *
 * This section includes the prototypes of the functions
 * which are mandatory for all adapters
 */
 
 
 
void ad_spi_init(void);
 
 
ad_spi_handle_t ad_spi_open(const ad_spi_controller_conf_t *conf);
 
int ad_spi_reconfig(ad_spi_handle_t handle, const ad_spi_driver_conf_t *drv_conf);
 
int ad_spi_close(ad_spi_handle_t handle, bool force);
 
int ad_spi_io_config (HW_SPI_ID id, const ad_spi_io_conf_t *io, AD_IO_CONF_STATE state);
 
 
/*
 * Adapter specific function prototypes section
 *
 * This section includes the prototypes of the functions
 * which are specific to each adapter.
 * An example function prototype is shown below
 */
 
typedef void (*ad_spi_user_cb)(void *user_data, uint16_t transferred);
 
#if (CONFIG_SPI_USE_SYNC_TRANSACTIONS == 1)
 
int ad_spi_write(ad_spi_handle_t handle, const uint8_t *wbuf, size_t wlen);
 
int ad_spi_read(ad_spi_handle_t handle, uint8_t *rbuf, size_t rlen);
 
int ad_spi_write_read(ad_spi_handle_t handle, const uint8_t *wbuf, uint8_t *rbuf, size_t len);
 
#endif /* CONFIG_SPI_USE_SYNC_TRANSACTIONS */
 
 
void ad_spi_activate_cs(ad_spi_handle_t handle, uint8_t csid);
 
void ad_spi_deactivate_cs(ad_spi_handle_t handle);
 
void ad_spi_deactivate_cs_when_spi_done(ad_spi_handle_t handle);
 
 
#if (CONFIG_SPI_USE_ASYNC_TRANSACTIONS == 1)
 
int ad_spi_write_async(ad_spi_handle_t handle, const uint8_t *wbuf, size_t wlen, ad_spi_user_cb cb,
        void *user_data);
 
int ad_spi_read_async(ad_spi_handle_t handle, const uint8_t *rbuf, size_t rlen, ad_spi_user_cb cb,
        void *user_data);
 
int ad_spi_write_read_async(ad_spi_handle_t handle, const uint8_t *wbuf, size_t wlen,
                         uint8_t *rbuf, size_t rlen, ad_spi_user_cb cb, void *user_data);
 
#endif /* CONFIG_SPI_USE_ASYNC_TRANSACTIONS */
 
#ifdef __cplusplus
}
#endif
 
#endif /* dg_configSPI_ADAPTER */
 
#endif /* AD_SPI_H_ */