/*
* Copyright (c) 2020 Huawei Device Co., Ltd.
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/**
* @addtogroup IotHardware
* @{
*
* @brief Provides APIs for operating devices,
* including flash, GPIO, I2C, PWM, UART, and watchdog APIs.
*
*
*
* @since 2.2
* @version 2.2
*/
/**
* @file iot_spi.h
*
* @brief Declares flash functions.
*
* These functions are used to initialize or deinitialize a flash device,
* and read data from or write data to a flash memory. \n
*
* @since 2.2
* @version 2.2
*/
#ifndef IOT_SPI_H
#define IOT_SPI_H
/**
* @brief Indicates the SPI callback, which is used in {@link SpiRegisterUsrFunc}.
*/
typedef void (*SpiIsrFunc)(void);
/**
* @brief Enumerates SPI channel IDs.
*/
typedef enum {
/** Channel 0 */
IOT_SPI_ID_0 = 0,
/** Channel 1 */
IOT_SPI_ID_1,
} IotSpiIdx;
/**
* @brief Enumerates communication polarities.
*/
typedef enum {
/** Polarity 0 */
IOT_SPI_CFG_CLOCK_CPOL_0,
/** Polarity 1 */
IOT_SPI_CFG_CLOCK_CPOL_1,
}IotSpiCfgClockCpol;
/**
* @brief Enumerates communication phases.
*/
typedef enum {
/** Phase 0 */
IOT_SPI_CFG_CLOCK_CPHA_0,
/** Phase 1 */
IOT_SPI_CFG_CLOCK_CPHA_1,
} IotSpiCfgClockCpha;
/**
* @brief Enumerates communication protocols.
*/
typedef enum {
/** Motorola protocol */
IOT_SPI_CFG_FRAM_MODE_MOTOROLA,
/** Texas Instruments protocol */
IOT_SPI_CFG_FRAM_MODE_TI,
/** Microwire protocol */
IOT_SPI_CFG_FRAM_MODE_MICROWIRE,
} IotSpiCfgFramMode;
/**
* @brief Enumerates the communication data width, that is,
* the number of valid bits in each frame.
*
*/
typedef enum {
/** 4 bits */
IOT_SPI_CFG_DATA_WIDTH_E_4BIT = 0x3,
/** 5 bits */
IOT_SPI_CFG_DATA_WIDTH_E_5BIT,
/** 6 bits */
IOT_SPI_CFG_DATA_WIDTH_E_6BIT,
/** 7 bits */
IOT_SPI_CFG_DATA_WIDTH_E_7BIT,
/** 8 bits */
IOT_SPI_CFG_DATA_WIDTH_E_8BIT,
/** 9 bits */
IOT_SPI_CFG_DATA_WIDTH_E_9BIT,
/** 10 bits */
IOT_SPI_CFG_DATA_WIDTH_E_10BIT,
/** 11 bits */
IOT_SPI_CFG_DATA_WIDTH_E_11BIT,
/** 12 bits */
IOT_SPI_CFG_DATA_WIDTH_E_12BIT,
/** 13 bits */
IOT_SPI_CFG_DATA_WIDTH_E_13BIT,
/** 14 bits */
IOT_SPI_CFG_DATA_WIDTH_E_14BIT,
/** 15 bits */
IOT_SPI_CFG_DATA_WIDTH_E_15BIT,
/** 16 bits */
IOT_SPI_CFG_DATA_WIDTH_E_16BIT,
} IotSpiCfgDataWidth;
/**
* @brief Enumerates the endian mode of each frame.
*/
typedef enum {
/** Little-endian */
IOT_SPI_CFG_ENDIAN_LITTLE,
/** Big-endian */
IOT_SPI_CFG_ENDIAN_BIG,
} IotSpiCfgEndian;
/**
* @brief Defines data communication parameters.
*/
typedef struct {
/** Communication polarity. For details about available values,
* see {@link IotSpiCfgClockCpol}.
*/
unsigned int cpol : 1;
/** Communication phase.
* For details about available values, see {@link IotSpiCfgClockCpha}.
*/
unsigned int cpha : 1;
/** Communication protocol.
* For details about available values, see {@link IotSpiCfgFramMode}.
*/
unsigned int framMode : 2;
/** Communication data width.
* For details about available values, see {@link IotSpiCfgDataWidth}.
*/
unsigned int dataWidth : 4;
/** Endian mode. For details about available values, see {@link IotSpiCfgEndian}. */
unsigned int endian : 1;
/** Padding bit */
unsigned int pad : 23;
/** Communication frequency. The value ranges from 2460 Hz to 40 MHz. */
unsigned int freq;
} IotSpiCfgBasicInfo;
/**
* @brief Specifies whether a device is a master or slave device.
*
* @since 1.0
* @version 1.0
*/
typedef struct {
/** Whether the device is a slave device */
unsigned int isSlave : 1;
/** Padding bit */
unsigned int pad : 31;
} IotSpiCfgInitParam;
/**
* @brief Sends data in SPI slave mode.
*
* In SPI slave mode, this function sends data of the length
* specified by byteLen in writeData through
* the channel specified by spiId within the duration timeOutMs.
*
* @param spiId Indicates the SPI channel ID.
* @param writeData Indicates the pointer to the data to send.
* @param byteLen Indicates the length of the data to send.
* @param timeOutMs Indicates the timeout interval.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiSlaveWrite(IotSpiIdx spiId, char *writeData, unsigned int byteLen, unsigned int timeOutMs);
/**
* @brief Reads data in SPI slave mode.
*
* In SPI slave mode, this function reads data of the length
* specified by byteLen in readData through the channel
* specified by spiId within the duration timeOutMs.
*
* @param spiId Indicates the SPI channel ID.
* @param readData Indicates the pointer to the data to read.
* @param byteLen Indicates the length of the data to read.
* @param timeOutMs Indicates the timeout interval.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiSlaveRead(IotSpiIdx spiId, char *readData, unsigned int byteLen, unsigned int timeOutMs);
/**
* @brief Sends data in half-duplex SPI master mode.
*
* In SPI master mode, this function sends data of the length
* specified by byteLen in writeData
* through the channel specified by spiId.
*
* @param spiId Indicates the SPI channel ID.
* @param writeData Indicates the pointer to the data to send.
* @param byteLen Indicates the length of the data to send.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiHostWrite(IotSpiIdx spiId, char *writeData, unsigned int byteLen);
/**
* @brief Reads data in half-duplex SPI master mode.
*
* In SPI master mode, this function reads data of the length
* specified by byteLen in readData
* through the channel specified by spiId.
*
* @param spiId Indicates the SPI channel ID.
* @param readData Indicates the pointer to the data to read.
* @param byteLen Indicates the length of the data to read.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiHostRead(IotSpiIdx spiId, char *readData, unsigned int byteLen);
/**
* @brief Sends and reads data in full-duplex SPI master mode.
*
* In SPI master mode, this function sends data in writeData and
* reads data of the length specified by byteLen in readData
* both through the channel specified by spiId.
*
* @param spiId Indicates the SPI channel ID.
* @param writeData Indicates the pointer to the data to send.
* @param readData Indicates the pointer to the data to read.
* @param byteLen Indicates the length of the data to read.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiHostWriteread(IotSpiIdx spiId, char *writeData, char *readData, unsigned int byteLen);
/**
* @brief Sets the SPI channel parameter.
*
*
*
* @param spiId Indicates the SPI channel ID.
* @param param Indicates the pointer to the SPI parameter to set.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiSetBasicInfo(IotSpiIdx spiId, const IotSpiCfgBasicInfo *param);
/**
* @brief Initializes an SPI device.
*
* This function initializes the device with the channel ID spiId,
* device type initParam, and device parameter param.
*
* @param spiId Indicates the SPI channel ID.
* @param initParam Specifies whether the device is a slave one.
* @param param Indicates the pointer to the SPI device parameter.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiInit(IotSpiIdx spiId, IotSpiCfgInitParam initParam, const IotSpiCfgBasicInfo *param);
/**
* @brief Deinitializes an SPI device.
*
* @param spiId Indicates the SPI channel ID.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiDeinit(IotSpiIdx spiId);
/**
* @brief Sets whether to enable the interrupt request (IRQ) mode for an SPI device.
*
*
*
* @param spiId Indicates the SPI channel ID.
* @param irqEn Specifies whether to enable IRQ.
* The value 1 means to enable IRQ, and 0 means to disable IRQ.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiSetIrqMode(IotSpiIdx spiId, unsigned char irqEn);
/**
* @brief Sets whether to enable DMA to transfer data for an SPI device in slave mode.
*
*
*
* @param spiId Indicates the SPI channel ID.
* @param dmaEn Specifies whether to enable DMA.
* The value 1 means to enable DMA, and 0 means to disable DMA.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiSetDmaMode(IotSpiIdx spiId, unsigned char dmaEn);
/**
* @brief Registers the data TX preparation/recovery function.
*
* This function registers the functions
* registered by prepareF and restoreF for
* an SPI device with a channel specified by spiId.
*
* @param spiId Indicates the SPI channel ID.
* @param prepareF Indicates the function used for data preparation.
* @param restoreF Indicates the function used for data recovery.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiRegisterUsrFunc(IotSpiIdx spiId, SpiIsrFunc prepareF, SpiIsrFunc restoreF);
/**
* @brief Sets whether to enable loopback test for an SPI device.
*
*
*
* @param spiId Indicates the SPI channel ID.
* @param lbEn Specifies whether to enable loopback test. The value 1
* means to enable loopback test, and 0 means to disable loopback test.
* @return Returns {@link IOT_SUCCESS} if the operation is successful;
* returns an error code defined in {@link iot_errno.h} otherwise.
* @since 1.0
* @version 1.0
*/
unsigned int IoTSpiSetLoopBackMode(IotSpiIdx spiId, unsigned char lbEn);
#endif
/** @} */