uart.h File Reference

Generic UART interface for BSPACM. More...

#include <bspacm/core.h>
#include <bspacm/periph/uart_.h>

Go to the source code of this file.

Data Structures
struct	sBSPACMperiphUARTstate
struct	sBSPACMperiphUARTconfiguration
struct	sBSPACMperiphUARToperations

Macros
#define	BSPACM_PERIPH_UART_FLAG_ONLCR   0x01

Typedefs
typedef struct sBSPACMperiphUARTstate	sBSPACMperiphUARTstate
typedef sBSPACMperiphUARTstate *	hBSPACMperiphUART
typedef struct sBSPACMperiphUARTconfiguration	sBSPACMperiphUARTconfiguration
typedef enum eBSPACMperiphUARTfifoState	eBSPACMperiphUARTfifoState
typedef struct sBSPACMperiphUARToperations	sBSPACMperiphUARToperations

Enumerations
enum	eBSPACMperiphUARTfifoState {   eBSPACMperiphUARTfifoState_HWRX = 0x01, eBSPACMperiphUARTfifoState_HWTX = 0x02, eBSPACMperiphUARTfifoState_HW, eBSPACMperiphUARTfifoState_SWRX = 0x04,   eBSPACMperiphUARTfifoState_SWTX = 0x08, eBSPACMperiphUARTfifoState_DRTX = 0x10, eBSPACMperiphUARTfifoState_TX, eBSPACMperiphUARTfifoState_RX }

Functions
static BSPACM_CORE_INLINE hBSPACMperiphUART	hBSPACMperiphUARTconfigure (hBSPACMperiphUART usp, const sBSPACMperiphUARTconfiguration *cfgp)
int	iBSPACMperiphUARTread (hBSPACMperiphUART usp, void *buf, size_t count)
int	iBSPACMperiphUARTwrite (hBSPACMperiphUART usp, const void *buf, size_t count)
static BSPACM_CORE_INLINE int	iBSPACMperiphUARTfifoState (hBSPACMperiphUART usp)
int	iBSPACMperiphUARTflush (hBSPACMperiphUART usp, int fifo_mask)

Variables
const hBSPACMperiphUART	hBSPACMdefaultUART

Detailed Description

Generic UART interface for BSPACM.

Homepage

http://github.com/pabigot/bspacm

Copyright

Copyright 2014, Peter A. Bigot. Licensed under BSD-3-Clause

Macro Definition Documentation

#define BSPACM_PERIPH_UART_FLAG_ONLCR   0x01

If set, iBSPACMperiphUARTwrite() will translate any newline (ASCII LF, hex 0x0a) in the output buffer output into a synthesized sequence CR LF (0x0d 0x0a).

Typedef Documentation

typedef enum eBSPACMperiphUARTfifoState eBSPACMperiphUARTfifoState

Bits set in the return code of iBSPACMperiphUARTfifoState() to indicate where there is unflushed material.

typedef sBSPACMperiphUARTstate* hBSPACMperiphUART

Typedef for API that references UARTs as handles where the fact that there's state should not be relevant.

typedef struct sBSPACMperiphUARTconfiguration sBSPACMperiphUARTconfiguration

Collected configuration information used to enable a UART.

Note

At the moment, configuration options are sparse.

typedef struct sBSPACMperiphUARToperations sBSPACMperiphUARToperations

The set of operations supported by UARTs.

The underlying implementation is specific to a vendor peripheral capable of acting like a UART.

Note

The contents of this structure are not intended to be public API.

typedef struct sBSPACMperiphUARTstate sBSPACMperiphUARTstate

State associated with a UART device.

An instance of this structure is uniquely associated with each UART peripheral that is supported by an application.

Enumeration Type Documentation

enum eBSPACMperiphUARTfifoState

Bits set in the return code of iBSPACMperiphUARTfifoState() to indicate where there is unflushed material.

