[PATCH: doco] gdbint.texinfo

[PATCH: doco] gdbint.texinfo

[Nick Roberts]

I still get confused by target and architecture (sometimes, they seem to be
used interchangeably) but how about adding a menu and creating nodes as below?

Also 

`gdb/ARCH-tdep.c'
`gdb/ARCH-tdep.h'
     This often exists to describe the basic layout of the target
     machine's processor chip (registers, stack, etc.).  If used, it is
     included by `TTT-tdep.h'.  It can be shared among many targets
     that use the same processor.

`gdb/config/ARCH/tm-ARCH.h'
     This often exists to describe the basic layout of the target
     machine's processor chip (registers, stack, etc.).  If used, it is
     included by `tm-TTT.h'.  It can be shared among many targets that
     use the same processor.

have the same description.  I presume the first is wrong.

-- 
Nick                                           http://www.inet.net.nz/~nickrob


2007-06-24  Nick Roberts  <nickrob@snap.net.nz>

	* gdbint.texinfo (Target Architecture Definition): Break sections
	into nodes and add a menu.


*** gdbint.texinfo	09 May 2007 19:48:39 +1200	1.261
--- gdbint.texinfo	24 Jun 2007 12:23:17 +1200	
*************** The target architecture object is implem
*** 2571,2576 ****
--- 2571,2593 ----
  @code{struct gdbarch *}.  The structure, and its methods, are generated
  using the Bourne shell script @file{gdbarch.sh}.
  
+ @menu
+ * Operating System ABI Variant Handling::
+ * Initializing a New Architecture::
+ * Registers and Memory::
+ * Pointers Are Not Always Addresses::
+ * Address Classes::
+ * Raw and Virtual Register Representations::
+ * Using Different Register and Memory Data Representations::
+ * Frame Interpretation::
+ * Inferior Call Setup::
+ * Compiler Characteristics::
+ * Target Conditionals::
+ * Adding a New Target::
+ * Converting an existing Target Architecture to Multi-arch::
+ @end menu
+ 
+ @node Operating System ABI Variant Handling
  @section Operating System ABI Variant Handling
  @cindex OS ABI variants
  
*************** from the note.  This function should be 
*** 2730,2735 ****
--- 2747,2753 ----
  @code{bfd_map_over_sections}.
  @end deftypefun
  
+ @node Initializing a New Architecture
  @section Initializing a New Architecture
  
  Each @code{gdbarch} is associated with a single @sc{bfd} architecture,
*************** However, @value{GDBN} now fills in @var{
*** 2765,2770 ****
--- 2783,2789 ----
  so new @code{gdbarch} initialization functions should not take
  defaults from @var{arches}.
  
+ @node Registers and Memory
  @section Registers and Memory
  
  @value{GDBN}'s model of the target machine is rather simple.
*************** and to reflect that in the @code{REGISTE
*** 2779,2784 ****
--- 2798,2804 ----
  
  @value{GDBN} can handle big-endian, little-endian, and bi-endian architectures.
  
+ @node Pointers Are Not Always Addresses
  @section Pointers Are Not Always Addresses
  @cindex pointer representation
  @cindex address representation
*************** This function may safely assume that @va
*** 2910,2915 ****
--- 2930,2936 ----
  C@t{++} reference type.
  @end deftypefn
  
+ @node Address Classes
  @section Address Classes
  @cindex address classes
  @cindex DW_AT_byte_size
*************** type = int * @@short
*** 2996,3001 ****
--- 3017,3023 ----
  @end smallexample
  
  
+ @node Raw and Virtual Register Representations
  @section Raw and Virtual Register Representations
  @cindex raw register representation
  @cindex virtual register representation
*************** their @var{reg} and @var{type} arguments
*** 3104,3109 ****
--- 3126,3132 ----
  @end deftypefn
  
  
+ @node Using Different Register and Memory Data Representations
  @section Using Different Register and Memory Data Representations
  @cindex register representation
  @cindex memory representation
*************** the @code{CONVERT_REGISTER_P} macro retu
*** 3182,3194 ****
  See @file{mips-tdep.c}.  It does not do what you want.
  @end deftypefn
  
! 
  @section Frame Interpretation
  
  @section Inferior Call Setup
  
  @section Compiler Characteristics
  
  @section Target Conditionals
  
  This section describes the macros that you can use to define the target
--- 3205,3220 ----
  See @file{mips-tdep.c}.  It does not do what you want.
  @end deftypefn
  
! @node Frame Interpretation
  @section Frame Interpretation
  
+ @node Inferior Call Setup
  @section Inferior Call Setup
  
+ @node Compiler Characteristics
  @section Compiler Characteristics
  
+ @node Target Conditionals
  @section Target Conditionals
  
  This section describes the macros that you can use to define the target
*************** allocate some memory in the inferior. Th
*** 4255,4260 ****
--- 4281,4287 ----
  
  @end ftable
  
+ @node Adding a New Target
  @section Adding a New Target
  
  @cindex adding a target
*************** that just @code{#include}s @file{tm-@var
*** 4313,4318 ****
--- 4340,4346 ----
  @file{config/tm-@var{os}.h}.
  
  
+ @node Converting an existing Target Architecture to Multi-arch
  @section Converting an existing Target Architecture to Multi-arch
  @cindex converting targets to multi-arch
  

Re: [PATCH: doco] gdbint.texinfo

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Sun, 24 Jun 2007 18:32:31 +1200
> 
> 
> I still get confused by target and architecture (sometimes, they seem to be
> used interchangeably) but how about adding a menu and creating nodes as below?

It's okay, but please make the long node names shorter.  Long node
names look badly in an Info reader

> `gdb/ARCH-tdep.c'
> `gdb/ARCH-tdep.h'
>      This often exists to describe the basic layout of the target
>      machine's processor chip (registers, stack, etc.).  If used, it is
>      included by `TTT-tdep.h'.  It can be shared among many targets
>      that use the same processor.
> 
> `gdb/config/ARCH/tm-ARCH.h'
>      This often exists to describe the basic layout of the target
>      machine's processor chip (registers, stack, etc.).  If used, it is
>      included by `tm-TTT.h'.  It can be shared among many targets that
>      use the same processor.
> 
> have the same description.  I presume the first is wrong.

