michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit the UART driver APIs

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

Amost all elements in this driver are now documented.

Made consistent use of @retval to document return values.

Made all verbs in the brief descriptions imperative.

Change-Id: Ied3a80ea636855ba42b33877c0ac7ac66d42e458
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero 2016-02-07 15:04:32 -06:00
commit 8a454e690a
1 changed files with 143 additions and 87 deletions
Download patch file Download diff file Expand all files Collapse all files

230
include/uart.h
View file

@ -1,5 +1,3 @@
/* uart.h - public UART driver APIs */
/* /*
* Copyright (c) 2015 Wind River Systems, Inc. * Copyright (c) 2015 Wind River Systems, Inc.
* *
@ -16,6 +14,11 @@
* limitations under the License. * limitations under the License.
*/ */
/**
* @file
* @brief Public APIs for UART drivers
*/
#ifndef __INCuarth #ifndef __INCuarth
#define __INCuarth #define __INCuarth
@ -38,25 +41,37 @@ extern "C" {
#include <pci/pci.h> #include <pci/pci.h>
#include <pci/pci_mgr.h> #include <pci/pci_mgr.h>
#endif #endif
/* options for uart init */ /**
* @brief Options for @a UART initialization.
*/
#define UART_OPTION_AFCE 0x01 #define UART_OPTION_AFCE 0x01
/** Common line controls for UART */ /** Common line controls for UART.*/
#define LINE_CTRL_BAUD_RATE (1 << 0) #define LINE_CTRL_BAUD_RATE (1 << 0)
#define LINE_CTRL_RTS (1 << 1) #define LINE_CTRL_RTS (1 << 1)
#define LINE_CTRL_DTR (1 << 2) #define LINE_CTRL_DTR (1 << 2)
/** Common errors types for UART */ /* Common communication errors for UART.*/
#define UART_ERROR_OVERRUN (1 << 0) /* overrun error */
#define UART_ERROR_PARITY (1 << 1) /* parity error */ /** @brief Overrun error */
#define UART_ERROR_FRAMING (1 << 2) /* framing error */ #define UART_ERROR_OVERRUN (1 << 0)
/* A break interrupt was received i.e. whenever the serial input was held at a
* logic '0' state for longer than the sum of start time + data bits + parity + /** @brief Parity error */
* stop bits. #define UART_ERROR_PARITY (1 << 1)
/** @brief Framing error */
#define UART_ERROR_FRAMING (1 << 2)
/**
* @brief Break interrupt error:
*
* A break interrupt was received. This happens when the serial input is
* held at a logic '0' state for longer than the sum of start time + data bits
* + parity + stop bits.
*/ */
#define UART_ERROR_BREAK (1 << 3) #define UART_ERROR_BREAK (1 << 3)
/** UART device configuration */ /** @brief UART device configuration.*/
struct uart_device_config { struct uart_device_config {
/** /**
* Base port number * Base port number
@ -69,37 +84,65 @@ struct uart_device_config {
uint32_t regs; uint32_t regs;
}; };
uint32_t sys_clk_freq; /* System clock frequency in Hz */ /** System clock frequency in Hz.*/
uint32_t sys_clk_freq;
#ifdef CONFIG_PCI #ifdef CONFIG_PCI
struct pci_dev_info pci_dev; struct pci_dev_info pci_dev;
#endif /* CONFIG_PCI */ #endif /* CONFIG_PCI */
}; };
/**< Driver API struct */ /** @brief Driver API structure. */
struct uart_driver_api { struct uart_driver_api {
/* console I/O functions */ /** Console I/O function */
int (*poll_in)(struct device *dev, unsigned char *p_char); int (*poll_in)(struct device *dev, unsigned char *p_char);
unsigned char (*poll_out)(struct device *dev, unsigned char out_char); unsigned char (*poll_out)(struct device *dev, unsigned char out_char);
/** Console I/O function */
int (*err_check)(struct device *dev); int (*err_check)(struct device *dev);
#ifdef CONFIG_UART_INTERRUPT_DRIVEN #ifdef CONFIG_UART_INTERRUPT_DRIVEN
/* interrupt driven I/O functions */ /** Interrupt driven FIFO fill function */
int (*fifo_fill)(struct device *dev, const uint8_t *tx_data, int len); int (*fifo_fill)(struct device *dev, const uint8_t *tx_data, int len);
/** Interrupt driven FIFO read function */
int (*fifo_read)(struct device *dev, uint8_t *rx_data, const int size); int (*fifo_read)(struct device *dev, uint8_t *rx_data, const int size);
/** Interrupt driven transfer enabling function */
void (*irq_tx_enable)(struct device *dev); void (*irq_tx_enable)(struct device *dev);
/** Interrupt driven transfer disabling function */
void (*irq_tx_disable)(struct device *dev); void (*irq_tx_disable)(struct device *dev);
/** Interrupt driven transfer ready function */
int (*irq_tx_ready)(struct device *dev); int (*irq_tx_ready)(struct device *dev);
/** Interrupt driven receiver enabling function */
void (*irq_rx_enable)(struct device *dev); void (*irq_rx_enable)(struct device *dev);
/** Interrupt driven receiver disabling function */
void (*irq_rx_disable)(struct device *dev); void (*irq_rx_disable)(struct device *dev);
/** Interrupt driven transfer empty function */
int (*irq_tx_empty)(struct device *dev); int (*irq_tx_empty)(struct device *dev);
/** Interrupt driven receiver ready function */
int (*irq_rx_ready)(struct device *dev); int (*irq_rx_ready)(struct device *dev);
/** Interrupt driven error enabling function */
void (*irq_err_enable)(struct device *dev); void (*irq_err_enable)(struct device *dev);
/** Interrupt driven error disabling function */
void (*irq_err_disable)(struct device *dev); void (*irq_err_disable)(struct device *dev);
/** Interrupt driven pending status function */
int (*irq_is_pending)(struct device *dev); int (*irq_is_pending)(struct device *dev);
/** Interrupt driven interrupt update function */
int (*irq_update)(struct device *dev); int (*irq_update)(struct device *dev);
/** Interrupt driven input hook function */
int (*irq_input_hook)(struct device *dev, uint8_t byte); int (*irq_input_hook)(struct device *dev, uint8_t byte);
#endif #endif
@ -115,12 +158,15 @@ struct uart_driver_api {
}; };
/** /**
* @brief Check whether an error was detected * @brief Check whether an error was detected.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return one of UART_ERROR_OVERRUN, UART_ERROR_PARITY, UART_ERROR_FRAMING, * @retval UART_ERROR_OVERRUN if an overrun error was detected.
* UART_ERROR_BREAK if an error was detected, 0 otherwise. * @retval UART_ERROR_PARITY if a parity error was detected.
* @retval UART_ERROR_FRAMING if a framing error was detected.
* @retval UART_ERROR_BREAK if a break error was detected.
* @retval 0 Otherwise.
*/ */
static inline int uart_err_check(struct device *dev) static inline int uart_err_check(struct device *dev)
{ {
@ -137,11 +183,12 @@ static inline int uart_err_check(struct device *dev)
/** /**
* @brief Poll the device for input. * @brief Poll the device for input.
* *
* @param dev UART device struct * @param dev UART device structure.
* @param p_char Pointer to character * @param p_char Pointer to character.
* *
* @return 0 if a character arrived, -1 if the input buffer if empty, * @retval 0 If a character arrived.
* -DEV_INVALID_OP if operation not supported. * @retval -1 If the input buffer if empty.
* @retval DEV_INVALID_OP If the operation is not supported.
*/ */
static inline int uart_poll_in(struct device *dev, unsigned char *p_char) static inline int uart_poll_in(struct device *dev, unsigned char *p_char)
{ {
@ -154,16 +201,17 @@ static inline int uart_poll_in(struct device *dev, unsigned char *p_char)
/** /**
* @brief Output a character in polled mode. * @brief Output a character in polled mode.
* *
* Checks if the transmitter is empty. If empty, a character is written to * This routine checks if the transmitter is empty.
* the data register. * When the transmitter is empty, it writes a character to the data
* register.
* *
* If the hardware flow control is enabled then the handshake signal CTS has to * To send a character when hardware flow control is enabled, the handshake
* be asserted in order to send a character. * signal CTS must be asserted.
* *
* @param dev UART device struct * @param dev UART device structure.
* @param out_char Character to send * @param out_char Character to send.
* *
* @return Sent character * @retval char Sent character.
*/ */
static inline unsigned char uart_poll_out(struct device *dev, static inline unsigned char uart_poll_out(struct device *dev,
unsigned char out_char) unsigned char out_char)
@ -178,13 +226,13 @@ static inline unsigned char uart_poll_out(struct device *dev,
#ifdef CONFIG_UART_INTERRUPT_DRIVEN #ifdef CONFIG_UART_INTERRUPT_DRIVEN
/** /**
* @brief Fill FIFO with data * @brief Fill FIFO with data.
* *
* @param dev UART device struct * @param dev UART device structure.
* @param tx_data Data to transmit * @param tx_data Data to transmit.
* @param size Number of bytes to send * @param size Number of bytes to send.
* *
* @return Number of bytes sent * @return Number of bytes sent.
*/ */
static inline int uart_fifo_fill(struct device *dev, const uint8_t *tx_data, static inline int uart_fifo_fill(struct device *dev, const uint8_t *tx_data,
int size) int size)
@ -200,13 +248,13 @@ static inline int uart_fifo_fill(struct device *dev, const uint8_t *tx_data,
} }
/** /**
* @brief Read data from FIFO * @brief Read data from FIFO.
* *
* @param dev UART device struct * @param dev UART device structure.
* @param rx_data Data container * @param rx_data Data container.
* @param size Container size * @param size Container size.
* *
* @return Number of bytes read * @return Number of bytes read.
*/ */
static inline int uart_fifo_read(struct device *dev, uint8_t *rx_data, static inline int uart_fifo_read(struct device *dev, uint8_t *rx_data,
const int size) const int size)
@ -222,9 +270,9 @@ static inline int uart_fifo_read(struct device *dev, uint8_t *rx_data,
} }
/** /**
* @brief Enable TX interrupt in IER * @brief Enable TX interrupt in IER.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return N/A * @return N/A
*/ */
@ -238,9 +286,9 @@ static inline void uart_irq_tx_enable(struct device *dev)
} }
} }
/** /**
* @brief Disable TX interrupt in IER * @brief Disable TX interrupt in IER.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return N/A * @return N/A
*/ */
@ -255,11 +303,12 @@ static inline void uart_irq_tx_disable(struct device *dev)
} }
/** /**
* @brief Check if Tx IRQ has been raised * @brief Check if Tx IRQ has been raised.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return 1 if an IRQ is ready, 0 otherwise * @retval 1 If an IRQ is ready.
* @retval 0 Otherwise.
*/ */
static inline int uart_irq_tx_ready(struct device *dev) static inline int uart_irq_tx_ready(struct device *dev)
{ {
@ -274,9 +323,9 @@ static inline int uart_irq_tx_ready(struct device *dev)
} }
/** /**
* @brief Enable RX interrupt in IER * @brief Enable RX interrupt in IER.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return N/A * @return N/A
*/ */
@ -291,9 +340,9 @@ static inline void uart_irq_rx_enable(struct device *dev)
} }
/** /**
* @brief Disable RX interrupt in IER * @brief Disable RX interrupt in IER.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return N/A * @return N/A
*/ */
@ -310,9 +359,10 @@ static inline void uart_irq_rx_disable(struct device *dev)
/** /**
* @brief Check if nothing remains to be transmitted * @brief Check if nothing remains to be transmitted
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return 1 if nothing remains to be transmitted, 0 otherwise * @retval 1 If nothing remains to be transmitted.
* @retval 0 Otherwise.
*/ */
static inline int uart_irq_tx_empty(struct device *dev) static inline int uart_irq_tx_empty(struct device *dev)
{ {
@ -327,11 +377,12 @@ static inline int uart_irq_tx_empty(struct device *dev)
} }
/** /**
* @brief Check if Rx IRQ has been raised * @brief Check if Rx IRQ has been raised.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return 1 if an IRQ is ready, 0 otherwise * @retval 1 If an IRQ is ready.
* @retval 0 Otherwise.
*/ */
static inline int uart_irq_rx_ready(struct device *dev) static inline int uart_irq_rx_ready(struct device *dev)
{ {
@ -345,9 +396,9 @@ static inline int uart_irq_rx_ready(struct device *dev)
return 0; return 0;
} }
/** /**
* @brief Enable error interrupt in IER * @brief Enable error interrupt in IER.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return N/A * @return N/A
*/ */
@ -362,11 +413,12 @@ static inline void uart_irq_err_enable(struct device *dev)
} }
/** /**
* @brief Disable error interrupt in IER * @brief Disable error interrupt in IER.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return 1 if an IRQ is ready, 0 otherwise * @retval 1 If an IRQ is ready.
* @retval 0 Otherwise.
*/ */
static inline void uart_irq_err_disable(struct device *dev) static inline void uart_irq_err_disable(struct device *dev)
{ {
@ -379,11 +431,12 @@ static inline void uart_irq_err_disable(struct device *dev)
} }
/** /**
* @brief Check if any IRQ is pending * @brief Check if any IRQs is pending.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return 1 if an IRQ is pending, 0 otherwise * @retval 1 If an IRQ is pending.
* @retval 0 Otherwise.
*/ */
static inline int uart_irq_is_pending(struct device *dev) static inline int uart_irq_is_pending(struct device *dev)
@ -399,11 +452,11 @@ static inline int uart_irq_is_pending(struct device *dev)
} }
/** /**
* @brief Update cached contents of IIR * @brief Update cached contents of IIR.
* *
* @param dev UART device struct * @param dev UART device structure.
* *
* @return always 1 * @retval 1 Always.
*/ */
static inline int uart_irq_update(struct device *dev) static inline int uart_irq_update(struct device *dev)
{ {
@ -418,16 +471,17 @@ static inline int uart_irq_update(struct device *dev)
} }
/** /**
* @brief Invoke the UART input hook routine if installed * @brief Invoke the UART input hook routine if it is installed.
* *
* The input hook is a custom handler invoked by the ISR on each received * The input hook is a custom handler invoked by the ISR on each received
* character. It allows the detection of a character escape sequence that may * character. It allows the detection of a character escape sequence that can
* be used to override the behavior of the ISR handler. * be used to override the behavior of the ISR handler.
* *
* @param dev UART device struct * @param dev UART device structure.
* @param byte Byte to process * @param byte Byte to process.
* *
* @return 1 if character processing must stop, 0 or if it is to continue * @retval 1 If character processing must stop.
* @retval 0 If it should continue.
*/ */
static inline int uart_irq_input_hook(struct device *dev, uint8_t byte) static inline int uart_irq_input_hook(struct device *dev, uint8_t byte)
{ {
@ -443,10 +497,10 @@ static inline int uart_irq_input_hook(struct device *dev, uint8_t byte)
} }
/** /**
* @brief Set the UART input hook routine * @brief Set the UART input hook routine.
* *
* @param dev UART device struct * @param dev UART device structure.
* @param hook Routine to use as UART input hook * @param hook Routine to use as UART input hook.
* *
* @return N/A * @return N/A
*/ */
@ -467,13 +521,14 @@ static inline void uart_irq_input_hook_set(struct device *dev,
#ifdef CONFIG_UART_LINE_CTRL #ifdef CONFIG_UART_LINE_CTRL
/** /**
* @brief Manipualte line control for UART. * @brief Manipulate line control for UART.
* *
* @param dev UART device struct * @param dev UART device structure.
* @param ctrl The line control to be manipulated * @param ctrl The line control to manipulate.
* @param val Value to set the line control * @param val Value to set to the line control.
* *
* @return DEV_OK if successful, failed otherwise * @retval DEV_OK If successful.
* @retval failed Otherwise.
*/ */
static inline int uart_line_ctrl_set(struct device *dev, static inline int uart_line_ctrl_set(struct device *dev,
uint32_t ctrl, uint32_t val) uint32_t ctrl, uint32_t val)
@ -494,16 +549,17 @@ static inline int uart_line_ctrl_set(struct device *dev,
#ifdef CONFIG_UART_DRV_CMD #ifdef CONFIG_UART_DRV_CMD
/** /**
* @brief Send extra command to driver * @brief Send extra command to driver.
* *
* Implementation and accepted commands are driver specific. * Implementation and accepted commands are driver specific.
* Refer to driver for more information. * Refer to the drivers for more information.
* *
* @param dev UART device struct * @param dev UART device structure.
* @param cmd Command to driver * @param cmd Command to driver.
* @param p Parameter to the command * @param p Parameter to the command.
* *
* @return DEV_OK if successful, failed otherwise * @retval DEV_OK If successful.
* @retval failed Otherwise.
*/ */
static inline int uart_drv_cmd(struct device *dev, uint32_t cmd, uint32_t p) static inline int uart_drv_cmd(struct device *dev, uint32_t cmd, uint32_t p)
{ {