Enumerator
eBSPACMperiphUARTfifoState_HWRX	Indicates there is material waiting to be read from the hardware receive buffer. Resolving this requires that interrupts be enabled to allow the data to transfer into the software FIFO or some other location.
eBSPACMperiphUARTfifoState_HWTX	Indicates there is material waiting to be written in the hardware transmit buffer. This includes material that is still in a shift register. The bit clears only when the transmission is fully complete to the point where the UART can be shut down without loss of data. Resolving this requires only waiting for the hardware to complete transmission.
eBSPACMperiphUARTfifoState_HW	Indicates there is material waiting in a hardware FIFO.
eBSPACMperiphUARTfifoState_SWRX	Indicates there is material waiting to be read from the software receive FIFO. Resolving this requires that the user application read the data.
eBSPACMperiphUARTfifoState_SWTX	Indicates there is material waiting to be written in the software transmit FIFO. Resolving this requires that interrupts be enabled so the queue can drain.
eBSPACMperiphUARTfifoState_DRTX	Indicates that there is material waiting to be written that is cached in the driver state. Resolving this requires re-invoking iBSPACMperiphUARTwrite() to flush the state machine. Note This bit is set only by iBSPACMperiphUARTfifoState(), not by the underlying device function.
eBSPACMperiphUARTfifoState_TX	Indicates there is material waiting to be written in hardware, software, or driver transmit queues.
eBSPACMperiphUARTfifoState_RX	Indicates there is material waiting to be read in hardware or software receive queues.

Function Documentation

static BSPACM_CORE_INLINE hBSPACMperiphUART hBSPACMperiphUARTconfigure ( hBSPACMperiphUART  usp, const sBSPACMperiphUARTconfiguration *  cfgp  )

static

Configure (or deconfigure) a UART.

Parameters

usp	the UART peripheral state
cfgp	if non-null, a pointer to information used to configure the peripheral. If null, a sign that the peripheral is no longer being used and should be shut down/deconfigured.

Returns

usp on successful (de-)configuration, otherwise a null pointer value to indicate an error.

static BSPACM_CORE_INLINE int iBSPACMperiphUARTfifoState ( hBSPACMperiphUART  usp )

static

Determine whether there is anything pending in the device: material that has been received but not consumed by the application, or material that has been submitted for transmission but has not yet gone out over the channel.

Parameters

usp	the UART abstraction

Returns

a combination of bits defined in eBSPACMperiphUARTfifoState. A value of zero indicates that no material is pending. A negative value indicates an error, e.g. that the UART is unconfigured.

int iBSPACMperiphUARTflush	(	hBSPACMperiphUART	usp,
		int	fifo_mask
	)

Block until the result of iBSPACMperiphUARTfifoState() indicates an error or no pending fifo_mask data

For example, the following ensures all pending console data has been transmitted prior to entering a sleep mode that disables peripheral clocks:

(void)iBSPACMperiphUARTflush(hBSPACMdefaultUART, eBSPACMperiphUARTfifoState_TX);

Note

If data is pending, this function will sleep for interrupts and enable them to process the data. If entered with interrupts disabled, interrupts will remain disabled between the last fifo check and returning, guaranteeing that fifo state will be as reflected in the return value.

Parameters

usp	the UART abstraction
fifo_mask	bits from eBSPACMperiphUARTfifoState that must be clear in the return value of iBSPACMperiphUARTfifoState() for a successful return

Returns

the value of the last call to iBSPACMperiphUARTfifoState(), which may be a negative error indicator.

int iBSPACMperiphUARTread	(	hBSPACMperiphUART	usp,
		void *	buf,
		size_t	count
	)

Read data from a UART.

This call attempts to read up to count bytes of data into the buffer at buf.

Parameters

usp	the UART peripheral state. The peripheral must be configured and active.
buf	location into which data should be stored
count	the number of bytes that should be read

Returns

the number of bytes actually read (which may be zero depending on receiver state), or a negative error code.

int iBSPACMperiphUARTwrite	(	hBSPACMperiphUART	usp,
		const void *	buf,
		size_t	count
	)

Write data to a UART.

The contract for this function is the following: Zero or more bytes from buf will be transmitted or queued for automatic transmission by interrupt. The function will not block and will not enable interrupts, even if that would be necessary to transmit data.

Parameters

usp	the UART peripheral state
buf	location from which transmitted data is read
count	the number of bytes that should be written

Returns

the number of bytes actually written (which may be zero depending on UART configuration flags and transmitter state), or a negative error code.

Variable Documentation

const hBSPACMperiphUART hBSPACMdefaultUART

The default UART device for the application/board.

Weakly Defined

A weak definition with a null pointer value is provided in the library. Generally a board-specific default should be defined in periph_config.c, when BSPACM_CONFIG_ENABLE_UART is true.