BSP430  20141115
Board Support Package for MSP430 microcontrollers
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Macros | Typedefs | Functions
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

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:

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
formatA 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
ccharacter 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
cpfirst of a series of characters to be emitted to the console
lennumber 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
nthe integer value to be formatted
radixthe 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
nthe integer value to be formatted
radixthe 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
sa 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
sa 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
nthe integer value to be formatted
radixthe 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
nthe integer value to be formatted
radixthe 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
enablepnonzero 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_availablethe 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
dppointer to start of memory region
lennumber of octets to display
basebase 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
dppointer to start of memory region
lennumber 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
cbthe 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
formatA printf(3) format string
apA 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.