third_party/synopsys/embarc_emsk_bsp/device/device_hal/inc/dev_spi.h

/* ------------------------------------------
 * Copyright (c) 2017, Synopsys, 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:

 * 1) Redistributions of source code must retain the above copyright notice, this
 * list of conditions and the following disclaimer.

 * 2) Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation and/or
 * other materials provided with the distribution.

 * 3) Neither the name of the Synopsys, Inc., nor the names of its contributors may
 * be used to endorse or promote products derived from this software without
 * specific prior written permission.

 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, 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.
 *
 * \version 2017.03
 * \date 2014-06-16
 * \author Huaqi Fang(Huaqi.Fang@synopsys.com)
--------------------------------------------- */

/**
 * \defgroup    DEVICE_HAL_SPI  SPI Device HAL Interface
 * \ingroup DEVICE_HAL_DEF
 * \brief   definitions for spi device hardware layer (\ref dev_spi.h)
 * \details provide interfaces for spi driver to implement
 *  Here is a diagram for the spi interface.
 *
 *  \htmlonly
 *  <div class="imagebox">
 *      <div style="width: 600px">
 *          <img src="pic/dev_spi_hal.jpg" alt="SPI Device HAL Interface Diagram"/>
 *          <p>SPI Device HAL Interface Diagram</p>
 *      </div>
 *  </div>
 *  \endhtmlonly
 *
 * @{
 *
 * \file
 * \brief   spi device hardware layer definitions
 * \details provide common definitions for spi device,
 *  then software developer can develop spi driver
 *  following this definitions, and the applications
 *  can directly call this definition to realize functions
 */

#ifndef _DEVICE_HAL_SPI_H_
#define _DEVICE_HAL_SPI_H_

#include "device/device_hal/inc/dev_common.h"


/**
 * \defgroup    DEVICE_HAL_SPI_CTRLCMD      SPI Device Control Commands
 * \ingroup DEVICE_HAL_SPI
 * \brief   Definitions for spi control command, used in \ref dev_spi::spi_control "SPI IO Control"
 * \details These commands defined here can be used in user code directly.
 * - Parameters Usage
 *   - For passing parameters like integer, just use uint32_t/int32_t to directly pass values
 *   - For passing parameters for a structure, please use pointer to pass values
 *   - For getting some data, please use pointer to store the return data
 * - Common Return Values
 *   - \ref E_OK,   Control device successfully
 *   - \ref E_CLSED,    Device is not opened
 *   - \ref E_OBJ,  Device object is not valid or not exists
 *   - \ref E_PAR,  Parameter is not valid for current control command
 *   - \ref E_SYS,  Control device failed, due to hardware issues such as device is disabled
 *   - \ref E_CTX,  Control device failed, due to different reasons like in transfer state
 *   - \ref E_NOSPT,    Control command is not supported or not valid
 * - Usage Comment
 *   - For SPI poll or interrupt read/write/transfer operations, only 1 operation can be triggered.
 *     If there is a operation is running, any other operation will return \ref E_CTX
 *   - If SPI is in transfer, then the following operations may return \ref E_CTX. Like
 *     \ref SPI_CMD_SET_CLK_MODE, \ref SPI_CMD_SET_TXINT_BUF, \ref SPI_CMD_SET_RXINT_BUF,
 *     \ref SPI_CMD_SET_TXINT, \ref SPI_CMD_SET_RXINT, \ref SPI_CMD_ABORT_TX, \ref SPI_CMD_ABORT_RX,
 *     \ref SPI_CMD_FLUSH_TX, \ref SPI_CMD_FLUSH_RX, \ref SPI_CMD_SET_DFS, \ref SPI_CMD_TRANSFER_POLLING,
 *     \ref SPI_CMD_TRANSFER_INT, \ref SPI_CMD_ABORT_XFER, \ref SPI_CMD_MST_SEL_DEV, \ref SPI_CMD_MST_DSEL_DEV,
 *     \ref SPI_CMD_MST_SET_FREQ and \ref dev_spi::spi_write "SPI Poll Write" or \ref dev_spi::spi_read "SPI Poll Read".
 * @{
 */

