adafruit-mirror/zephyr
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 9

doc: Edit the SPI driver APIs

Browse source 
Edit public API details for clarity, grammar, punctuation found
on file spi.h

Made consistent use of @retval to document return values.

Used imperative verbs for all @brief descriptions.

Change-Id: Ie53eeeb79d399e8474fe7341a396f5437c2999dc
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2016-02-07 14:29:17 -06:00 committed by Gerrit Code Review
parent 10bea3dec8
commit 0daf7e4968
1 changed files with 59 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

102
include/spi.h
View file

@ -1,5 +1,3 @@
/* spi.h - public SPI driver API */
/*
* Copyright (c) 2015 Intel Corporation
*
@ -16,6 +14,11 @@
* limitations under the License.
*/
/**
* @file
* @brief Public API for SPI drivers
*/
#ifndef __SPI_H__
#define __SPI_H__
@ -34,7 +37,9 @@
extern "C" {
#endif
/* SPI Polarity & Phase Modes */
/**
* @brief SPI Polarity & Phase Modes
*/
#define SPI_MODE_CPOL 0x1
#define SPI_MODE_CPHA 0x2
#define SPI_MODE_LOOP 0x4
@ -42,7 +47,9 @@ extern "C" {
#define SPI_MODE_MASK (0x7)
#define SPI_MODE(_in_) ((_in_) & SPI_MODE_MASK)
/* SPI Transfer modes (host controller dependent) */
/**
* @brief SPI Transfer modes (host controller dependent)
*/
#define SPI_TRANSFER_MSB (0 << 3)
#define SPI_TRANSFER_LSB (1 << 3)
@ -52,16 +59,18 @@ extern "C" {
#define SPI_WORD_SIZE_GET(_in_) (((_in_) & SPI_WORD_SIZE_MASK) >> 4)
#define SPI_WORD(_in_) ((_in_) << 4)
/*
/**
* @brief SPI configuration structure.
*
* config is a bit field with the following parts:
* mode [ 0 : 2 ] - Polarity, phase and loop mode
* transfer_mode [ 3 ] - LSB or MSB first transfer mode
* word_size [ 4 : 11 ] - Size of a data frame in bits
* RESERVED [ 12 : 31 ] - undefined usage
* mode [ 0 : 2 ] - Polarity, phase and loop mode.
* transfer_mode [ 3 ] - LSB or MSB first transfer mode.
* word_size [ 4 : 11 ] - Size of a data frame in bits.
* RESERVED [ 12 : 31 ] - undefined usage.
*
* max_sys_freq is the maximum frequency supported by the slave it
* will deal with. This value depends on the host controller (the driver
* may present a specific format for setting it).
* will deal with. This value depends on the host controller. The driver
* can present a specific format for setting it.
*/
struct spi_config {
uint32_t config;
@ -85,11 +94,12 @@ struct spi_driver_api {
};
/**
* @brief Configure a host controller for operating against slaves
* @param dev Pointer to the device structure for the driver instance
* @param config Pointer to the application provided configuration
* @brief Configure a host controller for operating against slaves.
* @param dev Pointer to the device structure for the driver instance.
* @param config Pointer to the configuration provided by the application.
*
* @return DEV_OK if successful, another DEV_* code otherwise.
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
static inline int spi_configure(struct device *dev,
struct spi_config *config)
@ -102,15 +112,16 @@ static inline int spi_configure(struct device *dev,
/**
* @brief Select a slave to deal with.
*
* Note: This is meaningful only if the controller supports per-slave
* addressing (One SS line per-slave). If not, this will not have any effect
* and you will have to consider daisy-chaining to deal with multiple slave
* This routine is meaningful only if the controller supports per-slave
* addressing: One SS line per-slave. If not, this routine has no effect
* and daisy-chaining should be considered to deal with multiple slaves
* on the same line.
*
* @param dev Pointer to the device structure for the driver instance
* @param slave An integer identifying the slave
*
* @return DEV_OK if successful, another DEV_* code otherwise.
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
static inline int spi_slave_select(struct device *dev, uint32_t slave)
{
@ -124,12 +135,13 @@ static inline int spi_slave_select(struct device *dev, uint32_t slave)
}
/**
* @brief Read a defined amount of data from an SPI driver
* @param dev Pointer to the device structure for the driver instance
* @param buf Memory buffer that data should be transferred to
* @param len Size of the memory buffer available for writing to
* @brief Read the specified amount of data from the SPI driver.
* @param dev Pointer to the device structure for the driver instance.
* @param buf Memory buffer where data will be transferred.
* @param len Size of the memory buffer available for writing.
*
* @return DEV_OK if successful, another DEV_* code otherwise.
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
static inline int spi_read(struct device *dev, uint8_t *buf, uint32_t len)
{
@ -139,12 +151,13 @@ static inline int spi_read(struct device *dev, uint8_t *buf, uint32_t len)
}
/**
* @brief Write a defined amount of data through an SPI driver
* @param dev Pointer to the device structure for the driver instance
* @param buf Memory buffer that data should be transferred from
* @param len Size of the memory buffer available for reading from
* @brief Write the specified amount of data from the SPI driver.
* @param dev Pointer to the device structure for the driver instance.
* @param buf Memory buffer from where data is transferred.
* @param len Size of the memory buffer available for reading.
*
* @return DEV_OK if successful, another DEV_* code otherwise.
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
static inline int spi_write(struct device *dev, uint8_t *buf, uint32_t len)
{
@ -154,17 +167,18 @@ static inline int spi_write(struct device *dev, uint8_t *buf, uint32_t len)
}
/**
* @brief Read and write defined amount of data through an SPI driver
* @brief Read and write the specified amount of data from the SPI driver.
*
* Note: This is meant for full-duplex transmission.
* This routine is meant for full-duplex transmission.
*
* @param dev Pointer to the device structure for the driver instance
* @param tx_buf Memory buffer that data should be transferred from
* @param tx_buf_len Size of the memory buffer available for reading from
* @param rx_buf Memory buffer that data should be transferred to
* @param rx_buf_len Size of the memory buffer available for writing to
* @param dev Pointer to the device structure for the driver instance.
* @param tx_buf Memory buffer where data originates
* @param tx_buf_len Size of the memory buffer available for reading.
* @param rx_buf Memory buffer where data is transferred.
* @param rx_buf_len Size of the memory buffer available for writing.
*
* @return DEV_OK if successful, another DEV_* code otherwise.
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
static inline int spi_transceive(struct device *dev,
uint8_t *tx_buf, uint32_t tx_buf_len,
@ -176,10 +190,11 @@ static inline int spi_transceive(struct device *dev,
}
/**
* @brief Suspend the SPI host controller operations
* @param dev Pointer to the device structure for the driver instance
* @brief Suspend the SPI host controller operations.
* @param dev Pointer to the device structure for the driver instance.
*
* @return DEV_OK if successful, another DEV_* code otherwise.
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
static inline int spi_suspend(struct device *dev)
{
@ -189,10 +204,11 @@ static inline int spi_suspend(struct device *dev)
}
/**
* @brief Resume the SPI host controller operations
* @param dev Pointer to the device structure for the driver instance
* @brief Resume the SPI host controller operations.
* @param dev Pointer to the device structure for the driver instance.
*
* @return DEV_OK if successful, another DEV_* code otherwise.
* @retval DEV_OK If successful.
* @retval DEV_* Code otherwise.
*/
static inline int spi_resume(struct device *dev)
{