console.h File Reference

A generic console output capability. More...

#include <bsp430/serial.h>
#include <stdarg.h>

Go to the source code of this file.

Macros
#define	configBSP430_CONSOLE   0
#define	BSP430_CONSOLE   include <bsp430/platform.h>
#define	BSP430_CONSOLE_SERIAL_PERIPH_CPPID   include <bsp430/platform.h>
#define	BSP430_CONSOLE_SERIAL_PERIPH_HANDLE   include <bsp430/platform.h>
#define	BSP430_CONSOLE_BAUD_RATE   9600
#define	BSP430_CONSOLE_RX_BUFFER_SIZE   0
#define	BSP430_CONSOLE_TX_BUFFER_SIZE   0
#define	BSP430_CONSOLE_USE_EMBTEXTF   0
#define	configBSP430_CONSOLE_PROVIDES_PUTCHAR   1
#define	configBSP430_CONSOLE_PROVIDES_STDIO   (BSP430_CORE_TOOLCHAIN_LIBC_NEWLIB - 0)
#define	configBSP430_CONSOLE_USE_ONLCR   1

Typedefs
typedef int(*	iBSP430consoleRxCallback_ni) (void)

Functions
int	cgetchar (void)
int	cpeekchar (void)
void	vBSP430consoleSetRxCallback_ni (iBSP430consoleRxCallback_ni cb)
int	cputs (const char *s)
int	cputchar (int c)
int	cputtext (const char *s)
int	cputchars (const char *cp, size_t len)
int	cprintf (const char *format,...)
int	vcprintf (const char *format, va_list ap)
int	cputi (int n, int radix)
int	cputu (unsigned int n, int radix)
int	cputl (long n, int radix)
int	cputul (unsigned long n, int radix)
int	iBSP430consoleInitialize (void)
int	iBSP430consoleDeconfigure (void)
hBSP430halSERIAL	hBSP430console (void)
int	iBSP430consoleTransmitUseInterrupts_ni (int enablep)
int	iBSP430consoleWaitForTxSpace_ni (int want_available)
int	iBSP430consoleFlush (void)
void	vBSP430consoleDisplayMemory (const uint8_t *dp, size_t len, unsigned long base)
void	vBSP430consoleDisplayOctets (const uint8_t *dp, size_t len)

Detailed Description

A generic console output capability.

This module collects various functions that format and generate human-readable output on a serial console, or support reading data from a serial console.

Interrupts and Console Operations

In the original design of BSP430 console output was performed with interrupts disabled under the belief that the potential of interleaved output between different tasks and interrupts was undesired. In practice, interrupt handlers only invoke console output when debugging, and this can be handled other ways. The impact of extended periods with interrupts disabled was unacceptable in applications that require prompt response to interrupts, such as radio packet reception and acknowledgement transmission.

Consequently all console output and input are now non-blocking and disable interrupts only where this is necessary to prevent corruption when both interrupt handlers and user code manipulate the same data structures.

The script ${BSP430_ROOT}/maintainer/xni_console.sed may be used to convert older sources to the new API where _ni suffixes are no longer present.

Basic Capabilities

Core routines natively supported are cputchar(), cputs(), and cgetchar(). Extensions include cputchars(), cputtext(), and cpeekchar().

With library support through BSP430_CONSOLE_USE_EMBTEXTF or msp430-libc in the MSPGCC toolchain full support for formatted output via cprintf() and vcprintf() is possible.

In addition optimized routines are provided to convert integers in standard bases with minimal space overhead (cputi(), cputu(), cputl(), cputul()). The integer routines are more cumbersome but necessary when the platform cannot accommodate the stack overhead of cprintf() (on the order of 100 bytes if 64-bit integer support is included).

Compile-time options BSP430_CONSOLE_RX_BUFFER_SIZE and BSP430_CONSOLE_TX_BUFFER_SIZE enable interrupt-driven input and output, allowing the application to make progress while output is produced and input buffered using interrupts.

Homepage

http://github.com/pabigot/bsp430

Copyright

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

Macro Definition Documentation

#define BSP430_CONSOLE   include <bsp430/platform.h>

Defined to a true value if BSP430_CONSOLE_SERIAL_PERIPH_CPPID has been provided, making the console infrastructure available.

Dependency:

configBSP430_CONSOLE

Platform-Based Value:

Undefined here; include <bsp430/platform.h> to obtain the correct value of this macro.