/** Define SPI control commands for common usage */
#define DEV_SET_SPI_SYSCMD(cmd)     DEV_SET_SYSCMD((cmd))
/** Define SPI control commands for master usage */
#define DEV_SET_SPI_MST_SYSCMD(cmd) DEV_SET_SYSCMD(0x00001000|(cmd))
/** Define SPI control commands for slave usage */
#define DEV_SET_SPI_SLV_SYSCMD(cmd) DEV_SET_SYSCMD(0x00002000|(cmd))


/* ++++ Common commands for SPI Device ++++ */
/**
 * Get \ref dev_spi_info::status "current device status"
 * - Param type : uint32_t *
 * - Param usage : store result of current status
 * - Return value explanation :
 */
#define SPI_CMD_GET_STATUS          DEV_SET_SPI_SYSCMD(0)
/**
 * set the \ref dev_spi_info::clk_mode "clock mode" of spi transfer
 * - Param type : uint32_t
 * - Param usage : spi clock mode to choose clock phase and clock polarity
 * - Return value explanation :
 */
#define SPI_CMD_SET_CLK_MODE            DEV_SET_SPI_SYSCMD(1)
/**
 * set spi \ref dev_spi_info::dfs "data frame size"
 * - Param type : uint32_t
 * - Param usage : should > 0
 * - Return value explanation : If dfs is not supported, then return \ref E_SYS
 */
#define SPI_CMD_SET_DFS             DEV_SET_SPI_SYSCMD(2)
/**
 * set the \ref dev_spi_info::dummy "dummy data" during spi transfer
 * - Param type : uint32_t
 * - Param usage : dummy data to transfer
 * - Return value explanation :
 */
#define SPI_CMD_SET_DUMMY_DATA          DEV_SET_SPI_SYSCMD(3)
/**
 * Set \ref dev_spi_cbs::tx_cb "spi transmit success callback" function
 * when all required bytes are transmitted for interrupt method
 * - Param type : \ref DEV_CALLBACK * or NULL
 * - Param usage : transmit success callback function for spi
 * - Return value explanation :
 */
#define SPI_CMD_SET_TXCB            DEV_SET_SPI_SYSCMD(4)
/**
 * Set \ref dev_spi_cbs::rx_cb "spi receive success callback" function
 * when all required bytes are received for interrupt method
 * - Param type : \ref DEV_CALLBACK * or NULL
 * - Param usage : receive success callback function for spi
 * - Return value explanation :
 */
#define SPI_CMD_SET_RXCB            DEV_SET_SPI_SYSCMD(5)
/**
 * Set \ref dev_spi_cbs::xfer_cb "spi transfer success callback" function
 * when all required transfer are done for interrupt method
 * - Param type : \ref DEV_CALLBACK * or NULL
 * - Param usage : transfer success callback function for spi
 * - Return value explanation :
 */
#define SPI_CMD_SET_XFERCB          DEV_SET_SPI_SYSCMD(6)
/**
 * Set \ref dev_spi_cbs::err_cb "spi transfer error callback" function
 * when something error happened for interrupt method
 * - Param type : \ref DEV_CALLBACK * or NULL
 * - Param usage : transfer error callback function for spi
 * - Return value explanation :
 */
#define SPI_CMD_SET_ERRCB           DEV_SET_SPI_SYSCMD(7)
/**
 * Set buffer in interrupt transmit, and it will set \ref dev_spi_info::xfer "spi tranfer".
 * - SPI master and slave mode use case  \n
 *    For both master and slave mode, if you set tx buffer to NULL, when tx interrupt is enabled and entered into tx interrupt,
 * it will automatically disable the tx interrupt, so when you want to transfer something, you need to set the
 * tx buffer to Non-NULL and enable tx interrupt, when the tx buffer is sent, it will disable the tx interrupt
 * and call tx callback function if available.
 * - Param type : DEV_BUFFER * or NULL
 * - Param usage : buffer structure pointer, if param is NULL, then it will set xfer to empty
 * - Return value explanation :
 */
#define SPI_CMD_SET_TXINT_BUF           DEV_SET_SPI_SYSCMD(8)
/**
 * Set buffer in interrupt receive, and it will set \ref dev_spi_info::xfer "spi tranfer".
 * - SPI master mode use case  \n
 *   Similar to \ref SPI_CMD_SET_TXINT_BUF
 * - SPI slave mode use case   \n
 *   Similiar to \ref SPI_CMD_SET_TXINT_BUF
 * - Param type : DEV_BUFFER * or NULL
 * - Param usage : buffer structure pointer, if param is NULL, then it will set xfer to empty
 * - Return value explanation :
 */
