Kernel Character I/O Support

The kernel character input/output support is an extension of the I/O Manager to output characters to the kernel character output device and receive characters from the kernel character input device using a polled and non-blocking implementation. More...

Files
file	bspIo.h
	This header file provides the kernel character input/output support API.
file	getchark.c
	This source file contains the implementation of getchark().
file	printk.c
	This source file contains the implementation of printk().
file	printk_plugin.c
	This source file contains the implementation of rtems_printk_printer() and rtems_print_printer_printk().
file	putk.c
	This source file contains the implementation of putk().
file	rtems_put_char.c
	This source file contains the implementation of rtems_put_char().
file	rtems_putc.c
	This source file contains the implementation of rtems_putc().
file	vprintk.c
	This source file contains the implementation of vprintk().

Typedefs
typedef void(*	BSP_output_char_function_type) (char)
	Polled character output functions shall have this type.
typedef int(*	BSP_polling_getchar_function_type) (void)
	Polled character input functions shall have this type.

Functions
void	rtems_putc (char c)
	Outputs the character to the kernel character output device.
void	rtems_put_char (int c, void *unused)
	Puts the character using rtems_putc()
int	putk (const char *s)
	Outputs the characters of the string and a newline character to the kernel character output device.
	RTEMS_PRINTFLIKE (1, 2) int printk(const char *fmt
	Outputs the characters defined by the format string and the arguments to the kernel character output device.
int	vprintk (const char *fmt, va_list ap)
	Outputs the characters defined by the format string and the variable argument list to the kernel character output device.
int	rtems_printk_printer (void *unused, const char *fmt, va_list ap)
	Outputs the characters defined by the format string and the variable argument list to the kernel character output device.
int	getchark (void)
	Tries to dequeue a character from the kernel character input device.

Variables
BSP_output_char_function_type	BSP_output_char
	This function pointer references the kernel character output implementation.
BSP_polling_getchar_function_type	BSP_poll_char
	This function pointer may reference the kernel character input implementation.

Detailed Description

The kernel character input/output support is an extension of the I/O Manager to output characters to the kernel character output device and receive characters from the kernel character input device using a polled and non-blocking implementation.

The directives may be used to print debug and test information. The kernel character input/output support should work even if no Console Driver is configured, see CONFIGURE_APPLICATION_NEEDS_CONSOLE_DRIVER. The kernel character input and output device is provided by the BSP. Applications may change the device.

Function Documentation

getchark()

int getchark

(

void

)

Tries to dequeue a character from the kernel character input device.

The directive tries to dequeue a character from the kernel character input device using the polled character input implementation referenced by BSP_poll_char if it is available.

Return values

-1	The BSP_poll_char pointer was equal to NULL.
-1	There was no character enqueued on the kernel character input device.

Returns

Returns the character least recently enqueued on the kernel character input device as an unsigned character value.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

putk()

int putk

(

const char *

s

)

Outputs the characters of the string and a newline character to the kernel character output device.

Parameters

s	is the string to output.

Returns

Returns the number of characters output to the kernel character output device.

Notes

The directive may be used to print debug and test information. It uses rtems_putc() to output the characters. This directive performs a character translation from NL to CR followed by NR.

If the kernel character output device is concurrently accessed, then interleaved output may occur.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

Kernel putk (e.g. puts) function requiring minimal infrastrure.

RTEMS_PRINTFLIKE()

RTEMS_PRINTFLIKE	(	1	,
		2
	)		const

Outputs the characters defined by the format string and the arguments to the kernel character output device.

Parameters

fmt	is a printf()-style format string.
...	is a list of optional parameters required by the format string.

Returns

Returns the number of characters output to the kernel character output device.

Notes

The directive may be used to print debug and test information. It uses rtems_putc() to output the characters. This directive performs a character translation from NL to CR followed by NR.

If the kernel character output device is concurrently accessed, then interleaved output may occur.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.
• Formatting of floating point numbers is not supported.

rtems_printk_printer()

int rtems_printk_printer	(	void *	unused,
		const char *	fmt,
		va_list	ap
	)

Outputs the characters defined by the format string and the variable argument list to the kernel character output device.

Parameters

unused	is an unused argument.
fmt	is a printf()-style format string.
ap	is the variable argument list required by the format string.

Returns

Returns the number of characters output to the kernel character output device.

Notes

The directive may be used to print debug and test information. It uses rtems_putc() to output the characters. This directive performs a character translation from NL to CR followed by NR.

If the kernel character output device is concurrently accessed, then interleaved output may occur.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.
• Formatting of floating point numbers is not supported.

rtems_put_char()

void rtems_put_char	(	int	c,
		void *	unused
	)

Puts the character using rtems_putc()

Parameters

c	is the character to output.
unused	is an unused argument.

Notes

The directive is provided to support the RTEMS Testing Framework.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

rtems_putc()

void rtems_putc

(

char

c

)

Outputs the character to the kernel character output device.

Parameters

c	is the character to output.

The directive outputs the character specified by c to the kernel character output device using the polled character output implementation provided by BSP_output_char. The directive performs a character translation from NL to CR followed by NR.

If the kernel character output device is concurrently accessed, then interleaved output may occur.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.

vprintk()

int vprintk	(	const char *	fmt,
		va_list	ap
	)

Outputs the characters defined by the format string and the variable argument list to the kernel character output device.

Parameters

fmt	is a printf()-style format string.
ap	is the variable argument list required by the format string.

Returns

Returns the number of characters output to the kernel character output device.

Notes

The directive may be used to print debug and test information. It uses rtems_putc() to output the characters. This directive performs a character translation from NL to CR followed by NR.

If the kernel character output device is concurrently accessed, then interleaved output may occur.

Constraints

The following constraints apply to this directive:

• The directive may be called from within any runtime context.
• The directive will not cause the calling task to be preempted.
• Formatting of floating point numbers is not supported.

Variable Documentation

BSP_output_char

BSP_output_char_function_type BSP_output_char

extern

This function pointer references the kernel character output implementation.

This function pointer shall never be NULL. It shall be provided by the BSP and statically initialized. The referenced function shall output exactly the character specified by the parameter. In particular, it shall not perform character translations, for example NL to CR followed by NR. The function shall not block.

BSP_poll_char

BSP_polling_getchar_function_type BSP_poll_char

extern

This function pointer may reference the kernel character input implementation.

This function pointer may be NULL. It may reference a function provided by the BSP. Referenced functions shall dequeue the least recently received character from the device and return it as an unsigned character. If no character is enqueued on the device, then the function shall immediately return the value minus one.