/*
 * Copyright (c) Hisilicon Technologies Co., Ltd. 2019-2020. All rights reserved.
 * Description: Application programming interfaces (APIs) of spi
 */
#ifndef UAPI_SPI_H
#define UAPI_SPI_H

#include "td_type.h"

#ifdef __cplusplus
#if __cplusplus
extern "C" {
#endif
#endif /* __cplusplus */

/* Structure Definition */
/* \addtogroup      SPI */
/* @{ */ /* <!-- [SPI] */

/* SPI device select */ /* CNcomment: SPI 设备 */
typedef enum {
    UAPI_SPI_DEV_0 = 0,
    UAPI_SPI_DEV_1 = 1,
    UAPI_SPI_DEV_2 = 2,
    UAPI_SPI_DEV_3 = 3,

    UAPI_SPI_DEV_MAX
} uapi_spi_device;

/* SPI CS Config */ /* CNcomment: SPI CS脚配置 */
typedef enum {
    UAPI_SPI_LOGIC_CS = 0,
    UAPI_SPI_GPIO_CS = 1,
} uapi_spi_config_cs;

/* SPICLOCKOUT polarity */ /* CNcomment: SPICLOCKOUT 极性值枚举 */
typedef enum {
    UAPI_SPI_SPO_0 = 0,
    UAPI_SPI_SPO_1 = 1,
    UAPI_SPI_SPO_2 = 2,
    UAPI_SPI_SPO_3 = 3,
} uapi_spi_clockout_polarity;

/* SPICLOCKOUT phase */ /* CNcomment: SPICLOCKOUT 相位值枚举 */
typedef enum {
    UAPI_SPI_SPH_0 = 0,
    UAPI_SPI_SPH_1 = 1,
    UAPI_SPI_SPH_2 = 2,
    UAPI_SPI_SPH_3 = 3,
} uapi_spi_clockout_phase;

/* SPI Frame format */ /* CNcomment: 帧格式 */
typedef enum {
    UAPI_SPI_FORMAT_MOTO = 0, /* < Motorola SPI */     /* CNcomment: Motorola SPI */
    UAPI_SPI_FORMAT_TI = 1, /* < TI SPI */             /* CNcomment: TI SPI */
    UAPI_SPI_FORMAT_NM = 2, /* < National Microwire */ /* CNcomment: National Microwire */

    UAPI_SPI_FORMAT_MAX = 3
} uapi_spi_frame_format;

/* SPI additional attribute about Motorola SPI */ /* CNcomment: Motorola SPI 协议专有属性 */
typedef struct {
    /* < only effective when config_cs is UAPI_SPI_FRF_MOTO */ /* CNcomment: 仅在motorola协议有效 */
    uapi_spi_clockout_polarity spo;
    /* < only effective when config_cs is UAPI_SPI_FRF_MOTO */ /* CNcomment: 仅在motorola协议有效 */
    uapi_spi_clockout_phase sph;
} uapi_spi_attr_motorola;

/* SPI additional attribute about National Microwire SPI */ /* CNcomment: National Microwire SPI 协议专有属性 */
typedef struct {
    td_bool wait_enable; /* < wait enable. */   /* CNcomment: 等待使能 */
    td_u32 wait_value; /* < wait time value. */ /* CNcomment: 等待时间 */
} uapi_spi_attr_national_microwire;

/* SPI additional attribute union */ /* CNcomment: Motorola SPI/NM 协议专有属性 */
typedef union {
    uapi_spi_attr_motorola motorola;
    uapi_spi_attr_national_microwire national_microwire;
} uapi_spi_attr_ext;

/* The SPI attribute */ /* CNcomment: SPI工作模式属性 */
typedef struct {
    uapi_spi_device device; /* < chip select */                                     /* CNcomment: 指定设备 */
    uapi_spi_config_cs cs_cfg; /* < cs select */                                    /* CNcomment: 选择片选配置 */
    td_u32 baud; /* < baud rate */                                                    /* CNcomment: 波特率 */
    uapi_spi_frame_format frame_format; /* < frame format */                        /* CNcomment: 帧模式 */
    td_u32 dss; /* < number of bits per transfer, 4-15bit, value of dss : [4, 15]. */ /* CNcomment: 设置范围4-15 */
    td_bool is_bigend; /* < byte order */                                             /* CNcomment: 大小端 */
    uapi_spi_attr_ext ext_attr; /* < addition attr when frame_format is motorola or national_microwire. */
    /* CNcomment: 模式为MOTO或者NM时使用 */
} uapi_spi_attr;

/* @} */ /* <!-- ==== Structure Definition End ==== */

/* API Declaration */
/* \addtogroup      SPI */
/* @{ */ /* <!-- [SPI] */

/*
 * \brief Init the SPI device. CNcomment:初始化SPI（the Inter-Integrated Circuit）设备。CNend
 * \param N/A                  CNcomment:无。CNend
 * \retval 0 Success           CNcomment:成功。CNend
 * \see \n
 * N/A
 */
td_s32 uapi_spi_init(td_void);

/*
 * \brief DeInit the SPI device.  CNcomment:去初始化SPI设备。CNend
 * \param N/A                     CNcomment:无。CNend
 * \retval 0 Success              CNcomment:成功。CNend
 * \see \n
 * N/A
 */
td_s32 uapi_spi_deinit(td_void);

/*
 * \brief Open the SPI device.                    CNcomment:打开指定SPI设备。CNend
 * \attention \n
 * \param[in] device select device                CNcomment:指定设备。CNend
 * \retval 0 Success                              CNcomment:成功。CNend
 * \retval ::SOC_ERR_SPI_OPEN_ERR  Opne Spi Error. CNcomment:SPI设备打开失败。CNend
 * \see \n
 * N/A
 */
td_s32 uapi_spi_open(uapi_spi_device device);

/*
 * \brief Close the SPI device.                     CNcomment:关闭指定SPI设备。CNend
 * \param[in] device select device                  CNcomment:指定设备。CNend
 * \retval 0 Success                                CNcomment:成功。CNend
 * \retval ::SOC_ERR_SPI_CLOSE_ERR Close Spi Error.  CNcomment:SPI设备关闭失败。CNend
 * \see \n
 * N/A
 */
td_s32 uapi_spi_close(uapi_spi_device device);

/*
 * \brief Set the SPI working mode.                CNcomment:设置SPI工作方式。CNend
 * \param[in] device select device                 CNcomment:指定设备。CNend
 * \param[in] attribute The attribute of the SPI.  CNcomment:SPI的属性。CNend
 * \retval 0 Success                               CNcomment:成功。CNend
 * \retval ::
 * \see \n
 * N/A
 */
td_s32 uapi_spi_set_attr(uapi_spi_device device, const uapi_spi_attr *attr);

/*
 * \brief  Get the SPI working mode.                CNcomment:获取SPI工作方式相关属性。CNend
 * \param[in] device  select device                 CNcomment:指定设备。CNend
 * \param[out] attribute The attribute of the SPI . CNcomment:SPI的属性。CNend
 * \retval 0 Success                                CNcomment:成功。CNend
 * \retval ::
 * \see \n
 * N/A
 */
td_s32 uapi_spi_get_attr(uapi_spi_device device, uapi_spi_attr *attr);

/*
 * \brief Trans data by using the SPI.                         CNcomment:SPI数据传输。CNend
 * \attention \n
 * N/A
 * \param[in] device select device                             CNcomment:指定设备。CNend
 * \param[in] send Buffer for storing the data to be written   CNcomment:存放待写入数据。CNend
 * \param[in] send_count Length of the data to be written      CNcomment:待写数据的长度。CNend
 * \param[in] read Buffer for storing the data to be read .    CNcomment:存放接收数据。CNend
 * \param[in] read_count Length of the data to be read         CNcomment:要读取的数据长度。CNend
 * \retval 0 Success                                           CNcomment:成功。CNend
 * \retval ::TD_FAILURE Read data failed                       CNcomment:失败。CNend
 * \see \n
 * N/A
 */
td_s32 uapi_spi_transmit(uapi_spi_device device, const td_u8 *send, td_u32 send_count, td_u8 *read, td_u32 read_count);

/*
 * \brief Reads data by using the SPI.                         CNcomment:SPI数据接收。CNend
 * \attention \n
 * N/A
 * \param[in] device select device                             CNcomment:指定设备。CNend
 * \param[out] read Buffer for storing the data to be read .   CNcomment:存放接收数据。CNend
 * \param[in] read_count Length of the data to be read         CNcomment:要读取的数据长度。CNend
 * \retval 0 Success                                           CNcomment:成功。CNend
 * \retval ::TD_FAILURE Read data failed                       CNcomment:失败。CNend
 * \see \n
 * N/A
 */
td_s32 uapi_spi_read(uapi_spi_device device, td_u8 *read, td_u32 read_count);

/*
 * \brief Reads data by using the SPI.                         CNcomment:SPI数据发送。CNend
 * \attention \n
 * N/A
 * \param[in] device select device                             CNcomment:指定设备。CNend
 * \param[in] send Buffer for storing the data to be written   CNcomment:存放待写入数据。CNend
 * \param[in] send_count Length of the data to be written      CNcomment:待写数据的长度。CNend
 * \retval 0 Success                                           CNcomment:成功。CNend
 * \retval ::TD_FAILURE Read data failed                       CNcomment:失败。CNend
 * \see \n
 * N/A
 */
td_s32 uapi_spi_write(uapi_spi_device device, const td_u8 *send, td_u32 send_count);

/* @} */ /* <!-- ==== API Declaration End ==== */

#ifdef __cplusplus
#if __cplusplus
}
#endif
#endif /* __cplusplus */

#endif /* UAPI_SPI_H */