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 #if CONFIG_IS_ENABLED(SEMIHOSTING_FALLBACK)
  21 /**
  22  * semihosting_enabled() - Determine whether semihosting is supported
  23  *
  24  * Semihosting-based drivers should call this function before making other
  25  * semihosting calls.
  26  *
  27  * Return: %true if a debugger is attached which supports semihosting, %false
  28  *         otherwise
  29  */
  30 bool semihosting_enabled(void);
  31
  32 /**
  33  * disable_semihosting() - Cause semihosting_enabled() to return false
  34  *
  35  * If U-Boot ever receives an unhandled exception caused by a semihosting trap,
  36  * the trap handler should call this function.
  37  */
  38 void disable_semihosting(void);
  39 #else
  40 static inline bool semihosting_enabled(void)
  41 {
  42         return CONFIG_IS_ENABLED(SEMIHOSTING);
  43 }
  44
  45 static inline void disable_semihosting(void)
  46 {
  47 }
  48 #endif
  49
  50 /**
  51  * enum smh_open_mode - Numeric file modes for use with smh_open()
  52  * MODE_READ: 'r'
  53  * MODE_BINARY: 'b'
  54  * MODE_PLUS: '+'
  55  * MODE_WRITE: 'w'
  56  * MODE_APPEND: 'a'
  57  *
  58  * These modes represent the mode string used by fopen(3) in a form which can
  59  * be passed to smh_open(). These do NOT correspond directly to %O_RDONLY,
  60  * %O_CREAT, etc; see fopen(3) for details. In particular, @MODE_PLUS
  61  * effectively results in adding %O_RDWR, and @MODE_WRITE will add %O_TRUNC.
  62  * For compatibility, @MODE_BINARY should be added when opening non-text files
  63  * (such as images).
  64  */
  65 enum smh_open_mode {
  66         MODE_READ       = 0x0,
  67         MODE_BINARY     = 0x1,
  68         MODE_PLUS       = 0x2,
  69         MODE_WRITE      = 0x4,
  70         MODE_APPEND     = 0x8,
  71 };
  72
  73 /**
  74  * smh_open() - Open a file on the host
  75  * @fname: The name of the file to open
  76  * @mode: The mode to use when opening the file
  77  *
  78  * Return: Either a file descriptor or a negative error on failure
  79  */
  80 long smh_open(const char *fname, enum smh_open_mode mode);
  81
  82 /**
  83  * smh_read() - Read data from a file
  84  * @fd: A file descriptor returned from smh_open()
  85  * @memp: Pointer to a buffer of memory of at least @len bytes
  86  * @len: The number of bytes to read
  87  *
  88  * Return:
  89  * * The number of bytes read on success, with 0 indicating %EOF
  90  * * A negative error on failure
  91  */
  92 long smh_read(long fd, void *memp, size_t len);
  93
  94 /**
  95  * smh_write() - Write data to a file
  96  * @fd: A file descriptor returned from smh_open()
  97  * @memp: Pointer to a buffer of memory of at least @len bytes
  98  * @len: The number of bytes to read
  99  * @written: Pointer which will be updated with the actual bytes written
 100  *
 101  * Return: 0 on success or negative error on failure
 102  */
 103 long smh_write(long fd, const void *memp, size_t len, ulong *written);
 104
 105 /**
 106  * smh_close() - Close an open file
 107  * @fd: A file descriptor returned from smh_open()
 108  *
 109  * Return: 0 on success or negative error on failure
 110  */
 111 long smh_close(long fd);
 112
 113 /**
 114  * smh_flen() - Get the length of a file
 115  * @fd: A file descriptor returned from smh_open()
 116  *
 117  * Return: The length of the file, in bytes, or a negative error on failure
 118  */
 119 long smh_flen(long fd);
 120
 121 /**
 122  * smh_seek() - Seek to a position in a file
 123  * @fd: A file descriptor returned from smh_open()
 124  * @pos: The offset (in bytes) to seek to
 125  *
 126  * Return: 0 on success or negative error on failure
 127  */
 128 long smh_seek(long fd, long pos);
 129
 130 /**
 131  * smh_getc() - Read a character from stdin
 132  *
 133  * Return: The character read, or a negative error on failure
 134  */
 135 int smh_getc(void);
 136
 137 /**
 138  * smh_putc() - Print a character on stdout
 139  * @ch: The character to print
 140  */
 141 void smh_putc(char ch);
 142
 143 /**
 144  * smh_write0() - Print a nul-terminated string on stdout
 145  * @s: The string to print
 146  */
 147 void smh_puts(const char *s);
 148
 149 #endif /* _SEMIHOSTING_H */