#define BSP430_CONSOLE_BAUD_RATE   9600

The baud rate that should be used for the console. This may be overridden in a platform header or by an application configuration.

Defaulted:

The value here is superseded by previously encountered definitions.

#define BSP430_CONSOLE_RX_BUFFER_SIZE   0

Define this to the size of a buffer to be used for interrupt-driven console input. The value must not exceed 254, and buffer management is most efficient if the value is a power of 2.

If this has a value of zero, character input is not interrupt driven. cgetchar() will return the most recently received character, if any, and cpeekchar() will not be available.

Defaulted:

The value here is superseded by previously encountered definitions.

#define BSP430_CONSOLE_SERIAL_PERIPH_CPPID   include <bsp430/platform.h>

Define to the preprocessor-compatible identifier for the peripheral that should be used by platform-agnostic programs to create the console, for example BSP430_PERIPH_CPPID_USCI5_A0.

The define must appear in the BSP430 Configuration subsystem so that functional resource requests are correctly propagated to the underlying resource instances. A default is provided based on the platform or available serial peripherals.

Dependency:

BSP430_CONSOLE

Platform-Based Value:

Undefined here; include <bsp430/platform.h> to obtain the correct value of this macro.

Affects:

BSP430_CONSOLE_SERIAL_PERIPH_HANDLE

#define BSP430_CONSOLE_SERIAL_PERIPH_HANDLE   include <bsp430/platform.h>

The peripheral handle that should be used by platform-agnostic programs to create the console. This derives directly from BSP430_CONSOLE_SERIAL_PERIPH_CPPID, but is a serial peripheral handle suitable for use in code.

The corresponding HAL and ISR features are automatically enabled for this peripheral.

Defaulted:

The value here is superseded by previously encountered definitions.

Platform-Based Value:

Undefined here; include <bsp430/platform.h> to obtain the correct value of this macro.

Dependency:

BSP430_CONSOLE_SERIAL_PERIPH_CPPID

#define BSP430_CONSOLE_TX_BUFFER_SIZE   0

Define this to the size of a buffer to be used for interrupt-driven console output. The value must not exceed 254, and buffer management is most efficient if the value is a power of 2.

If this has a value of zero, character output is not interrupt driven. cputchar() will block until the UART is ready to accept a new character.

Warning

By enabling interrupt-driven output the console output routines are no longer safe to call from within interrupt handlers. See Interrupts and Console Operations.

Defaulted:

The value here is superseded by previously encountered definitions.

#define BSP430_CONSOLE_USE_EMBTEXTF   0

Define to indicate build infrastructure support for embtextf

This flag should be defined to a true value by the build infrastructure when the external embtextf (Embedded System Text Formatting) library is to supply enhanced formatting functions. This enables:

• cprintf(), vcprintf()
• cputi(), cputu(), cputl(), cputul()

Note

When using the MSPGCC toolchain this capability is available implicitly through msp430-libc. BSP430_CONSOLE_USE_EMBTEXTF should be defined only when the external version of these functions is to be used instead.

#define configBSP430_CONSOLE   0

Define to a true value to request that a serial handle be identified to serve as a system console.

See BSP430_CONSOLE_SERIAL_PERIPH_CPPID for information about which serial peripheral will be used for this capability.

C Preprocessor Only:

This macro may have a value that restricts its use to C preprocessor conditional directives.

Affects:

BSP430_CONSOLE

Defaulted:

The value here is superseded by previously encountered definitions.

#define configBSP430_CONSOLE_PROVIDES_PUTCHAR   1

If defined to a true value, the individual character display function used internally to the console module will be made public with the name putchar so that it will be used by printf(3) when the C library depends on an external putchar.

The "atomic" behavior promised by cprintf is not guaranteed for printf, puts, or any other library function that might invoke this putchar implementation.

C Preprocessor Only:

This macro may have a value that restricts its use to C preprocessor conditional directives.

Defaulted:

The value here is superseded by previously encountered definitions.

#define configBSP430_CONSOLE_PROVIDES_STDIO   (BSP430_CORE_TOOLCHAIN_LIBC_NEWLIB - 0)

If defined to a true value, the console module will provide strong definitions of read() and write() that override the non-functional weak newlib nosys defaults to allow stdout and stdin to operate on the console UART.

C Preprocessor Only:

This macro may have a value that restricts its use to C preprocessor conditional directives.

