From 24d0ee57a4d95f99be6e7e60bd162a30daf0638d Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Fri, 20 May 2016 18:39:50 +1000 Subject: cpukit, testsuite: Add rtems_printf and rtems_printer support. This change adds rtems_printf and related functions and wraps the RTEMS print plugin support into a user API. All references to the plugin are removed and replaced with the rtems_printer interface. Printk and related functions are made to return a valid number of characters formatted and output. The function attribute to check printf functions has been added to rtems_printf and printk. No changes to remove warrnings are part of this patch set. The testsuite has been moved over to the rtems_printer. The testsuite has a mix of rtems_printer access and direct print control via the tmacros.h header file. The support for begink/endk has been removed as it served no purpose and only confused the code base. The testsuite has not been refactored to use rtems_printf. This is future work. --- cpukit/include/rtems/bspIo.h | 33 +++++++---- cpukit/include/rtems/print.h | 134 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 10 deletions(-) create mode 100644 cpukit/include/rtems/print.h (limited to 'cpukit/include') diff --git a/cpukit/include/rtems/bspIo.h b/cpukit/include/rtems/bspIo.h index dde8d942e8..403b857e43 100644 --- a/cpukit/include/rtems/bspIo.h +++ b/cpukit/include/rtems/bspIo.h @@ -36,6 +36,15 @@ extern "C" { * - BSP_poll_char */ +/** + * Print format function attribute for warning checks. Can be defined if + * checking needs to be disabled. + */ +#ifndef RTEMS_PRINTF_ATTRIBUTE +#define RTEMS_PRINTF_ATTRIBUTE(_format_pos, _ap_pos) \ + __attribute__((format(__printf__, _format_pos, _ap_pos))) +#endif + /** * This type defines the prototype for the BSP provided method to * print a single character. It is assumed to be polled. @@ -84,8 +93,10 @@ extern int getchark(void); * * @param[in] fmt is a printf()-style format string * @param[in] ap is a va_list pointer to arguments + * + * @return The number of characters output. */ -extern void vprintk(const char *fmt, va_list ap); +extern int vprintk(const char *fmt, va_list ap); /** * @brief Kernel Print @@ -93,8 +104,10 @@ extern void vprintk(const char *fmt, va_list ap); * This method allows the user to perform a debug printk(). * * @param[in] fmt is a printf()-style format string + * + * @return The number of characters output. */ -extern void printk(const char *fmt, ...); +extern int printk(const char *fmt, ...) RTEMS_PRINTF_ATTRIBUTE(1, 2); /** * @brief Kernel Put String @@ -102,8 +115,10 @@ extern void printk(const char *fmt, ...); * This method allows the user to perform a debug puts(). * * @param[in] s is the string to print + * + * @return The number of characters output. */ -extern void putk(const char *s); +extern int putk(const char *s); /** * @brief Kernel Put Character @@ -118,15 +133,13 @@ extern void rtems_putc(char c); * Type definition for function which can be plugged in to * certain reporting routines to redirect the output. * - * Methods following this prototype may be passed into RTEMS reporting - * functions that allow their output to be redirected. In particular, - * the cpu usage, period usage, and stack usage reporting - * functions use this. + * Use the RTEMS Print interface to call these functions. Do not + * directly use them. * * If the user provides their own "printf plugin", then they may * redirect those reports as they see fit. */ -typedef int (*rtems_printk_plugin_t)(void *, const char *format, ...); +typedef int (*rtems_print_plugin_t)(void *, const char *format, va_list ap); /** * @brief Reporting Methods printk() Plugin @@ -136,7 +149,7 @@ typedef int (*rtems_printk_plugin_t)(void *, const char *format, ...); * * @return The number of characters printed. */ -extern int printk_plugin(void *context, const char *fmt, ...); +extern int printk_plugin(void *context, const char *fmt, va_list ap); /** * @brief Reporting Methods printf() Plugin @@ -149,7 +162,7 @@ extern int printk_plugin(void *context, const char *fmt, ...); * * @return The number of characters printed. */ -extern int rtems_printf_plugin(void *context, const char *fmt, ...); +extern int rtems_printf_plugin(void *context, const char *fmt, va_list ap); /**@}*/ diff --git a/cpukit/include/rtems/print.h b/cpukit/include/rtems/print.h new file mode 100644 index 0000000000..5268e8c744 --- /dev/null +++ b/cpukit/include/rtems/print.h @@ -0,0 +1,134 @@ +/** + * @file rtems/print.h + * + * @brief User print interface to the bspIO print plug in. + * + * This include file defines the user interface to kernel print methods. + */ + +/* + * Copyright (c) 2016 Chris Johns + * All rights reserved. + * + * The license and distribution terms for this file may be + * found in the file LICENSE in this distribution or at + * http://www.rtems.org/license/LICENSE. + */ + +#ifndef _RTEMS_PRINT_H +#define _RTEMS_PRINT_H + +#include +#include +#include + +#include + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * @defgroup RTEMS Print Support + * + * This module contains all methods and support related to providing the user + * with an interface to the kernel level print support. + */ + +/** + * Type definition for the printer structure used to access the kernel print + * support. + */ +typedef struct { + void *context; + rtems_print_plugin_t printer; +}rtems_printer; + +/** + * @brief check if the printer is valid. + * + * @param[in] printer Pointer to the printer structure. + * + * @return true The printer is valid else false is returned. + */ +static inline bool rtems_print_printer_valid(const rtems_printer *printer) +{ + return printer != NULL && printer->printer != NULL; +} + +/** + * @brief Print to the kernel plugin handler. This has to be a macro because + * there is no vprint version of the plug in handlers. + * + * @param[in] printer Pointer to the printer structure. + * @param[in] fmt Print format string. + * @param[in] ... Print variable argument list. + * + * @return int Number of characters printed. + */ +extern int rtems_printf(const rtems_printer *printer, + const char *format, + ...) RTEMS_PRINTF_ATTRIBUTE(2, 3); + +/** + * @brief Print to the kernel plugin handler. This has to be a macro because + * there is no vprint version of the plug in handlers. + * + * @param[in] printer Pointer to the printer structure. + * @param[in] fmt Print format string. + * @param[in] ap Print variable argument list pointer. + * + * @return int Number of characters printed. + */ +extern int rtems_vprintf(const rtems_printer *printer, + const char *format, + va_list ap); + +/** + * @brief Intiialise the rtems_printer struct to empty. + * + * An empty printer prints nothing. You can use this to implement an enable and + * disable type print implementation. + * + * @param[in] printer Pointer to the printer structure. + */ +static inline void rtems_print_printer_empty(rtems_printer *printer) +{ + printer->context = NULL; + printer->printer = NULL; +} + +/** + * @brief Intiialise the rtems_printer struct to printk + * + * The printer will output to the kernel printk support. + * + * @param[in] printer Pointer to the printer structure. + */ +void rtems_print_printer_printk(rtems_printer *printer); + +/** + * @brief Intiialise the rtems_printer struct to printf + * + * The printer will output to the libc printf support. + * + * @param[in] printer Pointer to the printer structure. + */ +extern void rtems_print_printer_printf(rtems_printer *printer); + +/** + * @brief Intiialise the rtems_printer struct to a fprintf device. + * + * The printer will output to the libc fprintf file provided. + * + * @param[in] printer Pointer to the printer structure. + */ +extern void rtems_print_printer_fprintf(rtems_printer *printer, FILE *file); + +/**@}*/ + +#ifdef __cplusplus +} +#endif + +#endif -- cgit v1.2.3