semihosting_common.h

Go to the documentation of this file.

/* SPDX-License-Identifier: GPL-2.0-or-later */
 
/***************************************************************************
 *   Copyright (C) 2018 by Liviu Ionescu                                   *
 *   <ilg@livius.net>                                                      *
 *                                                                         *
 *   Copyright (C) 2009 by Marvell Technology Group Ltd.                   *
 *   Written by Nicolas Pitre <nico@marvell.com>                           *
 ***************************************************************************/
 
#ifndef OPENOCD_TARGET_SEMIHOSTING_COMMON_H
#define OPENOCD_TARGET_SEMIHOSTING_COMMON_H
 
#include <stdint.h>
#include <stdbool.h>
#include <time.h>
#include "helper/replacements.h"
#include <server/server.h>
 
/*
 * According to:
 * "Semihosting for AArch32 and AArch64, 2025Q1"
 * https://github.com/ARM-software/abi-aa/releases/download/2025Q1/semihosting.pdf
 * and to:
 * https://developer.arm.com/documentation/dui0203/latest/semihosting/about-semihosting/the-semihosting-interface
 * from ARM Ltd.
 *
 * The available semihosting operation numbers passed in R0 are allocated
 * as follows:
 * - 0x00-0x31 Used by ARM.
 * - 0x32-0xFF Reserved for future use by ARM.
 * - 0x100-0x1FF Reserved for user applications. These are not used by ARM.
 *   However, if you are writing your own SVC operations, you are advised
 *   to use a different SVC number rather than using the semihosted
 *   SVC number and these operation type numbers.
 * - 0x200-0xFFFFFFFF Undefined and currently unused. It is recommended
 *   that you do not use these.
 */
 
enum semihosting_operation_numbers {
    /*
     * ARM semihosting operations, in lexicographic order.
     */
    SEMIHOSTING_ENTER_SVC = 0x17,   /* DEPRECATED */
 
    SEMIHOSTING_SYS_CLOSE = 0x02,
    SEMIHOSTING_SYS_CLOCK = 0x10,
    SEMIHOSTING_SYS_ELAPSED = 0x30,
    SEMIHOSTING_SYS_ERRNO = 0x13,
    SEMIHOSTING_SYS_EXIT = 0x18,
    SEMIHOSTING_SYS_EXIT_EXTENDED = 0x20,
    SEMIHOSTING_SYS_FLEN = 0x0C,
    SEMIHOSTING_SYS_GET_CMDLINE = 0x15,
    SEMIHOSTING_SYS_HEAPINFO = 0x16,
    SEMIHOSTING_SYS_ISERROR = 0x08,
    SEMIHOSTING_SYS_ISTTY = 0x09,
    SEMIHOSTING_SYS_OPEN = 0x01,
    SEMIHOSTING_SYS_READ = 0x06,
    SEMIHOSTING_SYS_READC = 0x07,
    SEMIHOSTING_SYS_REMOVE = 0x0E,
    SEMIHOSTING_SYS_RENAME = 0x0F,
    SEMIHOSTING_SYS_SEEK = 0x0A,
    SEMIHOSTING_SYS_SYSTEM = 0x12,
    SEMIHOSTING_SYS_TICKFREQ = 0x31,
    SEMIHOSTING_SYS_TIME = 0x11,
    SEMIHOSTING_SYS_TMPNAM = 0x0D,
    SEMIHOSTING_SYS_WRITE = 0x05,
    SEMIHOSTING_SYS_WRITEC = 0x03,
    SEMIHOSTING_SYS_WRITE0 = 0x04,
    SEMIHOSTING_ARM_RESERVED_START = 0x32,
    SEMIHOSTING_ARM_RESERVED_END = 0xFF,
    SEMIHOSTING_USER_CMD_0X100 = 0x100, /* First user cmd op code */
    SEMIHOSTING_USER_CMD_0X107 = 0x107, /* Last supported user cmd op code */
    SEMIHOSTING_USER_CMD_0X1FF = 0x1FF, /* Last user cmd op code */
};
 
#define SEMIHOSTING_MAX_TCL_COMMAND_FIELD_LENGTH (1024 * 1024)
 
/*
 * Codes used by SEMIHOSTING_SYS_EXIT (formerly
 * SEMIHOSTING_REPORT_EXCEPTION).
 * On 64-bits, the exit code is passed explicitly.
 */
enum semihosting_reported_exceptions {
    /* On 32 bits, use it for exit(0) */
    ADP_STOPPED_APPLICATION_EXIT = ((2 << 16) + 38),
    /* On 32 bits, use it for exit(1) */
    ADP_STOPPED_RUN_TIME_ERROR = ((2 << 16) + 35),
};
 
enum semihosting_redirect_config {
    SEMIHOSTING_REDIRECT_CFG_NONE,
    SEMIHOSTING_REDIRECT_CFG_DEBUG,
    SEMIHOSTING_REDIRECT_CFG_STDIO,
    SEMIHOSTING_REDIRECT_CFG_ALL,
};
 
enum semihosting_result {
    SEMIHOSTING_NONE,       /* Not halted for a semihosting call. */
    SEMIHOSTING_HANDLED,    /* Call handled, and target was resumed. */
    SEMIHOSTING_WAITING,    /* Call handled, target is halted waiting until we can resume. */
    SEMIHOSTING_ERROR       /* Something went wrong. */
};
 
struct target;
 
/*
 * A pointer to this structure was added to the target structure.
 */
struct semihosting {
 
    bool is_active;
 
    int stdin_fd, stdout_fd, stderr_fd;
 
    enum semihosting_redirect_config redirect_cfg;
 
    struct connection *tcp_connection;
 
    bool is_fileio;
 
    bool hit_fileio;
 
    bool is_resumable;
 
    bool has_resumable_exit;
 
    size_t word_size_bytes;
 
    int op;
 
    uint64_t param;
 
    int64_t result;
 
    int sys_errno;
 
    char *cmdline;
 
    clock_t setup_time;
 
    char *basedir;
 
    int (*user_command_extension)(struct target *target);
 
    int (*setup)(struct target *target, int enable);
    int (*post_result)(struct target *target);
};
 
int semihosting_common_init(struct target *target, void *setup,
    void *post_result);
int semihosting_common(struct target *target);
 
/* utility functions which may also be used by semihosting extensions (custom vendor-defined syscalls) */
int semihosting_read_fields(struct target *target, size_t number,
    uint8_t *fields);
uint64_t semihosting_get_field(struct target *target, size_t index,
    uint8_t *fields);
 
extern const struct command_registration semihosting_common_handlers[];
 
#endif  /* OPENOCD_TARGET_SEMIHOSTING_COMMON_H */