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.

2 files changed, 157 insertions, 10 deletions

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
@@ -37,6 +37,15 @@ extern "C" {
  */
 
 /**
+ * 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 <chrisj@rtems.org>
+ *  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 <stdbool.h>
+#include <stddef.h>
+#include <stdio.h>
+
+#include <rtems/bspIo.h>
+
+#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