#define SPI_CMD_SET_RXINT_BUF           DEV_SET_SPI_SYSCMD(9)
/**
 * Enable or disable transmit interrupt,
 * for master mode, only one of tx and rx interrupt can be enabled,
 * if tx interrupt is enabled, then rx interrupt can't be enabled.
 * - Param type : uint32_t
 * - Param usage : enable(none-zero) or disable(zero) flag
 * - Return value explanation :
 */
#define SPI_CMD_SET_TXINT           DEV_SET_SPI_SYSCMD(10)
/**
 * Enable or disable receive interrupt,
 * for master mode, only one of tx and rx interrupt can be enabled,
 * if rx interrupt is enabled, then tx interrupt can't be enabled.
 * - Param type : uint32_t
 * - Param usage : enable(none-zero) or disable(zero) flag
 * - Return value explanation :
 */
#define SPI_CMD_SET_RXINT           DEV_SET_SPI_SYSCMD(11)
/**
 * start the transfer by polling
 * - Param type : \ref DEV_SPI_TRANSFER *
 * - Param usage :
 * - Return value explanation :
 */
#define SPI_CMD_TRANSFER_POLLING        DEV_SET_SPI_SYSCMD(12)
/**
 * start the transfer by interrupt
 * - Param type : \ref DEV_SPI_TRANSFER * or NULL
 * - Param usage : If NULL, it will disable transfer interrupt, if not NULL, it will enable transfer interrupt
 * - Return value explanation :
 */
#define SPI_CMD_TRANSFER_INT            DEV_SET_SPI_SYSCMD(13)
/**
 * Abort current interrupt transmit operation if tx interrupt enabled,
 * it will disable transmit interrupt, and set \ref DEV_IN_TX_ABRT
 * in \ref dev_spi_info::status "status" variable,
 * and call the transmit callback function, when tx callback is finished,
 * it will clear \ref DEV_IN_TX_ABRT and return
 * - Param type : NULL
 * - Param usage :
 * - Return value explanation :
 */
#define SPI_CMD_ABORT_TX            DEV_SET_SPI_SYSCMD(14)
/**
 * Abort current interrupt receive operation if rx interrupt enabled,
 * it will disable receive interrupt, and set \ref DEV_IN_TX_ABRT
 * in \ref dev_spi_info::status "status" variable,
 * and call the receive callback function, when rx callback is finished,
 * it will clear \ref DEV_IN_TX_ABRT and return
 * - Param type : NULL
 * - Param usage :
 * - Return value explanation :
 */
#define SPI_CMD_ABORT_RX            DEV_SET_SPI_SYSCMD(15)
/**
 * Abort current interrupt transfer operation if transfer is issued,
 * it will disable transfer interrupt, and set \ref DEV_IN_XFER_ABRT
 * in \ref dev_spi_info::status "status" variable,
 * and call the transfer callback function, when xfer callback is finished,
 * it will clear \ref DEV_IN_XFER_ABRT and return
 * - Param type : NULL
 * - Param usage :
 * - Return value explanation :
 */
#define SPI_CMD_ABORT_XFER          DEV_SET_SPI_SYSCMD(16)
/**
 * Do a software reset for SPI device, it will stop current transfer,
 * and clear error state and bring device to normal state, set next condition to STOP
 * - Param type : NULL
 * - Param usage :
 * - Return value explanation :
 */
#define SPI_CMD_RESET               DEV_SET_SPI_SYSCMD(17)
/**
 * Flush spi tx fifo, this will clear the data in tx fifo
 * - Param type : NULL
 * - Param usage :
 * - Return value explanation :
 */
#define SPI_CMD_FLUSH_TX            DEV_SET_SPI_SYSCMD(18)
/**
 * Flush spi rx fifo, this will clear the data in rx fifo
 * - Param type : NULL
 * - Param usage :
 * - Return value explanation :
 */