Defaulted:

The value here is superseded by previously encountered definitions.

Dependency:

BSP430_CORE_TOOLCHAIN_LIBC_NEWLIB

#define configBSP430_CONSOLE_USE_ONLCR   1

If defined to true, the console display routines will always emit a carriage return before a newline. This provides compatibility with standard terminal programs like minicom.

C Preprocessor Only:

This macro may have a value that restricts its use to C preprocessor conditional directives.

Defaulted:

The value here is superseded by previously encountered definitions.

Typedef Documentation

typedef int(* iBSP430consoleRxCallback_ni) (void)

Callback for alarm events.

This function will be invoked by the console infrastructure in an interrupt context after received characters have been buffered.

Returns

As with iBSP430halISRCallbackVoid_ni().

Function Documentation

int cgetchar

(

void

)

Return a character that was input to the console.

Returns

the next character that was input to the console, or -1 if no characters are available.

Note

This function is available even if BSP430_CONSOLE_RX_BUFFER_SIZE is zero.

Examples:

bootstrap/console/main.c, and utility/cli/main.c.

int cpeekchar

(

void

)

Peek at the next character input to the console

Use this to determine whether there's any data ready to be read, without actually consuming it yet.

Returns

the value that would be returned by invoking cgetchar(), but without consuming any pending input.

Warning

This function is not available if BSP430_CONSOLE_RX_BUFFER_SIZE is zero.

Dependency:

BSP430_CONSOLE_RX_BUFFER_SIZE

int cprintf	(	const char *	format,
			...
	)

Like printf(3), but to the console UART.

Interrupts are disabled during the duration of the invocation. On exit, interruptibility state is restored (if entered with interrupts disabled, they remain disabled).

If xBSP430consoleInitialize() has not assigned a UART device, the call is a no-op.

Parameters

format

A printf(3) format string

Returns

Number of characters printed if the console is enabled; 0 if it is disabled; a negative error code if an error is encountered

Dependency:

BSP430_CONSOLE, BSP430_CONSOLE_USE_EMBTEXTF, libc

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Examples:

bootstrap/applpm/main.c, bootstrap/button/main.c, bootstrap/clocks/main.c, periph/timer/alarm/main.c, platform/exp430f5529/fatfs/main.c, rf/cc110x/main.c, rf/cc3000/cli/main.c, sensors/ds18b20/main.c, sensors/hh10d/main.c, sensors/tmp102/main.c, sensors/venus6pps/main.c, utility/cli/main.c, utility/m25p/main.c, and utility/u8glib/main.c.

int cputchar

(

int

c

)

Like putchar(3) to the console UART

Parameters

c	character to be output

Returns

the character that was output

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Examples:

bootstrap/applpm/main.c, bootstrap/clocks/main.c, bootstrap/console/main.c, periph/timer/alarm/main.c, platform/exp430f5529/fatfs/main.c, rf/cc3000/cli/main.c, utility/cli/main.c, and utility/m25p/main.c.

int cputchars	(	const char *	cp,
		size_t	len
	)

Like puts(3) to the console UART without trailing newline and with explicit length instead of a terminating NUL.

Note

Any errors returned by the underlying UART implementation while writing are ignored.

Parameters

cp	first of a series of characters to be emitted to the console
len	number of characters to emit

Returns

the number of characters written

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

int cputi	(	int	n,
		int	radix
	)

Format an int using itoa and emit it to the console.

Parameters

n	the integer value to be formatted
radix	the radix to use when formatting

Warning

The implementation assumes that radix is at least 10. Passing a smaller radix will likely result in stack corruption.

Returns

the number of characters emitted

Dependency:

BSP430_CONSOLE, BSP430_CONSOLE_USE_EMBTEXTF

Examples:

bootstrap/clocks/main.c.

int cputl	(	long	n,
		int	radix
	)

Format an int using ltoa and emit it to the console.

Parameters

n	the integer value to be formatted
radix	the radix to use when formatting

Warning

The implementation assumes that the radix is at least 10. Passing a smaller radix will likely result in stack corruption.

Returns

the number of characters emitted

Dependency:

BSP430_CONSOLE, BSP430_CONSOLE_USE_EMBTEXTF

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Examples:

bootstrap/clocks/main.c.

int cputs

(

const char *

s

)

Like puts(3) to the console UART

As with cprintf, interrupts are disabled for the duration of the invocation (except see Interrupts and Console Operations).

