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