#define SPI_CMD_FLUSH_RX            DEV_SET_SPI_SYSCMD(19)
/**
 * Enable spi device
 * - Param type : NULL
 * - Param usage : param is not required
 * - Return value explanation :
 */
#define SPI_CMD_ENA_DEV             DEV_SET_SPI_SYSCMD(20)
/**
 * Disable spi device, when device is disabled,
 * only \ref SPI_CMD_ENA_DEV, \ref SPI_CMD_DIS_DEV,
 * \ref SPI_CMD_GET_STATUS and \ref SPI_CMD_RESET
 * commands can be executed, other commands will return \ref E_SYS
 * - Param type : NULL
 * - Param usage : param is not required
 * - Return value explanation :
 */
#define SPI_CMD_DIS_DEV             DEV_SET_SPI_SYSCMD(21)
/**
 * Get how many bytes space in spi are available to transmit,
 * this can be used in interrupt callback functions,
 * cooperate with \ref dev_spi::spi_write "spi_write" API to realize non-blocked write
 * - Param type : int32_t *
 * - Param usage : store the write available bytes, > 0 for available bytes, 0 for not available
 * - Return value explanation :
 */
#define SPI_CMD_GET_TXAVAIL         DEV_SET_SPI_SYSCMD(22)
/**
 * Get how many bytes in spi are available to receive,
 * this can be used in interrupt callback functions,
 * cooperate with \ref dev_spi::spi_read "spi_read" API to realize non-blocked read
 * - Param type : int32_t *
 * - Param usage : store the read available bytes, > 0 for available bytes, 0 for not available
 * - Return value explanation :
 */
#define SPI_CMD_GET_RXAVAIL         DEV_SET_SPI_SYSCMD(23)


/* ++++ Master only commands for SPI Device ++++ */
/**
 *  select spi slave device
 * - Param type : uint32_t
 * - Param usage : the number of spi slave device to select
 * - Return value explanation : return \ref E_SYS when selection can't be done, return \ref E_CTX during transfer
 */
#define SPI_CMD_MST_SEL_DEV         DEV_SET_SPI_MST_SYSCMD(0)
/**
 *  de-select spi slave device
 * - Param type : uint32_t
 * - Param usage : the number of spi slave device to de-select
 * - Return value explanation : return \ref E_SYS when selection can't be done, return \ref E_CTX during transfer
 */
#define SPI_CMD_MST_DSEL_DEV            DEV_SET_SPI_MST_SYSCMD(1)
/**
* Set \ref dev_spi_info::freq "spi frequency".
* - Param type : uint32_t
* - Param usage : spi freq
* - Return value explanation : no return
*/
#define SPI_CMD_MST_SET_FREQ            DEV_SET_SPI_MST_SYSCMD(2)


/* ++++ Slave only commands for SPI Device ++++ */

/* \todo add spi slave related CMDs */

/** @} */

/**
 * \defgroup    DEVICE_HAL_SPI_CALLBACK SPI Interrupt callback functions
 * \ingroup DEVICE_HAL_SPI
 * \brief   callback function structure for SPI device
 * @{
 */
typedef struct dev_spi_cbs
{
    DEV_CALLBACK tx_cb; /*!< spi data transmit success required bytes callback */
    DEV_CALLBACK rx_cb; /*!< spi data receive success required bytes callback */
    DEV_CALLBACK err_cb;    /*!< spi error callback */
    DEV_CALLBACK xfer_cb;   /*!< transfer callback */
} DEV_SPI_CBS, *DEV_SPI_CBS_PTR;
/** @} */

/** SPI Clock Mode */
typedef enum spi_clk_mode
{
    SPI_CPOL_0_CPHA_0 = 0,  /*!< Inactive state of serial clock is low, serial clock toggles in middle of first data bit */
    SPI_CPOL_0_CPHA_1 = 1,  /*!< Inactive state of serial clock is low, serial clock toggles at start of first data bit  */
    SPI_CPOL_1_CPHA_0 = 2,  /*!< Inactive state of serial clock is high, serial clock toggles in middle of first data bit */
    SPI_CPOL_1_CPHA_1 = 3,  /*!< Inactive state of serial clock is high, serial clock toggles at start of first data bit */

    SPI_CLK_MODE_0    = SPI_CPOL_0_CPHA_0,  /*!< Equal to \ref SPI_CPOL_0_CPHA_0 */
    SPI_CLK_MODE_1    = SPI_CPOL_0_CPHA_1,  /*!< Equal to \ref SPI_CPOL_0_CPHA_1 */
    SPI_CLK_MODE_2    = SPI_CPOL_1_CPHA_0,  /*!< Equal to \ref SPI_CPOL_1_CPHA_0 */
    SPI_CLK_MODE_3    = SPI_CPOL_1_CPHA_1   /*!< Equal to \ref SPI_CPOL_1_CPHA_1 */
} SPI_CLK_MODE;