Note

Any errors returned by the underlying UART implementation while writing are ignored.

Parameters

s	a string to be emitted to the console

Returns

the number of characters written, including the newline

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Examples:

bootstrap/applpm/main.c, platform/exp430f5529/fatfs/main.c, and utility/cli/main.c.

int cputtext

(

const char *

s

)

Like puts(3) to the console UART without trailing newline

Note

Any errors returned by the underlying UART implementation while writing are ignored.

Parameters

s	a NUL-terminated string to be emitted to the console

Returns

the number of characters written

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Examples:

bootstrap/applpm/main.c, bootstrap/clocks/main.c, bootstrap/console/main.c, platform/exp430f5529/fatfs/main.c, rf/cc3000/cli/main.c, and utility/cli/main.c.

int cputu	(	unsigned int	n,
		int	radix
	)

Format an int using utoa and emit it to the console.

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Parameters

n	the integer value to be formatted
radix	the radix to use when formatting

Warning

The implementation assumes that the radix is at least 10. Passing a smaller radix will likely result in stack corruption.

Returns

the number of characters emitted

Dependency:

BSP430_CONSOLE, BSP430_CONSOLE_USE_EMBTEXTF

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Examples:

bootstrap/clocks/main.c, and bootstrap/console/main.c.

int cputul	(	unsigned long	n,
		int	radix
	)

Format an int using itoa and emit it to the console.

Parameters

n	the integer value to be formatted
radix	the radix to use when formatting

Warning

The implementation assumes that the radix is at least 10. Passing a smaller radix will likely result in stack corruption.

Returns

the number of characters emitted

Dependency:

BSP430_CONSOLE, BSP430_CONSOLE_USE_EMBTEXTF

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

Examples:

bootstrap/clocks/main.c, and bootstrap/console/main.c.

hBSP430halSERIAL hBSP430console

(

void

)

Return a reference to the console device.

Returns

the serial HAL instance used for console interaction. A null pointer is returned if the console has not been successfully initialized.

Examples:

bootstrap/applpm/main.c, and bootstrap/console/main.c.

int iBSP430consoleDeconfigure

(

void

)

Deconfigure the console serial HAL instance

This routine closes the HAL serial instance, decoupling it from any callbacks and turning it off. The instance may be re-enabled by re-invoking iBSP430consoleInitialize().

You might need this function if you change the rate of the clock on which the console baud generator depends.

Returns

0 if the deconfiguration was successful, -1 if an error occurred.

int iBSP430consoleFlush

(

void

)

Flush any pending data in the console transmit buffer.

This is simply a wrapper around calls to iBSP430consoleWaitForTxSpace_ni() and vBSP430serialFlush_ni(), with interrupts disabled if required. On return, all queued output will have been transmitted.

If the console does not use interrupt driven transmission, this function will simply spin until the last character has been transmitted by the UART.

Returns

0 if the console was flushed without suspending; a positive number of the application had to suspend to permit interrupt-driven transmission to complete.

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

int iBSP430consoleInitialize

(

void

)

Initialize and return the console serial HAL instance.

This configures the platform-specified serial HAL instance identified by BSP430_CONSOLE_SERIAL_PERIPH_HANDLE as specified by BSP430_CONSOLE_BAUD_RATE. If BSP430_PLATFORM_SPIN_FOR_JUMPER is true, it will invoke vBSP430platformSpinForJumper_ni(). Once the console is configured and any required delays completed it will return, allowing use of cprintf() and related functions.

If this function is invoked multiple times without an intervening call to iBSP430consoleDeconfigure(), the existing configuration is unchanged.

Note

If BSP430_SERIAL_ENABLE_RESOURCE is non-zero the resource associated with the console peripheral will be claimed by the console infrastructure and held until iBSP430consoleDeconfigure() is invoked. Failure to obtain the resource will result in an error during initialization.

Returns

0 if the console was successfully initialized, -1 if an error occurred.

Examples:

bootstrap/applpm/main.c, bootstrap/button/main.c, bootstrap/clocks/main.c, bootstrap/console/main.c, periph/timer/alarm/main.c, platform/exp430f5529/fatfs/main.c, rf/cc110x/main.c, rf/cc3000/cli/main.c, sensors/ds18b20/main.c, sensors/hh10d/main.c, sensors/tmp102/main.c, sensors/venus6pps/main.c, utility/cli/main.c, utility/m25p/main.c, and utility/u8glib/main.c.

