Add semihosting documentation for nios2 and m68k

Message ID 52198095-2ca8-62fa-4835-baefe945dc71@codesourcery.com
State New
Headers show
Series
  • Add semihosting documentation for nios2 and m68k
Related show

Commit Message

Sandra Loosemore March 12, 2019, 5:32 p.m.
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

Comments

Jeff Johnston March 12, 2019, 11:15 p.m. | #1
Hi Sandra,

I didn't see any docs for the HOSTED fields in the comments of the libgloss
code.  Can you confirm that you didn't grab documentation from elsewhere
that has copyright/license issues?  If the source of the docs was covered
by the current code licenses for m68k and nios2 they can/should probably be
used in the .txt files since the licenses allow for copying of
documentation as long as the license is present.

-- Jeff J.

On Tue, Mar 12, 2019 at 1:33 PM Sandra Loosemore <sandra@codesourcery.com>
wrote:

> 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

>
Sandra Loosemore March 13, 2019, 12:41 a.m. | #2
On 3/12/19 5:15 PM, Jeff Johnston wrote:
> Hi Sandra,

> 

> I didn't see any docs for the HOSTED fields in the comments of the 

> libgloss code.  Can you confirm that you didn't grab documentation from 

> elsewhere that has copyright/license issues?  If the source of the docs 

> was covered by the current code licenses for m68k and nios2 they 

> can/should probably be used in the .txt files since the licenses allow 

> for copying of documentation as long as the license is present.


Well, I read the libgloss code too, not just the comments.  Also 
double-checked against the QEMU implementations, the GDB manual, and 
some old internal mailing list discussion.  All of the nios2 and m68k 
semihosting code (both libgloss and QEMU) was originally written by me 
and other CodeSourcery folks, so I think we can license it under any 
terms we want.

Do these documentation files need copyright notices, too?  :-S  That 
didn't occur to me when I wrote them up.

-Sandra
Jeff Johnston March 13, 2019, 2:53 p.m. | #3
Hi Sandra,

If documentation is taken verbatim from comments in code, it requires the
copyright license(s) that the code was under.  If on the other hand
you wrote the documentation yourself by looking at/knowing how the code
works, it is yours to license as you want.  If you are taking
comments verbatim from code and it is written by you and other folks, you
can't just license under "any" terms because that doesn't imply permission
of the other
folks unless it uses the license that everyone already agreed upon (which
can be nothing if no license governs the code).

I hope that clarifies.  If a license is required, you can add a separate
license file for each doc file if you don't want the license to be present
in the documentation.

-- Jeff J.



On Tue, Mar 12, 2019 at 8:42 PM Sandra Loosemore <sandra@codesourcery.com>
wrote:

> On 3/12/19 5:15 PM, Jeff Johnston wrote:

> > Hi Sandra,

> >

> > I didn't see any docs for the HOSTED fields in the comments of the

> > libgloss code.  Can you confirm that you didn't grab documentation from

> > elsewhere that has copyright/license issues?  If the source of the docs

> > was covered by the current code licenses for m68k and nios2 they

> > can/should probably be used in the .txt files since the licenses allow

> > for copying of documentation as long as the license is present.

>

> Well, I read the libgloss code too, not just the comments.  Also

> double-checked against the QEMU implementations, the GDB manual, and

> some old internal mailing list discussion.  All of the nios2 and m68k

> semihosting code (both libgloss and QEMU) was originally written by me

> and other CodeSourcery folks, so I think we can license it under any

> terms we want.

>

> Do these documentation files need copyright notices, too?  :-S  That

> didn't occur to me when I wrote them up.

>

> -Sandra

>
Sandra Loosemore March 13, 2019, 3:06 p.m. | #4
On 3/13/19 8:53 AM, Jeff Johnston wrote:
> Hi Sandra,

> 

> If documentation is taken verbatim from comments in code, it requires 

> the copyright license(s) that the code was under.  If on the other hand

> you wrote the documentation yourself by looking at/knowing how the code 

> works, it is yours to license as you want.  If you are taking

> comments verbatim from code and it is written by you and other folks, 

> you can't just license under "any" terms because that doesn't imply 

> permission of the other

> folks unless it uses the license that everyone already agreed upon 

> (which can be nothing if no license governs the code).

> 

> I hope that clarifies.  If a license is required, you can add a separate 

> license file for each doc file if you don't want the license to be 

> present in the documentation.


Well, the listed copyright holder on the corresponding code files is 
CodeSourcery/Mentor Graphics, so presumably we still retain the right to 
do whatever we want with it, including cutting and pasting comments into 
a separate documentation file.