#define SPI_CLK_MODE_DEFAULT    SPI_CPOL_0_CPHA_0   /*!< Default SPI device clock mode */

/**
 * \defgroup    DEVICE_HAL_SPI_DEVSTRUCT    SPI Device Structure
 * \ingroup DEVICE_HAL_SPI
 * \brief   contains definitions of spi device structure.
 * \details this structure will be used in user implemented code, which was called
 *  Device Driver Implement Layer for spi to realize in user code.
 * @{
 */
typedef struct dev_spi_transfer DEV_SPI_TRANSFER, *DEV_SPI_TRANSFER_PTR;
/**
 * \brief   spi read and write data structure used by \ref SPI_CMD_TRANSFER
 *  spi write then read data
 *
 */
struct dev_spi_transfer
{
    DEV_SPI_TRANSFER *next;
    /* Calc by software */
    /** tot_len = (tx_totlen>rx_totlen)?tx_totlen:rx_totlen */
    uint32_t tot_len;
    /* Set by user */
    uint8_t *tx_buf;
    uint32_t tx_ofs;
    uint32_t tx_len;
    uint8_t *rx_buf;
    uint32_t rx_ofs;
    uint32_t rx_len;
    /* Should auto set to proper value during set buffer value */
    uint32_t tx_idx;
    uint32_t tx_totlen; /** tx_totlen = tx_len + tx_ofs */
    uint32_t rx_idx;
    uint32_t rx_totlen; /** rx_totlen = rx_len + rx_ofs */
};

/** Set tx buffer of device spi transfer */
#define DEV_SPI_XFER_SET_TXBUF(xfer, buf, ofs, len)     {       \
                    (xfer)->tx_buf = (uint8_t *)(buf);  \
                    (xfer)->tx_len = (uint32_t)(len);   \
                    (xfer)->tx_ofs = (uint32_t)(ofs);   \
                    (xfer)->tx_idx = 0;         \
                    (xfer)->tx_totlen = ( (uint32_t)(len)   \
                            + (uint32_t)(ofs) ) ;   \
                }

/** Set rx buffer of device spi transfer */
#define DEV_SPI_XFER_SET_RXBUF(xfer, buf, ofs, len)     {       \
                    (xfer)->rx_buf = (uint8_t *)(buf);  \
                    (xfer)->rx_len = (uint32_t)(len);   \
                    (xfer)->rx_ofs = (uint32_t)(ofs);   \
                    (xfer)->rx_idx = 0;         \
                    (xfer)->rx_totlen = ( (uint32_t)(len)   \
                            + (uint32_t)(ofs) ) ;   \
                }

/** Calculate total length of current transfer without next transfer */
#define DEV_SPI_XFER_CALC_TOTLEN(xfer)      (xfer)->tot_len =   \
                ((xfer)->tx_totlen > (xfer)->rx_totlen) ? (xfer)->tx_totlen : (xfer)->rx_totlen ;

/** Set next SPI transfer */
#define DEV_SPI_XFER_SET_NEXT(xfer, next_xfer)  (xfer)->next = (next_xfer);

/** Init spi transfer */
#define DEV_SPI_XFER_INIT(xfer)                 {       \
                    (xfer)->tx_idx = 0;         \
                    (xfer)->rx_idx = 0;         \
                    (xfer)->tx_totlen = ((xfer)->tx_len     \
                            + (xfer)->tx_ofs) ; \
                    (xfer)->rx_totlen = ((xfer)->rx_len     \
                            + (xfer)->rx_ofs) ; \
                    DEV_SPI_XFER_CALC_TOTLEN(xfer);     \
                }
