commit 48b82c50392dd50293e172d1e9612a2be80b8afe Author: Sandra Loosemore 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