Skip to content

drivers: serial: Clarify usage of TX/RX IRQ predicates. #159

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 13, 2017
Merged

drivers: serial: Clarify usage of TX/RX IRQ predicates. #159

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions drivers/serial/uart_cc32xx.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,7 +202,7 @@ static void uart_cc32xx_irq_rx_disable(struct device *dev)
MAP_UARTIntDisable((unsigned long)config->base, UART_INT_RX);
}

static int uart_cc32xx_irq_tx_empty(struct device *dev)
static int uart_cc32xx_irq_tx_complete(struct device *dev)
{
const struct uart_device_config *config = DEV_CFG(dev);

Expand Down Expand Up @@ -296,7 +296,7 @@ static const struct uart_driver_api uart_cc32xx_driver_api = {
.irq_tx_ready = uart_cc32xx_irq_tx_ready,
.irq_rx_enable = uart_cc32xx_irq_rx_enable,
.irq_rx_disable = uart_cc32xx_irq_rx_disable,
.irq_tx_empty = uart_cc32xx_irq_tx_empty,
.irq_tx_complete = uart_cc32xx_irq_tx_complete,
.irq_rx_ready = uart_cc32xx_irq_rx_ready,
.irq_err_enable = uart_cc32xx_irq_err_enable,
.irq_err_disable = uart_cc32xx_irq_err_disable,
Expand Down
4 changes: 2 additions & 2 deletions drivers/serial/uart_cmsdk_apb.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -316,7 +316,7 @@ static void uart_cmsdk_apb_irq_rx_disable(struct device *dev)
*
* @return 1 if an interrupt is ready, 0 otherwise
*/
static int uart_cmsdk_apb_irq_tx_empty(struct device *dev)
static int uart_cmsdk_apb_irq_tx_complete(struct device *dev)
{
return uart_cmsdk_apb_irq_tx_ready(dev);
}
Expand Down Expand Up @@ -435,7 +435,7 @@ static const struct uart_driver_api uart_cmsdk_apb_driver_api = {
.irq_tx_ready = uart_cmsdk_apb_irq_tx_ready,
.irq_rx_enable = uart_cmsdk_apb_irq_rx_enable,
.irq_rx_disable = uart_cmsdk_apb_irq_rx_disable,
.irq_tx_empty = uart_cmsdk_apb_irq_tx_empty,
.irq_tx_complete = uart_cmsdk_apb_irq_tx_complete,
.irq_rx_ready = uart_cmsdk_apb_irq_rx_ready,
.irq_err_enable = uart_cmsdk_apb_irq_err_enable,
.irq_err_disable = uart_cmsdk_apb_irq_err_disable,
Expand Down
4 changes: 2 additions & 2 deletions drivers/serial/uart_fe310.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,7 @@ static int uart_fe310_irq_tx_ready(struct device *dev)
*
* @return 1 if nothing remains to be transmitted, 0 otherwise
*/
static int uart_fe310_irq_tx_empty(struct device *dev)
static int uart_fe310_irq_tx_complete(struct device *dev)
{
volatile struct uart_fe310_regs_t *uart = DEV_UART(dev);

Expand Down Expand Up @@ -361,7 +361,7 @@ static const struct uart_driver_api uart_fe310_driver_api = {
.irq_tx_enable = uart_fe310_irq_tx_enable,
.irq_tx_disable = uart_fe310_irq_tx_disable,
.irq_tx_ready = uart_fe310_irq_tx_ready,
.irq_tx_empty = uart_fe310_irq_tx_empty,
.irq_tx_complete = uart_fe310_irq_tx_complete,
.irq_rx_enable = uart_fe310_irq_rx_enable,
.irq_rx_disable = uart_fe310_irq_rx_disable,
.irq_rx_ready = uart_fe310_irq_rx_ready,
Expand Down
6 changes: 3 additions & 3 deletions drivers/serial/uart_mcux.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ static void uart_mcux_irq_tx_disable(struct device *dev)
UART_DisableInterrupts(config->base, mask);
}

static int uart_mcux_irq_tx_empty(struct device *dev)
static int uart_mcux_irq_tx_complete(struct device *dev)
{
const struct uart_mcux_config *config = dev->config->config_info;
u32_t flags = UART_GetStatusFlags(config->base);
Expand All @@ -138,7 +138,7 @@ static int uart_mcux_irq_tx_ready(struct device *dev)
u32_t mask = kUART_TxDataRegEmptyInterruptEnable;

return (UART_GetEnabledInterrupts(config->base) & mask)
&& uart_mcux_irq_tx_empty(dev);
&& uart_mcux_irq_tx_complete(dev);
}

static void uart_mcux_irq_rx_enable(struct device *dev)
Expand Down Expand Up @@ -254,7 +254,7 @@ static const struct uart_driver_api uart_mcux_driver_api = {
.fifo_read = uart_mcux_fifo_read,
.irq_tx_enable = uart_mcux_irq_tx_enable,
.irq_tx_disable = uart_mcux_irq_tx_disable,
.irq_tx_empty = uart_mcux_irq_tx_empty,
.irq_tx_complete = uart_mcux_irq_tx_complete,
.irq_tx_ready = uart_mcux_irq_tx_ready,
.irq_rx_enable = uart_mcux_irq_rx_enable,
.irq_rx_disable = uart_mcux_irq_rx_disable,
Expand Down
6 changes: 3 additions & 3 deletions drivers/serial/uart_mcux_lpsci.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ static void mcux_lpsci_irq_tx_disable(struct device *dev)
LPSCI_DisableInterrupts(config->base, mask);
}

static int mcux_lpsci_irq_tx_empty(struct device *dev)
static int mcux_lpsci_irq_tx_complete(struct device *dev)
{
const struct mcux_lpsci_config *config = dev->config->config_info;
u32_t flags = LPSCI_GetStatusFlags(config->base);
Expand All @@ -141,7 +141,7 @@ static int mcux_lpsci_irq_tx_ready(struct device *dev)
u32_t mask = kLPSCI_TxDataRegEmptyInterruptEnable;

return (LPSCI_GetEnabledInterrupts(config->base) & mask)
&& mcux_lpsci_irq_tx_empty(dev);
&& mcux_lpsci_irq_tx_complete(dev);
}

static void mcux_lpsci_irq_rx_enable(struct device *dev)
Expand Down Expand Up @@ -258,7 +258,7 @@ static const struct uart_driver_api mcux_lpsci_driver_api = {
.fifo_read = mcux_lpsci_fifo_read,
.irq_tx_enable = mcux_lpsci_irq_tx_enable,
.irq_tx_disable = mcux_lpsci_irq_tx_disable,
.irq_tx_empty = mcux_lpsci_irq_tx_empty,
.irq_tx_complete = mcux_lpsci_irq_tx_complete,
.irq_tx_ready = mcux_lpsci_irq_tx_ready,
.irq_rx_enable = mcux_lpsci_irq_rx_enable,
.irq_rx_disable = mcux_lpsci_irq_rx_disable,
Expand Down
6 changes: 3 additions & 3 deletions drivers/serial/uart_mcux_lpuart.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,7 +127,7 @@ static void mcux_lpuart_irq_tx_disable(struct device *dev)
LPUART_DisableInterrupts(config->base, mask);
}

static int mcux_lpuart_irq_tx_empty(struct device *dev)
static int mcux_lpuart_irq_tx_complete(struct device *dev)
{
const struct mcux_lpuart_config *config = dev->config->config_info;
u32_t flags = LPUART_GetStatusFlags(config->base);
Expand All @@ -141,7 +141,7 @@ static int mcux_lpuart_irq_tx_ready(struct device *dev)
u32_t mask = kLPUART_TxDataRegEmptyInterruptEnable;

return (LPUART_GetEnabledInterrupts(config->base) & mask)
&& mcux_lpuart_irq_tx_empty(dev);
&& mcux_lpuart_irq_tx_complete(dev);
}

static void mcux_lpuart_irq_rx_enable(struct device *dev)
Expand Down Expand Up @@ -258,7 +258,7 @@ static const struct uart_driver_api mcux_lpuart_driver_api = {
.fifo_read = mcux_lpuart_fifo_read,
.irq_tx_enable = mcux_lpuart_irq_tx_enable,
.irq_tx_disable = mcux_lpuart_irq_tx_disable,
.irq_tx_empty = mcux_lpuart_irq_tx_empty,
.irq_tx_complete = mcux_lpuart_irq_tx_complete,
.irq_tx_ready = mcux_lpuart_irq_tx_ready,
.irq_rx_enable = mcux_lpuart_irq_rx_enable,
.irq_rx_disable = mcux_lpuart_irq_rx_disable,
Expand Down
4 changes: 2 additions & 2 deletions drivers/serial/uart_nrf5.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -398,7 +398,7 @@ static void uart_nrf5_irq_rx_disable(struct device *dev)
}

/** Interrupt driven transfer empty function */
static int uart_nrf5_irq_tx_empty(struct device *dev)
static int uart_nrf5_irq_tx_complete(struct device *dev)
{
volatile struct _uart *uart = UART_STRUCT(dev);

Expand Down Expand Up @@ -481,7 +481,7 @@ static const struct uart_driver_api uart_nrf5_driver_api = {
.irq_tx_ready = uart_nrf5_irq_tx_ready, /** IRQ transfer ready function */
.irq_rx_enable = uart_nrf5_irq_rx_enable, /** IRQ receiver enabling function */
.irq_rx_disable = uart_nrf5_irq_rx_disable, /** IRQ receiver disabling function */
.irq_tx_empty = uart_nrf5_irq_tx_empty, /** IRQ transfer empty function */
.irq_tx_complete = uart_nrf5_irq_tx_complete, /** IRQ transfer complete function */
.irq_rx_ready = uart_nrf5_irq_rx_ready, /** IRQ receiver ready function */
.irq_err_enable = uart_nrf5_irq_err_enable, /** IRQ error enabling function */
.irq_err_disable = uart_nrf5_irq_err_disable, /** IRQ error disabling function */
Expand Down
4 changes: 2 additions & 2 deletions drivers/serial/uart_ns16550.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -508,7 +508,7 @@ static int uart_ns16550_irq_tx_ready(struct device *dev)
*
* @return 1 if nothing remains to be transmitted, 0 otherwise
*/
static int uart_ns16550_irq_tx_empty(struct device *dev)
static int uart_ns16550_irq_tx_complete(struct device *dev)
{
return (INBYTE(LSR(dev)) & (LSR_TEMT | LSR_THRE)) == (LSR_TEMT | LSR_THRE);
}
Expand Down Expand Up @@ -721,7 +721,7 @@ static const struct uart_driver_api uart_ns16550_driver_api = {
.irq_tx_enable = uart_ns16550_irq_tx_enable,
.irq_tx_disable = uart_ns16550_irq_tx_disable,
.irq_tx_ready = uart_ns16550_irq_tx_ready,
.irq_tx_empty = uart_ns16550_irq_tx_empty,
.irq_tx_complete = uart_ns16550_irq_tx_complete,
.irq_rx_enable = uart_ns16550_irq_rx_enable,
.irq_rx_disable = uart_ns16550_irq_rx_disable,
.irq_rx_ready = uart_ns16550_irq_rx_ready,
Expand Down
4 changes: 2 additions & 2 deletions drivers/serial/uart_qmsi.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,7 @@ static int uart_qmsi_irq_tx_ready(struct device *dev)
return id == QM_UART_IIR_THR_EMPTY;
}

static int uart_qmsi_irq_tx_empty(struct device *dev)
static int uart_qmsi_irq_tx_complete(struct device *dev)
{
qm_uart_t instance = GET_CONTROLLER_INSTANCE(dev);
const u32_t mask = (QM_UART_LSR_TEMT | QM_UART_LSR_THRE);
Expand Down Expand Up @@ -433,7 +433,7 @@ static const struct uart_driver_api api = {
.irq_tx_enable = uart_qmsi_irq_tx_enable,
.irq_tx_disable = uart_qmsi_irq_tx_disable,
.irq_tx_ready = uart_qmsi_irq_tx_ready,
.irq_tx_empty = uart_qmsi_irq_tx_empty,
.irq_tx_complete = uart_qmsi_irq_tx_complete,
.irq_rx_enable = uart_qmsi_irq_rx_enable,
.irq_rx_disable = uart_qmsi_irq_rx_disable,
.irq_rx_ready = uart_qmsi_irq_rx_ready,
Expand Down
4 changes: 2 additions & 2 deletions drivers/serial/uart_stm32.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ static int uart_stm32_irq_tx_ready(struct device *dev)
return __HAL_UART_GET_FLAG(UartHandle, UART_FLAG_TXE);
}

static int uart_stm32_irq_tx_empty(struct device *dev)
static int uart_stm32_irq_tx_complete(struct device *dev)
{
struct uart_stm32_data *data = DEV_DATA(dev);
UART_HandleTypeDef *UartHandle = &data->huart;
Expand Down Expand Up @@ -250,7 +250,7 @@ static const struct uart_driver_api uart_stm32_driver_api = {
.irq_tx_enable = uart_stm32_irq_tx_enable,
.irq_tx_disable = uart_stm32_irq_tx_disable,
.irq_tx_ready = uart_stm32_irq_tx_ready,
.irq_tx_empty = uart_stm32_irq_tx_empty,
.irq_tx_complete = uart_stm32_irq_tx_complete,
.irq_rx_enable = uart_stm32_irq_rx_enable,
.irq_rx_disable = uart_stm32_irq_rx_disable,
.irq_rx_ready = uart_stm32_irq_rx_ready,
Expand Down
49 changes: 39 additions & 10 deletions include/uart.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,8 +138,8 @@ struct uart_driver_api {
/** Interrupt driven receiver disabling function */
void (*irq_rx_disable)(struct device *dev);

/** Interrupt driven transfer empty function */
int (*irq_tx_empty)(struct device *dev);
/** Interrupt driven transfer complete function */
int (*irq_tx_complete)(struct device *dev);

/** Interrupt driven receiver ready function */
int (*irq_rx_ready)(struct device *dev);
Expand Down Expand Up @@ -312,11 +312,18 @@ static inline void uart_irq_tx_disable(struct device *dev)
}

/**
* @brief Check if Tx IRQ has been raised.
* @brief Check if UART TX buffer can accept a new char
*
* @details Check if UART TX buffer can accept at least one character
* for transmission (i.e. uart_fifo_fill() will succeed and return
* non-zero). This function must be called in a UART interrupt
* handler, or its result is undefined. Before calling this function
* in the interrupt handler, uart_irq_update() must be called once per
* the handler invocation.
*
* @param dev UART device structure.
*
* @retval 1 If an IRQ is ready.
* @retval 1 If at least one char can be written to UART.
* @retval 0 Otherwise.
*/
static inline int uart_irq_tx_ready(struct device *dev)
Expand Down Expand Up @@ -363,30 +370,52 @@ static inline void uart_irq_rx_disable(struct device *dev)
}

/**
* @brief Check if nothing remains to be transmitted
* @brief Check if UART TX block finished transmission
*
* @details Check if any outgoing data buffered in UART TX block was
* fully transmitted and TX block is idle. When this condition is
* true, UART device (or whole system) can be power off. Note that
* this function is *not* useful to check if UART TX can accept more
* data, use uart_irq_tx_ready() for that. This function must be called
* in a UART interrupt handler, or its result is undefined. Before
* calling this function in the interrupt handler, uart_irq_update()
* must be called once per the handler invocation.
*
* @param dev UART device structure.
*
* @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_complete(struct device *dev)
{
const struct uart_driver_api *api = dev->driver_api;

if (api->irq_tx_empty) {
return api->irq_tx_empty(dev);
if (api->irq_tx_complete) {
return api->irq_tx_complete(dev);
}

return 0;
}
Copy link
Member

@nashif nashif May 11, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

when renaming APIs, please deprecate the old function and keep it in place.

Copy link
Contributor Author

@pfalcon pfalcon May 11, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Copy link
Member

@nashif nashif May 12, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you need to add attribute __deprecated, doxygen @deprecated is not enough :)
Look at include/dma.h for example.

Copy link
Contributor Author

@pfalcon pfalcon May 12, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Missed that, sorry. Now fixed. Used pwm.h/dma.h as a reference re: placement of __deprecated, just in case.


/**
* @brief Check if Rx IRQ has been raised.
* @deprecated This API is deprecated.
*/
static inline int __deprecated uart_irq_tx_empty(struct device *dev)
{
return uart_irq_tx_complete(dev);
}

/**
* @brief Check if UART RX buffer has a new char
*
* (i.e. uart_fifo_read() will succeed and return non-zero). This function
* must be called in a UART interrupt handler, or its result is undefined.
* Before calling this function in the interrupt handler, uart_irq_update()
* must be called once per the handler invocation.
*
* @param dev UART device structure.
*
* @retval 1 If an IRQ is ready.
* @retval 1 If a new received char is ready.
* @retval 0 Otherwise.
*/
static inline int uart_irq_rx_ready(struct device *dev)
Expand Down