/**
 * \brief   spi information struct definition
 * \details informations about spi open state, working state,
 *  frequency, spi registers, working method, interrupt number
 */
typedef struct dev_spi_info
{
    void *spi_ctrl;     /*!< spi control related */
    uint32_t status;    /*!< current working status, refer to \ref DEVICE_HAL_COMMON_DEVSTATUS, this should be \ref DEV_ENABLED for first open */
    uint32_t freq;      /*!< spi working baudrate */
    uint8_t mode;       /*!< spi working mode (master/slave) */
    uint8_t clk_mode;   /*!< spi clock phase and polarity, this should be \ref SPI_CLK_MODE_DEFAULT for first open */
    uint8_t opn_cnt;    /*!< spi open count, open it will increase 1, close it will decrease 1, 0 for close, >0 for open */
    uint8_t slave;      /*!< current selected slave device no, start from 0, this should be \ref SPI_SLAVE_NOT_SELECTED for first open */
    uint8_t dfs;        /*!< data frame size, this should be \ref SPI_DFS_DEFAULT for first open */

    DEV_SPI_TRANSFER xfer;  /*!< spi transfer, this should be set to all zero for first open */
    DEV_SPI_CBS spi_cbs;    /*!< spi callbacks, for both master and slave mode, this should be all NULL for first open */
    void *extra;        /*!< a extra pointer to get hook to applications which should not used by bsp developer,
                    this should be NULL for first open and you can \ref DEV_SPI_INFO_SET_EXTRA_OBJECT "set"
                    or \ref DEV_SPI_INFO_GET_EXTRA_OBJECT "get" the extra information pointer */
    uint32_t dummy;     /*!< dummy write data when send and receive, this should be \ref SPI_DUMMY_DEFAULT for first open */
} DEV_SPI_INFO, * DEV_SPI_INFO_PTR;

/** Set extra information pointer of spi info */
#define DEV_SPI_INFO_SET_EXTRA_OBJECT(spi_info_ptr, extra_info)     (spi_info_ptr)->extra = (void *)(extra_info)
/** Get extra information pointer of spi info */
#define DEV_SPI_INFO_GET_EXTRA_OBJECT(spi_info_ptr)         ((spi_info_ptr)->extra)

#define SPI_DFS_DEFAULT             8       /*!< Default spi data frame size */
#define SPI_SLAVE_NOT_SELECTED          (0xFF)      /*!< Slave is not selected */
#define SPI_DUMMY_DEFAULT           (0xFF)      /*!< default dummy value for first open */

/**
 * \brief   spi device interface definition
 * \details define spi device interface, like spi information structure,
 *  fuctions to get spi info, open/close/control spi, send/receive data by spi
 * \note    all this details are implemented by user in user porting code
 */
typedef struct dev_spi
{
    DEV_SPI_INFO spi_info;                      /*!< spi device information */
    int32_t (*spi_open)(uint32_t mode, uint32_t param);        /*!< open spi device in master/slave mode, \
                                    when in master mode, param stands for frequency, \
                                    when in slave mode, param stands for clock mode */
    int32_t (*spi_close)(void);                     /*!< close spi device */
    int32_t (*spi_control)(uint32_t ctrl_cmd, void *param);     /*!< control spi device */
    int32_t (*spi_write)(const void *data, uint32_t len);       /*!< send data to spi device (blocking method) */
    int32_t (*spi_read)(void *data, uint32_t len);          /*!< read data from spi device (blocking method) */
} DEV_SPI, * DEV_SPI_PTR;

/**
 * \fn      int32_t (* dev_spi::spi_open) (uint32_t mode, uint32_t param)
 * \details open an spi device with selected mode (master or slave) with defined \ref param
 * \param[in]   mode    working mode (\ref DEV_MASTER_MODE "master" or \ref DEV_SLAVE_MODE "slave")
 * \param[in]   param   When mode is \ref DEV_MASTER_MODE, param stands for \ref dev_spi_info::freq "frequency",
 *          when mode is \ref DEV_SLAVE_MODE, param stands for \ref dev_spi_info::clk_mode "slave clock mode"
 * \retval  E_OK    Open successfully without any issues
 * \retval  E_OPNED If device was opened before with different parameters,
 *          then just increase the \ref dev_spi_info::opn_cnt "opn_cnt" and return \ref E_OPNED
 * \retval  E_OBJ   Device object is not valid
 * \retval  E_SYS   Device is opened for different mode before, if you want to open it with different mode, you need to fully close it first.
 * \retval  E_PAR   Parameter is not valid
 * \retval  E_NOSPT Open settings are not supported
 */

