mbed_retarget: Add a minimal console implementation to provide basic functionalities

The retarget code allocates an array of FileHandle* for console and file
handling (filehandles). A tiny target only needs a console (putc/getc).
There is no need for file handling.

The POSIX layer and the array of FileHandle* is not required for small
targets that only need a console ; this code is optionally compiled
out if the configuration parameter platform.stdio-minimal-console-only is
set to `"true"`.

Author: hugueskamba

platform/Stream.h

@@ -45,6 +45,7 @@ class Stream : public FileLike, private NonCopyable<Stream> {
     Stream(const char *name = NULL);
     virtual ~Stream();
 
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
     int putc(int c);
     int puts(const char *s);
     int getc();
@@ -59,7 +60,7 @@ class Stream : public FileLike, private NonCopyable<Stream> {
         return _file;
     }
 
-protected:
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
     virtual int close();
     virtual ssize_t write(const void *buffer, size_t length);
     virtual ssize_t read(void *buffer, size_t length);
@@ -70,10 +71,13 @@ class Stream : public FileLike, private NonCopyable<Stream> {
     virtual int sync();
     virtual off_t size();
 
+protected:
     virtual int _putc(int c) = 0;
     virtual int _getc() = 0;
 
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
     std::FILE *_file;
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 
     /** Acquire exclusive access to this object.
      */

platform/cxxsupport/mstd_mutex

@@ -373,7 +373,7 @@ private:
 template <class Callable, class... Args>
 void call_once(once_flag &flag, Callable&& f, Args&&... args)
 {
-    if (!(core_util_atomic_load_explicit(&flag.__guard, mbed_memory_order_acquire) & 1)) {
+    if (!(core_util_atomic_load_explicit((uint8_t *)&flag.__guard, mbed_memory_order_acquire) & 1)) {
         if (__cxa_guard_acquire(&flag.__guard)) {
              mstd::invoke(mstd::forward<Callable>(f), mstd::forward<Args>(args)...);
              __cxa_guard_release(&flag.__guard);

platform/mbed_lib.json

@@ -12,7 +12,12 @@
         },
 
         "stdio-buffered-serial": {
-            "help": "(Applies if target.console-uart is true.) Use UARTSerial driver to obtain buffered serial I/O on stdin/stdout/stderr. If false, unbuffered serial_getc and serial_putc are used directly.",
+            "help": "(Applies if target.console-uart is true and stdio-minimal-console-only is false.) Use UARTSerial driver to obtain buffered serial I/O on stdin/stdout/stderr. If false, unbuffered serial_getc and serial_putc are used directly.",
+            "value": false
+        },
+
+        "stdio-minimal-console-only": {
+            "help": "(Ignores stdio-buffered-serial) Creates a console for basic unbuffered I/O operations. Enable if your application does not require file handles to access the serial interface. The POSIX `fsync` function will always an error.",
             "value": false
         },
 

platform/mbed_retarget.h

@@ -82,6 +82,7 @@ typedef unsigned int  gid_t;    ///< Group ID
 /** \addtogroup platform-public-api */
 /** @{*/
 
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 /**
  * \defgroup platform_retarget Retarget functions
  * @{
@@ -90,7 +91,6 @@ typedef unsigned int  gid_t;    ///< Group ID
 /* DIR declarations must also be here */
 #if __cplusplus
 namespace mbed {
-
 class FileHandle;
 class DirHandle;
 
@@ -185,6 +185,7 @@ typedef mbed::DirHandle DIR;
 #else
 typedef struct Dir DIR;
 #endif
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 
 /* The intent of this section is to unify the errno error values to match
  * the POSIX definitions for the GCC_ARM, ARMCC and IAR compilers. This is
@@ -559,6 +560,7 @@ struct pollfd {
 #if __cplusplus
 extern "C" {
 #endif
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
     int open(const char *path, int oflag, ...);
 #ifndef __IAR_SYSTEMS_ICC__ /* IAR provides fdopen itself */
 #if __cplusplus
@@ -567,12 +569,14 @@ extern "C" {
     FILE *fdopen(int fildes, const char *mode);
 #endif
 #endif
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
     ssize_t write(int fildes, const void *buf, size_t nbyte);
     ssize_t read(int fildes, void *buf, size_t nbyte);
+    int fsync(int fildes);
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
     off_t lseek(int fildes, off_t offset, int whence);
     int ftruncate(int fildes, off_t length);
     int isatty(int fildes);
-    int fsync(int fildes);
     int fstat(int fildes, struct stat *st);
     int fcntl(int fildes, int cmd, ...);
     int poll(struct pollfd fds[], nfds_t nfds, int timeout);
@@ -586,11 +590,12 @@ extern "C" {
     long telldir(DIR *);
     void seekdir(DIR *, long);
     int mkdir(const char *name, mode_t n);
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 #if __cplusplus
 }; // extern "C"
 
 namespace mbed {
-
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 /** This call is an analogue to POSIX fdopen().
  *
  *  It associates a C stream to an already-opened FileHandle, to allow you to
@@ -619,6 +624,33 @@ std::FILE *fdopen(mbed::FileHandle *fh, const char *mode);
  */
 int bind_to_fd(mbed::FileHandle *fh);
 
+#else
+/** Targets may implement this to override how to write to the console.
+ *
+ * If the target has provided minimal_console_putc, this is called
+ * to give the target a chance to specify an alternative minimal console.
+ *
+ * If this is not provided, serial_putc will be used if
+ * `target.console-uart` is `true`, else there will not be an output.
+ *
+ *  @param c   The char to write
+ *  @return    The written char
+ */
+int minimal_console_putc(int c);
+
+/** Targets may implement this to override how to read from the console.
+ *
+ * If the target has provided minimal_console_getc, this is called
+ * to give the target a chance to specify an alternative minimal console.
+ *
+ * If this is not provided, serial_getc will be used if
+ * `target.console-uart` is `true`, else no input would be captured.
+ *
+ *  @return  The char read from the serial port
+ */
+int minimal_console_getc();
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
+
 } // namespace mbed
 
 #endif // __cplusplus

platform/source/Stream.cpp

@@ -20,9 +20,14 @@
 
 namespace mbed {
 
-Stream::Stream(const char *name) : FileLike(name), _file(NULL)
+Stream::Stream(const char *name) :
+    FileLike(name)
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
+    , _file(NULL)
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 {
     // No lock needed in constructor
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
     /* open ourselves */
     _file = fdopen(this, "w+");
     // fdopen() will make us buffered because Stream::isatty()
@@ -33,14 +38,18 @@ Stream::Stream(const char *name) : FileLike(name), _file(NULL)
     } else {
         MBED_ERROR1(MBED_MAKE_ERROR(MBED_MODULE_PLATFORM, MBED_ERROR_CODE_OPEN_FAILED), "Stream obj failure", _file);
     }
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 }
 
 Stream::~Stream()
 {
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
     // No lock can be used in destructor
     fclose(_file);
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 }
 
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 int Stream::putc(int c)
 {
     lock();
@@ -73,6 +82,7 @@ char *Stream::gets(char *s, int size)
     unlock();
     return ret;
 }
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
 
 int Stream::close()
 {
@@ -142,6 +152,8 @@ off_t Stream::size()
     return 0;
 }
 
+#if !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
+
 int Stream::printf(const char *format, ...)
 {
     lock();
@@ -184,4 +196,6 @@ int Stream::vscanf(const char *format, std::va_list args)
     return r;
 }
 
+#endif // !MBED_CONF_PLATFORM_STDIO_MINIMAL_CONSOLE_ONLY
+
 } // namespace mbed