src/target/semihosting_common.h

   1 /***************************************************************************
   2  *   Copyright (C) 2018 by Liviu Ionescu                                   *
   3  *   <ilg@livius.net>                                                      *
   4  *                                                                         *
   5  *   Copyright (C) 2009 by Marvell Technology Group Ltd.                   *
   6  *   Written by Nicolas Pitre <nico@marvell.com>                           *
   7  *                                                                         *
   8  *   This program is free software; you can redistribute it and/or modify  *
   9  *   it under the terms of the GNU General Public License as published by  *
  10  *   the Free Software Foundation; either version 2 of the License, or     *
  11  *   (at your option) any later version.                                   *
  12  *                                                                         *
  13  *   This program is distributed in the hope that it will be useful,       *
  14  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  15  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
  16  *   GNU General Public License for more details.                          *
  17  *                                                                         *
  18  *   You should have received a copy of the GNU General Public License     *
  19  *   along with this program.  If not, see <http://www.gnu.org/licenses/>. *
  20  ***************************************************************************/
  21
  22 #ifndef OPENOCD_TARGET_SEMIHOSTING_COMMON_H
  23 #define OPENOCD_TARGET_SEMIHOSTING_COMMON_H
  24
  25 #include <stdint.h>
  26 #include <stdbool.h>
  27 #include <time.h>
  28 #include "helper/replacements.h"
  29 #include <server/server.h>
  30
  31 /*
  32  * According to:
  33  * "Semihosting for AArch32 and AArch64, Release 2.0"
  34  * https://static.docs.arm.com/100863/0200/semihosting.pdf
  35  * from ARM Ltd.
  36  *
  37  * The available semihosting operation numbers passed in R0 are allocated
  38  * as follows:
  39  * - 0x00-0x31 Used by ARM.
  40  * - 0x32-0xFF Reserved for future use by ARM.
  41  * - 0x100-0x1FF Reserved for user applications. These are not used by ARM.
  42  *   However, if you are writing your own SVC operations, you are advised
  43  *   to use a different SVC number rather than using the semihosted
  44  *   SVC number and these operation type numbers.
  45  * - 0x200-0xFFFFFFFF Undefined and currently unused. It is recommended
  46  *   that you do not use these.
  47  */
  48
  49 enum semihosting_operation_numbers {
  50         /*
  51          * ARM semihosting operations, in lexicographic order.
  52          */
  53         SEMIHOSTING_ENTER_SVC = 0x17,   /* DEPRECATED */
  54
  55         SEMIHOSTING_SYS_CLOSE = 0x02,
  56         SEMIHOSTING_SYS_CLOCK = 0x10,
  57         SEMIHOSTING_SYS_ELAPSED = 0x30,
  58         SEMIHOSTING_SYS_ERRNO = 0x13,
  59         SEMIHOSTING_SYS_EXIT = 0x18,
  60         SEMIHOSTING_SYS_EXIT_EXTENDED = 0x20,
  61         SEMIHOSTING_SYS_FLEN = 0x0C,
  62         SEMIHOSTING_SYS_GET_CMDLINE = 0x15,
  63         SEMIHOSTING_SYS_HEAPINFO = 0x16,
  64         SEMIHOSTING_SYS_ISERROR = 0x08,
  65         SEMIHOSTING_SYS_ISTTY = 0x09,
  66         SEMIHOSTING_SYS_OPEN = 0x01,
  67         SEMIHOSTING_SYS_READ = 0x06,
  68         SEMIHOSTING_SYS_READC = 0x07,
  69         SEMIHOSTING_SYS_REMOVE = 0x0E,
  70         SEMIHOSTING_SYS_RENAME = 0x0F,
  71         SEMIHOSTING_SYS_SEEK = 0x0A,
  72         SEMIHOSTING_SYS_SYSTEM = 0x12,
  73         SEMIHOSTING_SYS_TICKFREQ = 0x31,
  74         SEMIHOSTING_SYS_TIME = 0x11,
  75         SEMIHOSTING_SYS_TMPNAM = 0x0D,
  76         SEMIHOSTING_SYS_WRITE = 0x05,
  77         SEMIHOSTING_SYS_WRITEC = 0x03,
  78         SEMIHOSTING_SYS_WRITE0 = 0x04,
  79         SEMIHOSTING_USER_CMD_0x100 = 0x100, /* First user cmd op code */
  80         SEMIHOSTING_USER_CMD_0x107 = 0x107, /* Last supported user cmd op code */
  81         SEMIHOSTING_USER_CMD_0x1FF = 0x1FF, /* Last user cmd op code */
  82 };
  83
  84 /** Maximum allowed Tcl command segment length in bytes*/
  85 #define SEMIHOSTING_MAX_TCL_COMMAND_FIELD_LENGTH (1024 * 1024)
  86
  87 /*
  88  * Codes used by SEMIHOSTING_SYS_EXIT (formerly
  89  * SEMIHOSTING_REPORT_EXCEPTION).
  90  * On 64-bits, the exit code is passed explicitly.
  91  */
  92 enum semihosting_reported_exceptions {
  93         /* On 32 bits, use it for exit(0) */
  94         ADP_STOPPED_APPLICATION_EXIT = ((2 << 16) + 38),
  95         /* On 32 bits, use it for exit(1) */
  96         ADP_STOPPED_RUN_TIME_ERROR = ((2 << 16) + 35),
  97 };
  98
  99 enum semihosting_redirect_config {
 100         SEMIHOSTING_REDIRECT_CFG_NONE,
 101         SEMIHOSTING_REDIRECT_CFG_DEBUG,
 102         SEMIHOSTING_REDIRECT_CFG_STDIO,
 103         SEMIHOSTING_REDIRECT_CFG_ALL,
 104 };
 105
 106 struct target;
 107
 108 /*
 109  * A pointer to this structure was added to the target structure.
 110  */
 111 struct semihosting {
 112
 113         /** A flag reporting whether semihosting is active. */
 114         bool is_active;
 115
 116         /** Semihosting STDIO file descriptors */
 117         int stdin_fd, stdout_fd, stderr_fd;
 118
 119         /** redirection configuration, NONE by default */
 120         enum semihosting_redirect_config redirect_cfg;
 121
 122         /** Handle to redirect semihosting print via tcp */
 123         struct connection *tcp_connection;
 124
 125         /** A flag reporting whether semihosting fileio is active. */
 126         bool is_fileio;
 127
 128         /** A flag reporting whether semihosting fileio operation is active. */
 129         bool hit_fileio;
 130
 131         /** Most are resumable, except the two exit calls. */
 132         bool is_resumable;
 133
 134         /**
 135          * When SEMIHOSTING_SYS_EXIT is called outside a debug session,
 136          * things are simple, the openocd process calls exit() and passes
 137          * the value returned by the target.
 138          * When SEMIHOSTING_SYS_EXIT is called during a debug session,
 139          * by default execution returns to the debugger, leaving the
 140          * debugger in a HALT state, similar to the state entered when
 141          * encountering a break.
 142          * In some use cases, it is useful to have SEMIHOSTING_SYS_EXIT
 143          * return normally, as any semihosting call, and do not break
 144          * to the debugger.
 145          * The standard allows this to happen, but the condition
 146          * to trigger it is a bit obscure ("by performing an RDI_Execute
 147          * request or equivalent").
 148          *
 149          * To make the SEMIHOSTING_SYS_EXIT call return normally, enable
 150          * this variable via the dedicated command (default: disabled).
 151          */
 152         bool has_resumable_exit;
 153
 154         /** The Target (hart) word size; 8 for 64-bits targets. */
 155         size_t word_size_bytes;
 156
 157         /** The current semihosting operation (R0 on ARM). */
 158         int op;
 159
 160         /** The current semihosting parameter (R1 or ARM). */
 161         uint64_t param;
 162
 163         /**
 164          * The current semihosting result to be returned to the application.
 165          * Usually 0 for success, -1 for error,
 166          * but sometimes a useful value, even a pointer.
 167          */
 168         int64_t result;
 169
 170         /** The value to be returned by semihosting SYS_ERRNO request. */
 171         int sys_errno;
 172
 173         /** The semihosting command line to be passed to the target. */
 174         char *cmdline;
 175
 176         /** The current time when 'execution starts' */
 177         clock_t setup_time;
 178
 179         int (*setup)(struct target *target, int enable);
 180         int (*post_result)(struct target *target);
 181 };
 182
 183 int semihosting_common_init(struct target *target, void *setup,
 184         void *post_result);
 185 int semihosting_common(struct target *target);
 186
 187 #endif  /* OPENOCD_TARGET_SEMIHOSTING_COMMON_H */