/**
 * \fn      int32_t (* dev_spi::spi_close) (void)
 * \details close an spi device, just decrease the \ref dev_spi_info::opn_cnt "opn_cnt",
 *      if \ref dev_spi_info::opn_cnt "opn_cnt" equals 0, then close the device
 * \retval  E_OK    Close successfully without any issues(including scenario that device is already closed)
 * \retval  E_OPNED Device is still opened, the device \ref dev_spi_info::opn_cnt "opn_cnt" decreased by 1
 * \retval  E_OBJ   Device object is not valid
 */

/**
 * \fn      int32_t (* dev_spi::spi_control) (uint32_t ctrl_cmd, void *param)
 * \details control an spi device by \ref ctrl_cmd, with passed \ref param.
 *  you can control spi device using predefined spi control commands defined using \ref DEV_SET_SYSCMD
 *  (which must be implemented by bsp developer), such as \ref SPI_CMD_MST_SET_FREQ "set spi master frequency",
 *  \ref SPI_CMD_FLUSH_TX "flush tx" and \ref DEVICE_HAL_SPI_CTRLCMD "more".
 *  And you can also control spi device using your own specified commands defined using \ref DEV_SET_USRCMD,
 *  but these specified commands should be defined in your own spi device driver implementation.
 * \param[in]       ctrl_cmd    \ref DEVICE_HAL_SPI_CTRLCMD "control command", to change or get some thing related to spi
 * \param[in,out]   param       parameters that maybe argument of the command,
 *                  or return values of the command, must not be NULL
 * \retval  E_OK    Control device successfully
 * \retval  E_CLSED Device is not opened
 * \retval  E_OBJ   Device object is not valid or not exists
 * \retval  E_PAR   Parameter is not valid for current control command
 * \retval  E_SYS   Control device failed, due to hardware issues, such as device is disabled
 * \retval  E_CTX   Control device failed, due to different reasons like in transfer state
 * \retval  E_NOSPT Control command is not supported or not valid
 */

/**
 * \fn      int32_t (* dev_spi::spi_write) (const void *data, uint32_t len)
 * \details send \ref data through spi with defined \ref len to slave device .
 * \param[in]   data    pointer to data need to send by spi
 * \param[in]   len length of data to be sent
 * \retval  >0  Byte count that was successfully sent for poll method
 * \retval  E_OBJ   Device object is not valid or not exists
 * \retval  E_PAR   Parameter is not valid
 * \retval  E_CTX   Device is still in transfer state
 * \retval  E_SYS   Can't write data to hardware due to hardware issues, such as device is disabled
 */

/**
 * \fn      int32_t (* dev_spi::spi_read) (void *data, uint32_t len)
 * \details receive \ref data of defined \ref len through spi from slave device .
 * \param[out]  data    pointer to data need to received by spi
 * \param[in]   len length of data to be received
 * \retval  >0  Byte count that was successfully received for poll method
 * \retval  E_OBJ   Device object is not valid or not exists
 * \retval  E_CTX   Device is still in transfer state
 * \retval  E_PAR   Parameter is not valid
 * \retval  E_SYS   Can't receive data from hardware due to hardware issues, such as device is disabled
 */
/** @} */

#ifdef __cplusplus
extern "C" {
#endif

/**
 * \brief   get an \ref dev_spi "spi device" by spi device id.
 *  For how to use spi device hal refer to \ref dev_spi "Functions in spi device structure"
 * \param[in]   spi_id  id of spi, defined by user
 * \retval  !NULL   pointer to an \ref dev_spi "spi device structure"
 * \retval  NULL    failed to find the spi device by \ref spi_id
 * \note    need to implemented by user in user code
 */
extern DEV_SPI_PTR spi_get_dev(int32_t spi_id);

#ifdef __cplusplus
}
#endif

/** @} */
#endif /* _DEVICE_HAL_SPI_H_ */