include/semihosting.h

   1 /* SPDX-License-Identifier: GPL-2.0+ */
   2 /*
   3  * Copyright (C) 2022 Sean Anderson <sean.anderson@seco.com>
   4  */
   5
   6 #ifndef _SEMIHOSTING_H
   7 #define _SEMIHOSTING_H
   8
   9 /*
  10  * These are the encoded instructions used to indicate a semihosting trap. They
  11  * are named like SMH_ISA_INSN, where ISA is the instruction set (e.g.
  12  * AArch64), and INSN is the mneumonic for the instruction.
  13  */
  14 #define SMH_A64_HLT 0xD45E0000
  15 #define SMH_A32_SVC 0xEF123456
  16 #define SMH_A32_HLT 0xE10F0070
  17 #define SMH_T32_SVC 0xDFAB
  18 #define SMH_T32_HLT 0xBABC
  19
  20 /**
  21  * smh_trap() - ARCH-specific semihosting call.
  22  *
  23  * Semihosting library/driver can use this function to do the
  24  * actual semihosting calls.
  25  *
  26  * Return: Error code defined by semihosting spec.
  27  */
  28
  29 long smh_trap(unsigned int sysnum, void *addr);
  30
  31 #if CONFIG_IS_ENABLED(SEMIHOSTING_FALLBACK)
  32 /**
  33  * semihosting_enabled() - Determine whether semihosting is supported
  34  *
  35  * Semihosting-based drivers should call this function before making other
  36  * semihosting calls.
  37  *
  38  * Return: %true if a debugger is attached which supports semihosting, %false
  39  *         otherwise
  40  */
  41 bool semihosting_enabled(void);
  42
  43 /**
  44  * disable_semihosting() - Cause semihosting_enabled() to return false
  45  *
  46  * If U-Boot ever receives an unhandled exception caused by a semihosting trap,
  47  * the trap handler should call this function.
  48  */
  49 void disable_semihosting(void);
  50 #else
  51 static inline bool semihosting_enabled(void)
  52 {
  53         return CONFIG_IS_ENABLED(SEMIHOSTING);
  54 }
  55
  56 static inline void disable_semihosting(void)
  57 {
  58 }
  59 #endif
  60
  61 /**
  62  * enum smh_open_mode - Numeric file modes for use with smh_open()
  63  * MODE_READ: 'r'
  64  * MODE_BINARY: 'b'
  65  * MODE_PLUS: '+'
  66  * MODE_WRITE: 'w'
  67  * MODE_APPEND: 'a'
  68  *
  69  * These modes represent the mode string used by fopen(3) in a form which can
  70  * be passed to smh_open(). These do NOT correspond directly to %O_RDONLY,
  71  * %O_CREAT, etc; see fopen(3) for details. In particular, @MODE_PLUS
  72  * effectively results in adding %O_RDWR, and @MODE_WRITE will add %O_TRUNC.
  73  * For compatibility, @MODE_BINARY should be added when opening non-text files
  74  * (such as images).
  75  */
  76 enum smh_open_mode {
  77         MODE_READ       = 0x0,
  78         MODE_BINARY     = 0x1,
  79         MODE_PLUS       = 0x2,
  80         MODE_WRITE      = 0x4,
  81         MODE_APPEND     = 0x8,
  82 };
  83
  84 /**
  85  * smh_open() - Open a file on the host
  86  * @fname: The name of the file to open
  87  * @mode: The mode to use when opening the file
  88  *
  89  * Return: Either a file descriptor or a negative error on failure
  90  */
  91 long smh_open(const char *fname, enum smh_open_mode mode);
  92
  93 /**
  94  * smh_read() - Read data from a file
  95  * @fd: A file descriptor returned from smh_open()
  96  * @memp: Pointer to a buffer of memory of at least @len bytes
  97  * @len: The number of bytes to read
  98  *
  99  * Return:
 100  * * The number of bytes read on success, with 0 indicating %EOF
 101  * * A negative error on failure
 102  */
 103 long smh_read(long fd, void *memp, size_t len);
 104
 105 /**
 106  * smh_write() - Write data to a file
 107  * @fd: A file descriptor returned from smh_open()
 108  * @memp: Pointer to a buffer of memory of at least @len bytes
 109  * @len: The number of bytes to read
 110  * @written: Pointer which will be updated with the actual bytes written
 111  *
 112  * Return: 0 on success or negative error on failure
 113  */
 114 long smh_write(long fd, const void *memp, size_t len, ulong *written);
 115
 116 /**
 117  * smh_close() - Close an open file
 118  * @fd: A file descriptor returned from smh_open()
 119  *
 120  * Return: 0 on success or negative error on failure
 121  */
 122 long smh_close(long fd);
 123
 124 /**
 125  * smh_flen() - Get the length of a file
 126  * @fd: A file descriptor returned from smh_open()
 127  *
 128  * Return: The length of the file, in bytes, or a negative error on failure
 129  */
 130 long smh_flen(long fd);
 131
 132 /**
 133  * smh_seek() - Seek to a position in a file
 134  * @fd: A file descriptor returned from smh_open()
 135  * @pos: The offset (in bytes) to seek to
 136  *
 137  * Return: 0 on success or negative error on failure
 138  */
 139 long smh_seek(long fd, long pos);
 140
 141 /**
 142  * smh_getc() - Read a character from stdin
 143  *
 144  * Return: The character read, or a negative error on failure
 145  */
 146 int smh_getc(void);
 147
 148 /**
 149  * smh_putc() - Print a character on stdout
 150  * @ch: The character to print
 151  */
 152 void smh_putc(char ch);
 153
 154 /**
 155  * smh_write0() - Print a nul-terminated string on stdout
 156  * @s: The string to print
 157  */
 158 void smh_puts(const char *s);
 159
 160 #endif /* _SEMIHOSTING_H */