/* Copyright (c) 2012 The Chromium OS Authors. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the LICENSE file.
 */

/* uart.h - UART module for Chrome EC */

#ifndef __CROS_EC_UART_H
#define __CROS_EC_UART_H

#include <stdarg.h>  /* For va_list */
#include "common.h"


/* Initializes the UART module. */
int uart_init(void);

/* Return non-zero if UART init has completed. */
int uart_init_done(void);

/* Enables console mode if <enable>!=0.  In console mode:
 *    - Input is echoed
 *    - Input CRLF and CR are translated to LF
 *    - Input backspace will remove characters from the input buffer (which
 *      is pretty much only useful if the input handler is only triggered on
 *      newline)
 *    - Output LF is translated to CRLF */
void uart_set_console_mode(int enable);

/*****************************************************************************/
/* Output functions
 *
 * Output is buffered.  If the buffer overflows, subsequent output is
 * discarded. */

/* Put a null-terminated string to the UART, like fputs().
 *
 * Returns error if output was truncated. */
int uart_puts(const char *outstr);

/* Print formatted output to the UART, like printf().
 *
 * See printf.h for valid formatting codes. */
int uart_printf(const char *format, ...);

/* Print formatted output to the UART, like vprintf().
 *
 * See printf.h for valid formatting codes. */
int uart_vprintf(const char *format, va_list args);

/* Flushes output.  Blocks until UART has transmitted all output. */
void uart_flush_output(void);

/* Flushes output.
 *
 * Blocks until UART has transmitted all output, even in a high priority
 * interrupt context. */
void uart_emergency_flush(void);

/* Like uart_printf(), but bypasses the transmit buffer.
 *
 * Blocks until UART has transmitted the formatted output, even in a high
 * priority interrupt context. */
int uart_emergency_printf(const char *format, ...);

/*****************************************************************************/
/* Input functions
 *
 * Input is buffered.  If the buffer overflows, the oldest input in
 * the buffer is discarded to make room for the new input.
 *
 * Input lines may be terminated by CR ('\r'), LF ('\n'), or CRLF; all
 * are translated to newline. */

/* Flushes input buffer, discarding all input. */
void uart_flush_input(void);

/* Non-destructively checks for a character in the input buffer.
 *
 * Returns the offset into the input buffer of character <c>, or -1 if
 * it is not in the input buffer. */
int uart_peek(int c);

/* Reads a single character of input, similar to fgetc().  Returns the
 * character, or -1 if no input waiting. */
int uart_getc(void);

/* Reads characters from the UART, similar to fgets().
 *
 * Reads input until one of the following conditions is met:
 *    (1)  <size-1> characters have been read.
 *    (2)  A newline ('\n') has been read.
 *    (3)  The input buffer is empty.
 *
 * Condition (3) means this call never blocks.  This is important
 * because it prevents a race condition where the caller calls
 * UartPeek() to see if input is waiting, or is notified by the
 * callack that input is waiting, but then the input buffer overflows
 * or someone else grabs the input before UartGets() is called.
 *
 * Characters are stored in <dest> and are null-terminated.
 * Characters include the newline if present, so that the caller can
 * distinguish between a complete line and a truncated one.  If the
 * input buffer is empty, a null-terminated empty string ("") is
 * returned.
 *
 * Returns the number of characters read (not counting the terminating
 * null). */
int uart_gets(char *dest, int size);

/* TODO: getc(), putc() equivalents? */

/*****************************************************************************/
/* Hardware UART driver functions */

/* Flushes the transmit FIFO. */
void uart_tx_flush(void);

/* Returns true if there is room to transmit a character immediatly. */
int uart_tx_ready(void);

/* Returns true if the UART has character available. */
int uart_rx_available(void);

/**
 * Sends a character to the UART data register.
 * If the transmit FIFO is full, this function blocks until there is space.
 *
 * c : byte to send.
 */
void uart_write_char(char c);

/**
 * Reads and returns one char from the UART data register.
 *
 * Called when uart_rx_available once returns true.
 */
int uart_read_char(void);

/**
 * Disables all UART related IRQs.
 *
 * To avoid concurrent accesses on UART management variables.
 */
void uart_disable_interrupt(void);

/* Re-enables UART IRQs. */
void uart_enable_interrupt(void);

/**
 * Re-enables the UART transmit interrupt.
 *
 * It also forces triggering an interrupt if the hardware doesn't automatically
 * trigger it when the transmit buffer was filled beforehand.
 */
void uart_tx_start(void);

/* Disables the UART transmit interrupt. */
void uart_tx_stop(void);

/* Returns true if the UART transmit interrupt is disabled */
int uart_tx_stopped(void);

/**
 * Helper for UART processing.
 * Read the input FIFO until empty, then fill the output FIFO until the transmit
 * buffer is empty or the FIFO full.
 *
 * Designed to be called from the driver interrupt handler.
 */
void uart_process(void);


/*****************************************************************************/
/* COMx functions */

/* Enables comx interrupts */
void uart_comx_enable(void);

/* Returns non-zero if ok to put a character via uart_comx_putc(). */
int uart_comx_putc_ok(void);

/* Puts a character to the COMx UART interface. */
void uart_comx_putc(int c);

#endif  /* __CROS_EC_UART_H */