int iBSP430consoleTransmitUseInterrupts_ni

(

int

enablep

)

Control whether console output uses interrupt-driven transmission.

When BSP430_CONSOLE_TX_BUFFER_SIZE is configured to a positive value, it is normally improper to use the console output routines from within interrupt handlers and in other cases where interrupts are disabled, since the routines might enable interrupts to allow the transmission buffer to drain. See Interrupts and Console Operations. This routine can be used at runtime to disable the interrupt-based transmission, thus allowing use of direct, busy-waiting console output.

Note

You probably want to invoke vBSP430consoleFlush() prior to disabling interrupt-driven transmission. If you don't, whatever was unflushed in the buffer will be displayed once the transmission is re-enabled.

Parameters

enablep

nonzero if interrupt-drive transmission is to be used; zero to disable the transmit interrupt on the console UART and use direct UART writes instead.

Returns

0 if the configuration was accepted. -1 if enable is nonzero but the application was not configured with interrupt-driven transmission enabled.

int iBSP430consoleWaitForTxSpace_ni

(

int

want_available

)

Potentially block until space is available in console transmit buffer.

This function causes the caller to block until the interrupt-driven console transmit buffer has drained to the point where at least want_available bytes are available.

If the console does not use interrupt-driven transmission, this function immediately returns zero.

Note

The return value of this function indicates whether it was necessary to enable interrupts in order to achieve the desired available space. In such a case an application may need to re-check other conditions to ensure there is no pending work prior to entering low power mode.

Parameters

want_available

the number of bytes that are requested. A negative number requires that the transmit buffer be empty (i.e., flushed).

Returns

• Zero if want_available bytes were available on entry without suspending;
• A positive number if the bytes are now available, but the function had to suspend (enabling interrupts) in order to obtain that space;
• -1 if want_available is larger than BSP430_CONSOLE_TX_BUFFER_SIZE-1, which is the maximum number of bytes that can be made available.

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.

void vBSP430consoleDisplayMemory	(	const uint8_t *	dp,
		size_t	len,
		unsigned long	base
	)

Display the contents of a block of memory.

This function displays on the console the contents of a memory region as octets and printable characters. The memory must by byte-addressable. One line is emitted for each 16-byte block: it begins with the address of the displayed data (per base), followed by up to 16 octet values, followed by the values as printable characters.

Parameters

dp	pointer to start of memory region
len	number of octets to display
base	base displayed address for first octet

Examples:

rf/cc3000/cli/main.c, and utility/m25p/main.c.

void vBSP430consoleDisplayOctets	(	const uint8_t *	dp,
		size_t	len
	)

Display a short memory region contents of a block of memory.

This function displays a sequence of octets on the console. It differs from vBSP430consoleDisplayMemory() in that there is no address information, no printable character display, and no attempt to split the output into individual lines.

Parameters

dp	pointer to start of memory region
len	number of octetst to display

void vBSP430consoleSetRxCallback_ni

(

iBSP430consoleRxCallback_ni

cb

)

Register a callback for console RX events.

If a non-null callback is registered with the console, it will be invoked after each character received on the console is stored in the receive buffer. The return value of the callback influences how the console RX interrupt handler manages LPM wakeup and other behavior; see Interrupt Callback Return Values.

If no callback is registered, the infrastructure will act as though a registered callback did nothing but return BSP430_HAL_ISR_CALLBACK_EXIT_LPM.

Note

The infrastructure will add BSP430_HAL_ISR_CALLBACK_BREAK_CHAIN to any value returned by this callback, including the value returned by a null (default) callback.

Warning

This function is not available if BSP430_CONSOLE_RX_BUFFER_SIZE is zero.

Parameters

cb	the callback to be invoked on received characters, or a null pointer to cause the application to wake from LPM when characters are received.

Dependency:

BSP430_CONSOLE_RX_BUFFER_SIZE

int vcprintf	(	const char *	format,
		va_list	ap
	)

Like vprintf(3), but to the console UART.

Parameters

format	A printf(3) format string
ap	A stdarg reference to variable arguments to a calling function.

Returns

as with cprintf().

Dependency:

BSP430_CONSOLE, BSP430_CONSOLE_USE_EMBTEXTF

Warning

This function may enable interrupts and sleep if interrupt-driven console transmission is enabled. See Interrupts and Console Operations.