minor doc fix

minor doc fix

[Bart Veer]

Current docs for the remote protocol file I/O extension state that a
struct timeval is 8 bytes. It is actually 12, a 4-byte time_t tv_sec
and an 8-byte long tv_usec. It is not clear why tv_usec was made a
long rather than an int, but that is what has been implemented in
remote_fileio_to_fio_timeval() and hence what current server
implementations expect.

Bart

2008-07-30  Bart Veer  <bartv@ecoscentric.com>

	* gdb.texinfo: gettimeofday() involves a 12-byte transfer, not 8
	bytes.

Index: gdb.texinfo
===================================================================
RCS file: /cvs/src/src/gdb/doc/gdb.texinfo,v
retrieving revision 1.509
diff -u -p -r1.509 gdb.texinfo
--- gdb.texinfo	18 Jul 2008 20:55:33 -0000	1.509
+++ gdb.texinfo	30 Jul 2008 14:55:06 -0000
@@ -26636,7 +26636,7 @@ struct timeval @{
 
 The integral datatypes conform to the definitions given in the
 appropriate section (see @ref{Integral Datatypes}, for details) so this
-structure is of size 8 bytes.
+structure is of size 12 bytes.
 
 @node Constants
 @subsection Constants
	

Re: minor doc fix

[Eli Zaretskii]

> Date: Wed, 30 Jul 2008 16:54:43 +0100
> From: Bart Veer <bartv@ecoscentric.com>
> 
> Current docs for the remote protocol file I/O extension state that a
> struct timeval is 8 bytes. It is actually 12, a 4-byte time_t tv_sec
> and an 8-byte long tv_usec.

You are on a 64-bit machine, right?  On a 32-bit machine, a long takes
4 bytes, like an int.

So if you want to get this text right, you will need to rewrite it
such that it is correct on both architectures.

Thanks.

Re: minor doc fix

[Bart Veer]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

    >> Date: Wed, 30 Jul 2008 16:54:43 +0100
    >> From: Bart Veer <bartv@ecoscentric.com>
    >> 
    >> Current docs for the remote protocol file I/O extension state that a
    >> struct timeval is 8 bytes. It is actually 12, a 4-byte time_t tv_sec
    >> and an 8-byte long tv_usec.

    Eli> You are on a 64-bit machine, right? On a 32-bit machine, a
    Eli> long takes 4 bytes, like an int.

    Eli> So if you want to get this text right, you will need to
    Eli> rewrite it such that it is correct on both architectures.

The text is not talking about host-side or target-side data
structures. It is describing a protocol, what gets transferred between
host and target for a gettimeofday request, which happens to be 12
bytes and not 8.

Bart

Re: minor doc fix

[Eli Zaretskii]

> Date: Wed, 30 Jul 2008 19:17:02 +0100
> From: Bart Veer <bartv@ecoscentric.com>
> CC: gdb-patches@sourceware.org
> 
> The text is not talking about host-side or target-side data
> structures. It is describing a protocol, what gets transferred between
> host and target for a gettimeofday request, which happens to be 12
> bytes and not 8.

Sorry, you lost me.  Perhaps I'm confused, but `long' takes 8 bytes
only on 64-bit Unix machines.  Otherwise it's 4 bytes.  What am I
missing?

Re: minor doc fix

[Daniel Jacobowitz]

On Wed, Jul 30, 2008 at 09:34:07PM +0300, Eli Zaretskii wrote:
> > Date: Wed, 30 Jul 2008 19:17:02 +0100
> > From: Bart Veer <bartv@ecoscentric.com>
> > CC: gdb-patches@sourceware.org
> > 
> > The text is not talking about host-side or target-side data
> > structures. It is describing a protocol, what gets transferred between
> > host and target for a gettimeofday request, which happens to be 12
> > bytes and not 8.
> 
> Sorry, you lost me.  Perhaps I'm confused, but `long' takes 8 bytes
> only on 64-bit Unix machines.  Otherwise it's 4 bytes.  What am I
> missing?

The answer's even in the manual! :-)

In Protocol-specific Representation of Datatypes, see Integral
Datatypes:

   `long' and `unsigned long' are implemented as 64 bit types.

Then in struct timeval:

     struct timeval {
         time_t tv_sec;  /* second */
         long   tv_usec; /* microsecond */
     };

     The integral datatypes conform to the definitions given in the
  appropriate section (see *note Integral Datatypes::, for details) so
  this structure is of size 8 bytes.

-- 
Daniel Jacobowitz
CodeSourcery

Re: minor doc fix

[Eli Zaretskii]

> Date: Wed, 30 Jul 2008 14:49:02 -0400
> From: Daniel Jacobowitz <drow@false.org>
> Cc: Bart Veer <bartv@ecoscentric.com>, gdb-patches@sourceware.org
> 
>    `long' and `unsigned long' are implemented as 64 bit types.

How do you mean ``implemented''?  These are primitive C data types, so
the compiler implements them and we cannot change that.

> Then in struct timeval:
> 
>      struct timeval {
>          time_t tv_sec;  /* second */
>          long   tv_usec; /* microsecond */
>      };

Is this a declaration that is compiled?  If so, it uses the primitive
data types defined by the compiler.

Again, what am I missing here?

Re: minor doc fix

[Daniel Jacobowitz]

On Wed, Jul 30, 2008 at 10:07:37PM +0300, Eli Zaretskii wrote:
> Again, what am I missing here?

None of this is compiled by a C compiler.  These are descriptions of a
protocol used to communicate between the debugger and the remote
system, to simulate file I/O on systems which lack it.

There's a bit about this in "File-I/O Overview".

-- 
Daniel Jacobowitz
CodeSourcery

Re: minor doc fix

[Bart Veer]

>>>>> "Eli" == Eli Zaretskii <eliz@gnu.org> writes:

    >> Date: Wed, 30 Jul 2008 19:17:02 +0100
    >> From: Bart Veer <bartv@ecoscentric.com>
    >> CC: gdb-patches@sourceware.org
    >> 
    >> The text is not talking about host-side or target-side data
    >> structures. It is describing a protocol, what gets transferred
    >> between host and target for a gettimeofday request, which
    >> happens to be 12 bytes and not 8.

    Eli> Sorry, you lost me. Perhaps I'm confused, but `long' takes 8
    Eli> bytes only on 64-bit Unix machines. Otherwise it's 4 bytes.
    Eli> What am I missing?

That we are talking about a communication protocol which is
independent of any given architecture.

On an embedded target, the target-side stub code can send a packet
Fgettimeofday,<buf1>,<buf2> to the host-side gdb. This is part of the
remote protocol as documented in appendix D, "GDB Remote Serial
Protocol" of the gdb info pages. Communication can happen over a
serial line, a network socket, whatever. The Fgettimeofday packet is
part of the File-I/O Remote Protocol Extension documented in that
appendix.

<buf1> is a pointer to a target-side buffer where gdb should store the
desired information. The protocol specification says that the first 4
bytes of that buffer will be filled with the tv_sec value in
big-endian format, and the next 8 bytes of that buffer will be filled
with the tv_usec value, again in big-endian format. When gdb resumes
the target, target-side code is responsible for converting the
contents of that buffer into appropriate data structures. That may
involve swapping the endianness, truncating the 8 bytes of tv_usec
data to the 4 bytes that are actually required, whatever.

The current documentation states that that target-side buffer only
needs to be 8 bytes, not 12, so anybody implementing target-side code
may reserve insufficient memory. Result: confusion and memory
corruption.

Bart