src/target/semihosting_common.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2
   3 /***************************************************************************
   4  *   Copyright (C) 2018 by Liviu Ionescu                                   *
   5  *   <ilg@livius.net>                                                      *
   6  *                                                                         *
   7  *   Copyright (C) 2009 by Marvell Technology Group Ltd.                   *
   8  *   Written by Nicolas Pitre <nico@marvell.com>                           *
   9  ***************************************************************************/
  10
  11 #ifndef OPENOCD_TARGET_SEMIHOSTING_COMMON_H
  12 #define OPENOCD_TARGET_SEMIHOSTING_COMMON_H
  13
  14 #include <stdint.h>
  15 #include <stdbool.h>
  16 #include <time.h>
  17 #include "helper/replacements.h"
  18 #include <server/server.h>
  19
  20 /*
  21  * According to:
  22  * "Semihosting for AArch32 and AArch64, Release 2.0"
  23  * https://static.docs.arm.com/100863/0200/semihosting.pdf
  24  * from ARM Ltd.
  25  *
  26  * The available semihosting operation numbers passed in R0 are allocated
  27  * as follows:
  28  * - 0x00-0x31 Used by ARM.
  29  * - 0x32-0xFF Reserved for future use by ARM.
  30  * - 0x100-0x1FF Reserved for user applications. These are not used by ARM.
  31  *   However, if you are writing your own SVC operations, you are advised
  32  *   to use a different SVC number rather than using the semihosted
  33  *   SVC number and these operation type numbers.
  34  * - 0x200-0xFFFFFFFF Undefined and currently unused. It is recommended
  35  *   that you do not use these.
  36  */
  37
  38 enum semihosting_operation_numbers {
  39         /*
  40          * ARM semihosting operations, in lexicographic order.
  41          */
  42         SEMIHOSTING_ENTER_SVC = 0x17,   /* DEPRECATED */
  43
  44         SEMIHOSTING_SYS_CLOSE = 0x02,
  45         SEMIHOSTING_SYS_CLOCK = 0x10,
  46         SEMIHOSTING_SYS_ELAPSED = 0x30,
  47         SEMIHOSTING_SYS_ERRNO = 0x13,
  48         SEMIHOSTING_SYS_EXIT = 0x18,
  49         SEMIHOSTING_SYS_EXIT_EXTENDED = 0x20,
  50         SEMIHOSTING_SYS_FLEN = 0x0C,
  51         SEMIHOSTING_SYS_GET_CMDLINE = 0x15,
  52         SEMIHOSTING_SYS_HEAPINFO = 0x16,
  53         SEMIHOSTING_SYS_ISERROR = 0x08,
  54         SEMIHOSTING_SYS_ISTTY = 0x09,
  55         SEMIHOSTING_SYS_OPEN = 0x01,
  56         SEMIHOSTING_SYS_READ = 0x06,
  57         SEMIHOSTING_SYS_READC = 0x07,
  58         SEMIHOSTING_SYS_REMOVE = 0x0E,
  59         SEMIHOSTING_SYS_RENAME = 0x0F,
  60         SEMIHOSTING_SYS_SEEK = 0x0A,
  61         SEMIHOSTING_SYS_SYSTEM = 0x12,
  62         SEMIHOSTING_SYS_TICKFREQ = 0x31,
  63         SEMIHOSTING_SYS_TIME = 0x11,
  64         SEMIHOSTING_SYS_TMPNAM = 0x0D,
  65         SEMIHOSTING_SYS_WRITE = 0x05,
  66         SEMIHOSTING_SYS_WRITEC = 0x03,
  67         SEMIHOSTING_SYS_WRITE0 = 0x04,
  68         SEMIHOSTING_ARM_RESERVED_START = 0x32,
  69         SEMIHOSTING_ARM_RESERVED_END = 0xFF,
  70         SEMIHOSTING_USER_CMD_0X100 = 0x100, /* First user cmd op code */
  71         SEMIHOSTING_USER_CMD_0X107 = 0x107, /* Last supported user cmd op code */
  72         SEMIHOSTING_USER_CMD_0X1FF = 0x1FF, /* Last user cmd op code */
  73 };
  74
  75 /** Maximum allowed Tcl command segment length in bytes*/
  76 #define SEMIHOSTING_MAX_TCL_COMMAND_FIELD_LENGTH (1024 * 1024)
  77
  78 /*
  79  * Codes used by SEMIHOSTING_SYS_EXIT (formerly
  80  * SEMIHOSTING_REPORT_EXCEPTION).
  81  * On 64-bits, the exit code is passed explicitly.
  82  */
  83 enum semihosting_reported_exceptions {
  84         /* On 32 bits, use it for exit(0) */
  85         ADP_STOPPED_APPLICATION_EXIT = ((2 << 16) + 38),
  86         /* On 32 bits, use it for exit(1) */
  87         ADP_STOPPED_RUN_TIME_ERROR = ((2 << 16) + 35),
  88 };
  89
  90 enum semihosting_redirect_config {
  91         SEMIHOSTING_REDIRECT_CFG_NONE,
  92         SEMIHOSTING_REDIRECT_CFG_DEBUG,
  93         SEMIHOSTING_REDIRECT_CFG_STDIO,
  94         SEMIHOSTING_REDIRECT_CFG_ALL,
  95 };
  96
  97 enum semihosting_result {
  98         SEMIHOSTING_NONE,               /* Not halted for a semihosting call. */
  99         SEMIHOSTING_HANDLED,    /* Call handled, and target was resumed. */
 100         SEMIHOSTING_WAITING,    /* Call handled, target is halted waiting until we can resume. */
 101         SEMIHOSTING_ERROR               /* Something went wrong. */
 102 };
 103
 104 struct target;
 105
 106 /*
 107  * A pointer to this structure was added to the target structure.
 108  */
 109 struct semihosting {
 110
 111         /** A flag reporting whether semihosting is active. */
 112         bool is_active;
 113
 114         /** Semihosting STDIO file descriptors */
 115         int stdin_fd, stdout_fd, stderr_fd;
 116
 117         /** redirection configuration, NONE by default */
 118         enum semihosting_redirect_config redirect_cfg;
 119
 120         /** Handle to redirect semihosting print via tcp */
 121         struct connection *tcp_connection;
 122
 123         /** A flag reporting whether semihosting fileio is active. */
 124         bool is_fileio;
 125
 126         /** A flag reporting whether semihosting fileio operation is active. */
 127         bool hit_fileio;
 128
 129         /** Most are resumable, except the two exit calls. */
 130         bool is_resumable;
 131
 132         /**
 133          * When SEMIHOSTING_SYS_EXIT is called outside a debug session,
 134          * things are simple, the openocd process calls exit() and passes
 135          * the value returned by the target.
 136          * When SEMIHOSTING_SYS_EXIT is called during a debug session,
 137          * by default execution returns to the debugger, leaving the
 138          * debugger in a HALT state, similar to the state entered when
 139          * encountering a break.
 140          * In some use cases, it is useful to have SEMIHOSTING_SYS_EXIT
 141          * return normally, as any semihosting call, and do not break
 142          * to the debugger.
 143          * The standard allows this to happen, but the condition
 144          * to trigger it is a bit obscure ("by performing an RDI_Execute
 145          * request or equivalent").
 146          *
 147          * To make the SEMIHOSTING_SYS_EXIT call return normally, enable
 148          * this variable via the dedicated command (default: disabled).
 149          */
 150         bool has_resumable_exit;
 151
 152         /** The Target (hart) word size; 8 for 64-bits targets. */
 153         size_t word_size_bytes;
 154
 155         /** The current semihosting operation (R0 on ARM). */
 156         int op;
 157
 158         /** The current semihosting parameter (R1 or ARM). */
 159         uint64_t param;
 160
 161         /**
 162          * The current semihosting result to be returned to the application.
 163          * Usually 0 for success, -1 for error,
 164          * but sometimes a useful value, even a pointer.
 165          */
 166         int64_t result;
 167
 168         /** The value to be returned by semihosting SYS_ERRNO request. */
 169         int sys_errno;
 170
 171         /** The semihosting command line to be passed to the target. */
 172         char *cmdline;
 173
 174         /** The current time when 'execution starts' */
 175         clock_t setup_time;
 176
 177         /** Base directory for semihosting I/O operations. */
 178         char *basedir;
 179
 180         /**
 181          * Target's extension of semihosting user commands.
 182          * @returns ERROR_NOT_IMPLEMENTED when user command is not handled, otherwise
 183          * sets semihosting->result and semihosting->sys_errno and returns ERROR_OK.
 184          */
 185         int (*user_command_extension)(struct target *target);
 186
 187         int (*setup)(struct target *target, int enable);
 188         int (*post_result)(struct target *target);
 189 };
 190
 191 /**
 192  * @brief Convert the syscall opcode to a human-readable string
 193  * @param[in] opcode Syscall opcode
 194  * @return String representation of syscall opcode
 195  */
 196 const char *semihosting_opcode_to_str(uint64_t opcode);
 197
 198 int semihosting_common_init(struct target *target, void *setup,
 199         void *post_result);
 200 int semihosting_common(struct target *target);
 201
 202 /* utility functions which may also be used by semihosting extensions (custom vendor-defined syscalls) */
 203 int semihosting_read_fields(struct target *target, size_t number,
 204         uint8_t *fields);
 205 int semihosting_write_fields(struct target *target, size_t number,
 206         uint8_t *fields);
 207 uint64_t semihosting_get_field(struct target *target, size_t index,
 208         uint8_t *fields);
 209 void semihosting_set_field(struct target *target, uint64_t value,
 210         size_t index,
 211         uint8_t *fields);
 212
 213 extern const struct command_registration semihosting_common_handlers[];
 214
 215 #endif  /* OPENOCD_TARGET_SEMIHOSTING_COMMON_H */