[patch] Add semihosting documentation for nios2 and m68k

[Sandra Loosemore <sandra at codesourcery dot com>]

I'd like to find a home in libgloss for some internal semihosting 
documentation I put together, that is more or less entirely derived from 
comments in the code.  Is this OK to commit?

-Sandra

commit 48b82c50392dd50293e172d1e9612a2be80b8afe
Author: Sandra Loosemore <sandra@codesourcery.com>
Date:   Tue Mar 12 10:23:00 2019 -0700

    Add semihosting documentation for nios2 and m68k.
    
    QEMU maintainers have asked for a specification of the nios2
    semihosting interface.  Since it's essentially a copy of the m68k
    implementation, this patch adds a document for that target as well.

diff --git a/libgloss/m68k/m68k-semi.txt b/libgloss/m68k/m68k-semi.txt
new file mode 100644
index 0000000..2a823d2
--- /dev/null
+++ b/libgloss/m68k/m68k-semi.txt
@@ -0,0 +1,200 @@
+m68k Semihosting Protocol
+-------------------------
+
+The instruction used to trigger a semihosting request depends on the
+m68k processor variant.  On ColdFire, "halt" is used; on other processors
+(which don't implement "halt"), "bkpt #0" may be used.
+
+Additionally, a special code sequence is used to distinguish
+semihosting requests from other uses of the instruction used to
+trigger it.  The semihosting instruction is immediately preceded by a
+"nop" aligned to a 4-byte boundary, and followed by an invalid sentinel
+instruction 0x4e7bf000 ("movec %sp,0").  The debug agent handling the
+semihosting request must adjust the program counter to skip over the
+sentinel instruction before continuing execution.
+
+Registers d0 and d1 are used to pass parameters to the semihosting call.
+d0 contains a request code.  d1 is typically a pointer to a 4-longword
+parameter block, except for the exit and simulator initialization operations
+where it is an immediate integer value.
+
+The result of the operation is returned in the first word of the
+parameter block.  The second word is used to return an errno value,
+encoded per the "Errno Values" section of the RSP documentation in the
+GDB User Manual.
+
+The supported d0 request codes are:
+
+#define HOSTED_EXIT  0
+
+  Terminate program execution; send a 'W' stop reply to GDB.
+
+  d1 contains the exit code, as an immediate integer rather than indirectly
+  in a parameter block.  This semihosting request isn't expected to return.
+
+#define HOSTED_INIT_SIM 1
+
+  Do simulator initialization, such as allocation of memory for the
+  stack and heap.  This semihosting request may be triggered from
+  startup code (crt0.S).
+
+  On entry to the semihosting request, d1 contains the default initial
+  stack pointer as an immediate value, typically the high end of
+  memory defined by the linker script.  If the simulator needs to
+  dynamically allocate memory for the stack, it should set both d1 and
+  sp (a7) to the new stack pointer value.
+
+#define HOSTED_OPEN 2
+
+  Open file; 'Fopen' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] pointer to filename
+  [1] filename length
+  [2] open flags, encoded per the GDB RSP documentation
+  [3] mode, encoded per the GDB RSP documentation
+
+  Return values in parameter block:
+  [0] file descriptor or -1 on error
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_CLOSE 3
+
+  Close file; 'Fclose' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] file descriptor
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_READ 4
+
+  Read from file; 'Fread' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] file descriptor
+  [1] pointer to buffer
+  [2] buffer size
+  
+  Return values in parameter block:
+  [0] number of bytes read
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_WRITE 5
+
+  Write to file; 'Fwrite' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] file descriptor
+  [1] pointer to buffer
+  [2] byte count
+  
+  Return values in parameter block:
+  [0] number of bytes written
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_LSEEK 6
+
+  File seek; 'Flseek' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] file descriptor
+  [1] high word of 64-bit offset
+  [2] low word of 64-bit offset
+  [3] seek flag, encoded per the GDB RSP documentation
+
+  Return values in parameter block:
+  [0] high word of 64-bit result
+  [1] low word of 64-bit result
+  [2] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_RENAME 7
+
+  File rename; 'Frename' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] oldname pointer
+  [1] oldname length
+  [2] newname pointer
+  [3] newname length
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_UNLINK 8
+
+  File unlink/delete; 'Funlink' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] filename pointer
+  [1] filename length
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_STAT 9
+
+  File information; 'Fstat' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] filename pointer
+  [1] filename length
+  [2] pointer to stat buf, using the structure definition in the GDB RSP
+      documentation 
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_FSTAT 10
+
+  File information; 'Ffstat' GDB fileio request.
+  
+  d1 points to a parameter block containing:
+  [0] file descriptor
+  [1] pointer to stat buf, using the structure definition in the GDB RSP
+      documentation 
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_GETTIMEOFDAY 11
+
+  Get current time; 'Fgettimeofday' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] timeval pointer, using the structure definition in the GDB RSP
+      documentation
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_ISATTY 12
+
+ Return true if the file descriptor is the GDB console; 'Fisatty' GDB fileio
+ request.
+
+  d1 points to a parameter block containing:
+  [0] file descriptor
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_SYSTEM 13
+
+  System call; 'Fsystem' GDB fileio request.
+
+  d1 points to a parameter block containing:
+  [0] command pointer
+  [1] command length
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
diff --git a/libgloss/nios2/nios2-semi.txt b/libgloss/nios2/nios2-semi.txt
new file mode 100644
index 0000000..f63190c
--- /dev/null
+++ b/libgloss/nios2/nios2-semi.txt
@@ -0,0 +1,183 @@
+Nios II Semihosting Protocol
+----------------------------
+
+The runtime (libgloss) indicates a semihosting request to the debug
+agent by issuing a "break 1" instruction.  r4 and r5 are used to pass
+parameters per the normal C ABI on nios2.
+
+r4 contains a request code.  r5 is typically a pointer to a 4-word
+parameter block, except for the exit operation where it is an
+immediate integer value.
+
+The result of the operation is returned in the first word of the
+parameter block.  The second word is used to return an errno value,
+encoded per the "Errno Values" section of the RSP documentation in the
+GDB User Manual.
+
+The supported r4 request codes are:
+
+#define HOSTED_EXIT  0
+
+  Terminate program execution; send a 'W' stop reply to GDB.
+
+  r5 contains the exit code, as an immediate integer rather than indirectly
+  in a parameter block.  This semihosting request isn't expected to return.
+
+#define HOSTED_INIT_SIM 1
+
+  Reserved/unimplemented.
+
+#define HOSTED_OPEN 2
+
+  Open file; 'Fopen' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] pointer to filename
+  [1] filename length
+  [2] open flags, encoded per the GDB RSP documentation
+  [3] mode, encoded per the GDB RSP documentation
+
+  Return values in parameter block:
+  [0] file descriptor or -1 on error
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_CLOSE 3
+
+  Close file; 'Fclose' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] file descriptor
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_READ 4
+
+  Read from file; 'Fread' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] file descriptor
+  [1] pointer to buffer
+  [2] buffer size
+  
+  Return values in parameter block:
+  [0] number of bytes read
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_WRITE 5
+
+  Write to file; 'Fwrite' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] file descriptor
+  [1] pointer to buffer
+  [2] byte count
+  
+  Return values in parameter block:
+  [0] number of bytes written
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_LSEEK 6
+
+  File seek; 'Flseek' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] file descriptor
+  [1] high word of 64-bit offset
+  [2] low word of 64-bit offset
+  [3] seek flag, encoded per the GDB RSP documentation
+
+  Return values in parameter block:
+  [0] high word of 64-bit result
+  [1] low word of 64-bit result
+  [2] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_RENAME 7
+
+  File rename; 'Frename' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] oldname pointer
+  [1] oldname length
+  [2] newname pointer
+  [3] newname length
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_UNLINK 8
+
+  File unlink/delete; 'Funlink' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] filename pointer
+  [1] filename length
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_STAT 9
+
+  File information; 'Fstat' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] filename pointer
+  [1] filename length
+  [2] pointer to stat buf, using the structure definition in the GDB RSP
+      documentation 
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_FSTAT 10
+
+  File information; 'Ffstat' GDB fileio request.
+  
+  r5 points to a parameter block containing:
+  [0] file descriptor
+  [1] pointer to stat buf, using the structure definition in the GDB RSP
+      documentation 
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_GETTIMEOFDAY 11
+
+  Get current time; 'Fgettimeofday' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] timeval pointer, using the structure definition in the GDB RSP
+      documentation
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_ISATTY 12
+
+ Return true if the file descriptor is the GDB console; 'Fisatty' GDB fileio
+ request.
+
+  r5 points to a parameter block containing:
+  [0] file descriptor
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation
+
+#define HOSTED_SYSTEM 13
+
+  System call; 'Fsystem' GDB fileio request.
+
+  r5 points to a parameter block containing:
+  [0] command pointer
+  [1] command length
+
+  Return values in parameter block:
+  [0] return status
+  [1] errno, encoded per the GDB RSP documentation