zephyr/include/uart.h

/* uart.h - public UART driver APIs */

/*
 * Copyright (c) 2015 Wind River Systems, Inc.
 *
 * 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.
 */

#ifndef __INCuarth
#define __INCuarth

/**
 * @brief UART Interface
 * @defgroup uart_interface UART Interface
 * @ingroup io_interfaces
 * @{
 */

#ifdef __cplusplus
extern "C" {
#endif

#include <stddef.h>

#include <device.h>

#ifdef CONFIG_PCI
#include <pci/pci.h>
#include <pci/pci_mgr.h>
#endif
/* options for uart init */
#define UART_OPTION_AFCE 0x01

/** Common line controls for UART */
#define LINE_CTRL_BAUD_RATE	(1 << 0)
#define LINE_CTRL_RTS		(1 << 1)
#define LINE_CTRL_DTR		(1 << 2)

/** Common errors types for UART */
#define UART_ERROR_OVERRUN  (1 << 0) /* overrun error */
#define UART_ERROR_PARITY   (1 << 1) /* parity error  */
#define UART_ERROR_FRAMING  (1 << 2) /* framing error */
/* 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 +
 * stop bits.
 */
#define UART_ERROR_BREAK    (1 << 3)

/** UART device configuration */
struct uart_device_config {
	/**
	 * Base port number
	 * or memory mapped base address
	 * or register address
	 */
	union {
		uint32_t port;
		uint8_t *base;
		uint32_t regs;
	};

	uint32_t sys_clk_freq;	/* System clock frequency in Hz */

#ifdef CONFIG_PCI
	struct pci_dev_info  pci_dev;
#endif /* CONFIG_PCI */
};

/**< Driver API struct */
struct uart_driver_api {
	/* console I/O functions */
	int (*poll_in)(struct device *dev, unsigned char *p_char);
	unsigned char (*poll_out)(struct device *dev, unsigned char out_char);

	int (*err_check)(struct device *dev);

#ifdef CONFIG_UART_INTERRUPT_DRIVEN

	/* interrupt driven I/O functions */
	int (*fifo_fill)(struct device *dev, const uint8_t *tx_data, int len);
	int (*fifo_read)(struct device *dev, uint8_t *rx_data, const int size);
	void (*irq_tx_enable)(struct device *dev);
	void (*irq_tx_disable)(struct device *dev);
	int (*irq_tx_ready)(struct device *dev);
	void (*irq_rx_enable)(struct device *dev);
	void (*irq_rx_disable)(struct device *dev);
	int (*irq_tx_empty)(struct device *dev);
	int (*irq_rx_ready)(struct device *dev);
	void (*irq_err_enable)(struct device *dev);
	void (*irq_err_disable)(struct device *dev);
	int (*irq_is_pending)(struct device *dev);
	int (*irq_update)(struct device *dev);
	int (*irq_input_hook)(struct device *dev, uint8_t byte);

#endif

#ifdef CONFIG_UART_LINE_CTRL
	int (*line_ctrl_set)(struct device *dev, uint32_t ctrl, uint32_t val);
#endif

#ifdef CONFIG_UART_DRV_CMD
	int (*drv_cmd)(struct device *dev, uint32_t cmd, uint32_t p);
#endif

};

/**
 * @brief Check whether an error was detected
 *
 * @param dev UART device struct
 *
 * @return one of UART_ERROR_OVERRUN, UART_ERROR_PARITY, UART_ERROR_FRAMING,
 * UART_ERROR_BREAK if an error was detected, 0 otherwise.
 */
static inline int uart_err_check(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->err_check) {
		return api->err_check(dev);
	}
	return 0;
}


/**
 * @brief Poll the device for input.
 *
 * @param dev UART device struct
 * @param p_char Pointer to character
 *
 * @return 0 if a character arrived, -1 if the input buffer if empty,
 *         -DEV_INVALID_OP if operation not supported.
 */
static inline int uart_poll_in(struct device *dev, unsigned char *p_char)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	return api->poll_in(dev, p_char);
}

/**
 * @brief Output a character in polled mode.
 *
 * Checks if the transmitter is empty. If empty, a character is written to
 * the data register.
 *
 * If the hardware flow control is enabled then the handshake signal CTS has to
 * be asserted in order to send a character.
 *
 * @param dev UART device struct
 * @param out_char Character to send
 *
 * @return Sent character
 */
static inline unsigned char uart_poll_out(struct device *dev,
					  unsigned char out_char)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	return api->poll_out(dev, out_char);
}


#ifdef CONFIG_UART_INTERRUPT_DRIVEN

/**
 * @brief Fill FIFO with data
 *
 * @param dev UART device struct
 * @param tx_data Data to transmit
 * @param size Number of bytes to send
 *
 * @return Number of bytes sent
 */
static inline int uart_fifo_fill(struct device *dev, const uint8_t *tx_data,
				 int size)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->fifo_fill) {
		return api->fifo_fill(dev, tx_data, size);
	}

	return 0;
}

/**
 * @brief Read data from FIFO
 *
 * @param dev UART device struct
 * @param rx_data Data container
 * @param size Container size
 *
 * @return Number of bytes read
 */
static inline int uart_fifo_read(struct device *dev, uint8_t *rx_data,
				 const int size)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->fifo_read) {
		return api->fifo_read(dev, rx_data, size);
	}

	return 0;
}