I can add the same copyright notice and license terms to the new 
documentation files.

-Sandra
Jeff Johnston March 13, 2019, 3:17 p.m. | #5
On Wed, Mar 13, 2019 at 11:07 AM Sandra Loosemore <sandra@codesourcery.com>
wrote:

> On 3/13/19 8:53 AM, Jeff Johnston wrote:

> > Hi Sandra,

> >

> > If documentation is taken verbatim from comments in code, it requires

> > the copyright license(s) that the code was under.  If on the other hand

> > you wrote the documentation yourself by looking at/knowing how the code

> > works, it is yours to license as you want.  If you are taking

> > comments verbatim from code and it is written by you and other folks,

> > you can't just license under "any" terms because that doesn't imply

> > permission of the other

> > folks unless it uses the license that everyone already agreed upon

> > (which can be nothing if no license governs the code).

> >

> > I hope that clarifies.  If a license is required, you can add a separate

> > license file for each doc file if you don't want the license to be

> > present in the documentation.

>

> Well, the listed copyright holder on the corresponding code files is

> CodeSourcery/Mentor Graphics, so presumably we still retain the right to

> do whatever we want with it, including cutting and pasting comments into

> a separate documentation file.

>

>

Yes.  You could have done so even if the copyright was some other company
as long as
their license allowed copying and you attributed them as asked for in their
license.  If the other
company didn't allow copying, you could have gotten around the issue by
writing docs from scratch in your own words.

I can add the same copyright notice and license terms to the new
> documentation files.

>

>

Yes, the license should be added.  I'll check it in when you update.

-Sandra
>
Sandra Loosemore March 14, 2019, 3:26 a.m. | #6
On 3/13/19 9:17 AM, Jeff Johnston wrote:
> 

> 

> On Wed, Mar 13, 2019 at 11:07 AM Sandra Loosemore 

> <sandra@codesourcery.com <mailto:sandra@codesourcery.com>> wrote:

> 

>     I can add the same copyright notice and license terms to the new

>     documentation files.

> 

> Yes, the license should be added.  I'll check it in when you update.


New patch attached.

-Sandra
commit 09bef5537ee2b8dfa136d772f07c031c9fdf9442
Author: Sandra Loosemore <sandra@codesourcery.com>
Date:   Wed Mar 13 20:22:16 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..50520c1
--- /dev/null
+++ b/libgloss/m68k/m68k-semi.txt
@@ -0,0 +1,214 @@
+Copyright (c) 2006 CodeSourcery Inc
+Copyright (c) 2019 Mentor Graphics
+
+The authors hereby grant permission to use, copy, modify, distribute,
+and license this software and its documentation for any purpose, provided
+that existing copyright notices are retained in all copies and that this
+notice is included verbatim in any distributions. No written agreement,
+license, or royalty fee is required for any of the authorized uses.
+Modifications to this software may be copyrighted by their authors
+and need not follow the licensing terms described here, provided that
+the new terms are clearly indicated on the first page of each file where
+they apply.
+
+
+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..ded3a09
--- /dev/null
+++ b/libgloss/nios2/nios2-semi.txt
@@ -0,0 +1,197 @@
+Copyright (c) 2006 CodeSourcery Inc
+Copyright (c) 2018, 2019 Mentor Graphics
+
+The authors hereby grant permission to use, copy, modify, distribute,
+and license this software and its documentation for any purpose, provided
+that existing copyright notices are retained in all copies and that this
+notice is included verbatim in any distributions. No written agreement,
+license, or royalty fee is required for any of the authorized uses.
+Modifications to this software may be copyrighted by their authors
+and need not follow the licensing terms described here, provided that
+the new terms are clearly indicated on the first page of each file where
+they apply.
+
+
+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
Jeff Johnston March 14, 2019, 5:59 p.m. | #7
Patch committed.

Thanks,

-- Jeff J.

On Wed, Mar 13, 2019 at 11:26 PM Sandra Loosemore <sandra@codesourcery.com>
wrote:

> On 3/13/19 9:17 AM, Jeff Johnston wrote:

> >

> >

> > On Wed, Mar 13, 2019 at 11:07 AM Sandra Loosemore

> > <sandra@codesourcery.com <mailto:sandra@codesourcery.com>> wrote:

> >

> >     I can add the same copyright notice and license terms to the new

> >     documentation files.

> >

> > Yes, the license should be added.  I'll check it in when you update.

>

> New patch attached.

>

> -Sandra

>

Patch

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