Yes, it's wrong.  Thanks for catching that.

Re: [PATCH: doco] gdbint.texinfo

[Nick Roberts]

Eli Zaretskii writes:
 > > From: Nick Roberts <nickrob@snap.net.nz>
 > > Date: Sun, 24 Jun 2007 18:32:31 +1200
 > > 
 > > 
 > > I still get confused by target and architecture (sometimes, they seem to be
 > > used interchangeably) but how about adding a menu and creating nodes as below?
 > 
 > It's okay, but please make the long node names shorter.  Long node
 > names look badly in an Info reader

I'm reluctant to make my own names as I only have a shallow understanding.
How about if I use the cindex names as node names?

+ @menu
+ * OS ABI Variant Handling::
+ * Initializing a New Architecture::
+ * Registers and Memory::
+ * Pointers Are Not Always Addresses::
+ * Address Classes::
+ * Raw and Virtual Register Representations::
+ * Register and Memory Data Representations::
+ * Frame Interpretation::
+ * Inferior Call Setup::
+ * Compiler Characteristics::
+ * Target Conditionals::
+ * Adding a New Target::
+ * Converting Targets to Multi-arch::
+ @end menu

That's shorter but I don't know if it's short enough.


-- 
Nick                                           http://www.inet.net.nz/~nickrob

Re: [PATCH: doco] gdbint.texinfo

[Eli Zaretskii]

> From: Nick Roberts <nickrob@snap.net.nz>
> Date: Mon, 25 Jun 2007 09:55:08 +1200
> Cc: gdb-patches@sources.redhat.com
> 
> I'm reluctant to make my own names as I only have a shallow understanding.
> How about if I use the cindex names as node names?

That's close, but I'd like to shorten some more:

> + * Initializing a New Architecture::

Initialize New Architecture

> + * Pointers Are Not Always Addresses::

Pointers and Addresses

> + * Raw and Virtual Register Representations::

Raw and Virtual Registers

> + * Register and Memory Data Representations::

Register and Memory Data

Thanks.

Re: [PATCH: doco] gdbint.texinfo

[Daniel Jacobowitz]

On Sun, Jun 24, 2007 at 06:32:31PM +1200, Nick Roberts wrote:
> Also 
> 
> `gdb/ARCH-tdep.c'
> `gdb/ARCH-tdep.h'
>      This often exists to describe the basic layout of the target
>      machine's processor chip (registers, stack, etc.).  If used, it is
>      included by `TTT-tdep.h'.  It can be shared among many targets
>      that use the same processor.
> 
> `gdb/config/ARCH/tm-ARCH.h'
>      This often exists to describe the basic layout of the target
>      machine's processor chip (registers, stack, etc.).  If used, it is
>      included by `tm-TTT.h'.  It can be shared among many targets that
>      use the same processor.
> 
> have the same description.  I presume the first is wrong.

Yes, the description for the first is somewhat wrong.  The description
for the second is a bit stale - nowadays it exists for local hacks,
and we're phasing it out pretty fast.  After Ulrich finished his
cleanups, there are only nine left!

-- 
Daniel Jacobowitz
CodeSourcery

Re: [PATCH: doco] gdbint.texinfo

[Daniel Jacobowitz]

On Sun, Jun 24, 2007 at 06:32:31PM +1200, Nick Roberts wrote:
> Also 
> 
> `gdb/ARCH-tdep.c'
> `gdb/ARCH-tdep.h'
>      This often exists to describe the basic layout of the target
>      machine's processor chip (registers, stack, etc.).  If used, it is
>      included by `TTT-tdep.h'.  It can be shared among many targets
>      that use the same processor.
> 
> `gdb/config/ARCH/tm-ARCH.h'
>      This often exists to describe the basic layout of the target
>      machine's processor chip (registers, stack, etc.).  If used, it is
>      included by `tm-TTT.h'.  It can be shared among many targets that
>      use the same processor.
> 
> have the same description.  I presume the first is wrong.

Yes, the description for the first is somewhat wrong.  The description
for the second is a bit stale - nowadays it exists for local hacks,
and we're phasing it out pretty fast.  After Ulrich finished his
cleanups, there are only nine left!

-- 
Daniel Jacobowitz
CodeSourcery