/**
 * @brief Enable TX interrupt in IER
 *
 * @param dev UART device struct
 *
 * @return N/A
 */
static inline void uart_irq_tx_enable(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_tx_enable) {
		api->irq_tx_enable(dev);
	}
}
/**
 * @brief Disable TX interrupt in IER
 *
 * @param dev UART device struct
 *
 * @return N/A
 */
static inline void uart_irq_tx_disable(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_tx_disable) {
		api->irq_tx_disable(dev);
	}
}

/**
 * @brief Check if Tx IRQ has been raised
 *
 * @param dev UART device struct
 *
 * @return 1 if an IRQ is ready, 0 otherwise
 */
static inline int uart_irq_tx_ready(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_tx_ready) {
		return api->irq_tx_ready(dev);
	}

	return 0;
}

/**
 * @brief Enable RX interrupt in IER
 *
 * @param dev UART device struct
 *
 * @return N/A
 */
static inline void uart_irq_rx_enable(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_rx_enable) {
		api->irq_rx_enable(dev);
	}
}

/**
 * @brief Disable RX interrupt in IER
 *
 * @param dev UART device struct
 *
 * @return N/A
 */
static inline void uart_irq_rx_disable(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_tx_disable) {
		api->irq_tx_disable(dev);
	}
}

/**
 * @brief Check if nothing remains to be transmitted
 *
 * @param dev UART device struct
 *
 * @return 1 if nothing remains to be transmitted, 0 otherwise
 */
static inline int uart_irq_tx_empty(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_tx_empty) {
		return api->irq_tx_empty(dev);
	}

	return 0;
}

/**
 * @brief Check if Rx IRQ has been raised
 *
 * @param dev UART device struct
 *
 * @return 1 if an IRQ is ready, 0 otherwise
 */
static inline int uart_irq_rx_ready(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_rx_ready) {
		return api->irq_rx_ready(dev);
	}

	return 0;
}
/**
 * @brief Enable error interrupt in IER
 *
 * @param dev UART device struct
 *
 * @return N/A
 */
static inline void uart_irq_err_enable(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_err_enable) {
		api->irq_err_enable(dev);
	}
}

/**
 * @brief Disable error interrupt in IER
 *
 * @param dev UART device struct
 *
 * @return 1 if an IRQ is ready, 0 otherwise
 */
static inline void uart_irq_err_disable(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_err_disable) {
		api->irq_err_disable(dev);
	}
}

/**
 * @brief Check if any IRQ is pending
 *
 * @param dev UART device struct
 *
 * @return 1 if an IRQ is pending, 0 otherwise
 */

static inline int uart_irq_is_pending(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_is_pending)	{
		return api->irq_is_pending(dev);
	}

	return 0;
}

/**
 * @brief Update cached contents of IIR
 *
 * @param dev UART device struct
 *
 * @return always 1
 */
static inline int uart_irq_update(struct device *dev)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;
	if (api && api->irq_update) {
		return api->irq_update(dev);
	}

	return 0;
}

/**
 * @brief Invoke the UART input hook routine if installed
 *
 * 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
 * be used to override the behavior of the ISR handler.
 *
 * @param dev UART device struct
 * @param byte Byte to process
 *
 * @return 1 if character processing must stop, 0 or if it is to continue
 */
static inline int uart_irq_input_hook(struct device *dev, uint8_t byte)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;

	if ((api != NULL) && (api->irq_input_hook != NULL)) {
		return api->irq_input_hook(dev, byte);
	}

	return 0;
}

/**
 * @brief Set the UART input hook routine
 *
 * @param dev UART device struct
 * @param hook Routine to use as UART input hook
 *
 * @return N/A
 */
static inline void uart_irq_input_hook_set(struct device *dev,
		int (*hook)(struct device *, uint8_t))
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;

	if (api != NULL) {
		api->irq_input_hook = hook;
	}
}

#endif

#ifdef CONFIG_UART_LINE_CTRL

/**
 * @brief Manipualte line control for UART.
 *
 * @param dev UART device struct
 * @param ctrl The line control to be manipulated
 * @param val Value to set the line control
 *
 * @return DEV_OK if successful, failed otherwise
 */
static inline int uart_line_ctrl_set(struct device *dev,
				     uint32_t ctrl, uint32_t val)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;

	if (api && api->line_ctrl_set) {
		return api->line_ctrl_set(dev, ctrl, val);
	}

	return DEV_INVALID_OP;
}

#endif /* CONFIG_UART_LINE_CTRL */

#ifdef CONFIG_UART_DRV_CMD

/**
 * @brief Send extra command to driver
 *
 * Implementation and accepted commands are driver specific.
 * Refer to driver for more information.
 *
 * @param dev UART device struct
 * @param cmd Command to driver
 * @param p Parameter to the command
 *
 * @return DEV_OK if successful, failed otherwise
 */
static inline int uart_drv_cmd(struct device *dev, uint32_t cmd, uint32_t p)
{
	struct uart_driver_api *api;

	api = (struct uart_driver_api *)dev->driver_api;

	if (api && api->drv_cmd) {
		return api->drv_cmd(dev, cmd, p);
	}

	return DEV_INVALID_OP;
}

#endif /* CONFIG_UART_DRV_CMD */

#ifdef __cplusplus
}
#endif

/**
 * @}
 */

#endif /* __INCuarth */