trace-semihosting.cpp

Go to the documentation of this file.

/*
 * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
 * Copyright (c) 2015-2025 Liviu Ionescu. All rights reserved.
 *
 * Permission to use, copy, modify, and/or distribute this software
 * for any purpose is hereby granted, under the terms of the MIT license.
 *
 * If a copy of the license was not distributed with this file, it can
 * be obtained from https://opensource.org/licenses/mit.
 */
 
#if defined(__clang__)
#pragma clang diagnostic ignored "-Wempty-translation-unit"
#elif defined(__GNUC__)
#pragma GCC diagnostic ignored "-Wold-style-cast"
#pragma GCC diagnostic ignored "-Wcast-qual"
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
 
// ----------------------------------------------------------------------------
 
#if defined(__ARM_EABI__)
 
// ----------------------------------------------------------------------------
 
#if defined(TRACE)
 
#if defined(OS_USE_OS_APP_CONFIG_H)
#include <cmsis-plus/os-app-config.h>
#endif
 
#if defined(OS_USE_TRACE_SEMIHOSTING_DEBUG) \
    || defined(OS_USE_TRACE_SEMIHOSTING_STDOUT)
 
#include <cmsis-plus/diag/trace.h>
 
// ----------------------------------------------------------------------------
 
#if defined(OS_DEBUG_SEMIHOSTING_FAULTS)
#error "Cannot debug semihosting using semihosting trace; use OS_USE_TRACE_ITM"
#endif
 
#include <cmsis-plus/arm/semihosting.h>
 
// ----------------------------------------------------------------------------
 
namespace os
{
  namespace trace
  {
    // ------------------------------------------------------------------------
 
    void
    initialize (void)
    {
      // For semihosting, no inits are required.
    }
 
    // ------------------------------------------------------------------------
 
    // Semihosting is another output channel that can be used for the trace
    // messages. It comes in two flavours: STDOUT and DEBUG. The STDOUT channel
    // is the equivalent of the stdout in POSIX and in most cases it is
    // forwarded to the GDB server stdout stream. The debug channel is a
    // separate channel. STDOUT is buffered, so nothing is displayed until
    // a \n; DEBUG is not buffered, but can be slow.
    //
    // Choosing between semihosting stdout and debug depends on the
    // capabilities of your GDB server, and also on specific needs. It is
    // recommended to test DEBUG first, and if too slow, try STDOUT.
    //
    // The JLink GDB server fully support semihosting, and both configurations
    // are available; to activate it, use "monitor semihosting enable" or check
    // the corresponding button in the JLink Debugging plug-in.
    // In OpenOCD, support for semihosting can be enabled using
    // "monitor arm semihosting enable".
    //
    // Note: Applications built with semihosting output active normally cannot
    // be executed without the debugger connected and active, since they use
    // BKPT to communicate with the host. However, with a carefully written
    // HardFault_Handler, the semihosting BKPT calls can be processed, making
    // possible to run semihosting applications as standalone, without being
    // terminated with hardware faults.
 
    // ------------------------------------------------------------------------
 
#if defined(OS_USE_TRACE_SEMIHOSTING_DEBUG)
 
#if !defined(OS_INTEGER_TRACE_SEMIHOSTING_BUFF_ARRAY_SIZE)
#define OS_INTEGER_TRACE_SEMIHOSTING_BUFF_ARRAY_SIZE (16)
#endif
 
    ssize_t
    write (const void* buf, std::size_t nbyte)
    {
      if (buf == nullptr || nbyte == 0)
        {
          return 0;
        }
 
      const char* cbuf = (const char*)buf;
 
      // Since the single character debug channel is quite slow, try to
      // optimise and send a null terminated string, if possible.
      if (cbuf[nbyte] == '\0')
        {
          // send string
          call_host (SEMIHOSTING_SYS_WRITE0, (void*)cbuf);
        }
      else
        {
          // If not, use a local buffer to speed things up.
          // For re-entrance, this bugger must be allocated on the stack,
          // so be cautious with the size.
          char tmp[OS_INTEGER_TRACE_SEMIHOSTING_BUFF_ARRAY_SIZE];
          size_t togo = nbyte;
          while (togo > 0)
            {
              std::size_t n
                  = ((togo < sizeof (tmp)) ? togo : sizeof (tmp) - 1);
              std::size_t i = 0;
              for (; i < n; ++i, ++cbuf)
                {
                  tmp[i] = *cbuf;
                }
              tmp[i] = '\0';
 
              call_host (SEMIHOSTING_SYS_WRITE0, (void*)tmp);
 
              togo -= n;
            }
        }
 
      // All bytes written.
      return (ssize_t)nbyte;
    }
 
#elif defined(OS_USE_TRACE_SEMIHOSTING_STDOUT)
 
    ssize_t
    write (const void* buf, std::size_t nbyte)
    {
      if (buf == nullptr || nbyte == 0)
        {
          return 0;
        }
 
      static int handle; // STATIC!
 
      void* block[3];
      int ret;
 
      if (handle == 0)
        {
          // On the very first call get the file handle from the host.
 
          // Special filename for stdin/out/err.
          block[0] = (void*)":tt";
          block[1] = (void*)4; // mode "w"
          // Length of ":tt", except null terminator.
          block[2] = (void*)(sizeof (":tt") - 1);
 
          ret = call_host (SEMIHOSTING_SYS_OPEN, (void*)block);
          if (ret == -1)
            {
              return -1;
            }
 
          handle = ret;
        }
 
      block[0] = (void*)handle;
      block[1] = (void*)buf;
      block[2] = (void*)nbyte;
      // Send character array to host file/device.
      ret = call_host (SEMIHOSTING_SYS_WRITE, (void*)block);
      // This call returns the number of bytes NOT written (0 if all ok).
 
      // -1 is not a legal value, but SEGGER seems to return it
      if (ret == -1)
        {
          return -1;
        }
 
      // The compliant way of returning errors.
      if (ret == (int)nbyte)
        {
          return -1;
        }
 
      // Return the number of bytes written.
      return (ssize_t)(nbyte) - (ssize_t)ret;
    }
 
#endif /* defined(OS_USE_TRACE_SEMIHOSTING_STDOUT) */
 
  } /* namespace trace */
} /* namespace os */
 
#endif /* defined(OS_USE_TRACE_SEMIHOSTING_DEBUG) || \
          defined(OS_USE_TRACE_SEMIHOSTING_STDOUT) */
#endif /* defined(TRACE) */
 
// ----------------------------------------------------------------------------
 
#endif /* defined(__ARM_EABI__) */
 
// ----------------------------------------------------------------------------