assembler man pages ?

assembler man pages ?

[Mike Frysinger]

i'm wondering if a set of man pages exist for assembly instructions akin to 
the man-pages package for the C library ...

ive looked through the binutils info/texi files and they cover a lot of 
binutils-related stuff, but nothing in terms of a language reference ...

for example, say i wanted quick info on the 'jne' instruction, i would do `man 
jne` and get back a reference page similar to `man 2 close`
-mike

Re: assembler man pages ?

[DJ Delorie]

> for example, say i wanted quick info on the 'jne' instruction, i
> would do `man jne` and get back a reference page similar to `man 2
> close`

Binutils supports a *lot* of different chips.  Which one are you
referring to?  Do you *really* think it's worth our time to reproduce
a lot of documentation that the chip manufacturers already publish?
If you want to know what the JNE instruction does, find the chip's
programming manual and figure it out.  For the M32C/80, for example,
e32c80sm.pdf documents JNE as "jump on condition, not equal" on page
92.

Re: assembler man pages ?

[Eric Christopher]

On Sep 1, 2005, at 6:29 PM, Mike Frysinger wrote:

> i'm wondering if a set of man pages exist for assembly instructions  
> akin to
> the man-pages package for the C library ...
>
> ive looked through the binutils info/texi files and they cover a  
> lot of
> binutils-related stuff, but nothing in terms of a language  
> reference ...
>
> for example, say i wanted quick info on the 'jne' instruction, i  
> would do `man
> jne` and get back a reference page similar to `man 2 close`

Nope. For this it's best to use the processor manual from the vendor.

-eric

Re: assembler man pages ?

[Doug Evans]

Eric Christopher writes:
 > 
 > On Sep 1, 2005, at 6:29 PM, Mike Frysinger wrote:
 > 
 > > i'm wondering if a set of man pages exist for assembly instructions  
 > > akin to
 > > the man-pages package for the C library ...
 > >
 > > ive looked through the binutils info/texi files and they cover a  
 > > lot of
 > > binutils-related stuff, but nothing in terms of a language  
 > > reference ...
 > >
 > > for example, say i wanted quick info on the 'jne' instruction, i  
 > > would do `man
 > > jne` and get back a reference page similar to `man 2 close`
 > 
 > Nope. For this it's best to use the processor manual from the vendor.

I agree the best choice is the vendor's manual.
For cgen ports there is the cgen-generated html manual though.
Kinda handy sometimes (well, I like it anyway :-)).

One could certainly write a generator for man pages if one wanted to.
And was suffering from insomnia!

Re: assembler man pages ?

[Mike Frysinger]

On Thursday 01 September 2005 09:40 pm, DJ Delorie wrote:
> > for example, say i wanted quick info on the 'jne' instruction, i
> > would do `man jne` and get back a reference page similar to `man 2
> > close`
>
> Binutils supports a *lot* of different chips.  Which one are you
> referring to?  Do you *really* think it's worth our time to reproduce
> a lot of documentation that the chip manufacturers already publish?
> If you want to know what the JNE instruction does, find the chip's
> programming manual and figure it out.  For the M32C/80, for example,
> e32c80sm.pdf documents JNE as "jump on condition, not equal" on page
> 92.

i never said 'hey, write me some documentation you lazy bums', so settle 
down :P ... i was merely asking if anything *already existed*

i have the reference books for the architectures i'm interested in, it's just 
a hell of a lot easier to run `man blah` than flip through a book
-mike

Re: assembler man pages ?

[DJ Delorie]

> i have the reference books for the architectures i'm interested in,
> it's just a hell of a lot easier to run `man blah` than flip through
> a book

The M32C "books" are searchable indexed PDFs :-)

Re: assembler man pages ?

[Mike Frysinger]

On Thursday 01 September 2005 10:12 pm, DJ Delorie wrote:
> > i have the reference books for the architectures i'm interested in,
> > it's just a hell of a lot easier to run `man blah` than flip through
> > a book
>
> The M32C "books" are searchable indexed PDFs :-)

i'll keep that in mind if i ever work on M32C ;)

thanks all for the quick feedback
-mike

Re: assembler man pages ?

[Erik Christiansen]

On Thu, Sep 01, 2005 at 10:14:27PM -0400, Mike Frysinger wrote:
> On Thursday 01 September 2005 10:12 pm, DJ Delorie wrote:
> > > i have the reference books for the architectures i'm interested in,
> > > it's just a hell of a lot easier to run `man blah` than flip through
> > > a book
> >
> > The M32C "books" are searchable indexed PDFs :-)
> 
> i'll keep that in mind if i ever work on M32C ;)

Mike,

The point may have been a little broader than that. ;-)

Flitting from Atmel AVR to PowerPC to NEC V850, I also use PDFs for two
of the three. Maybe if I dug a bit, I'd find 'em for PowerPC as well.

Incidentally, it's a delight to be able to use binutils for them all.
:-))

Erik

Re: assembler man pages ?

[Jim Blandy]

Mike Frysinger <vapier@gentoo.org> writes:
> for example, say i wanted quick info on the 'jne' instruction, i would do `man 
> jne` and get back a reference page similar to `man 2 close`

You're right that something like this would be the nicest interface to
an assembly reference manual.  Even the indexed PDF's (what I use,
like DJ) are a pain compared to the beauty of something like `C-h f'
when writing Emacs Lisp code in Emacs (the documentation for the
function the cursor is sitting on a call to pops up).

But it's a question of pragmatics: what's the interface, what's the
structure, and how do you get the information into it?  You'd pretty
much need to have chip vendors cooperating with you, because nobody's
going to retype all that.  It's boring enough doing the opcodes
library and the GCC machine description.

Re: assembler man pages ?

[Mike Frysinger]

On Tuesday 06 September 2005 02:22 pm, Jim Blandy wrote:
> Mike Frysinger <vapier@gentoo.org> writes:
> > for example, say i wanted quick info on the 'jne' instruction, i would do
> > `man jne` and get back a reference page similar to `man 2 close`
>
> But it's a question of pragmatics: what's the interface, what's the
> structure, and how do you get the information into it?  You'd pretty
> much need to have chip vendors cooperating with you, because nobody's
> going to retype all that.  It's boring enough doing the opcodes
> library and the GCC machine description.

of the different ways i imagined tackling the issue, here's the two i think 
are most feasible:
- integrate with binutils documentation/source code in an effort to keep down 
duplicated information in multiple places ... maybe something like using 
doxygen to turn comments placed around opcode definitions in the binutils 
source into manpages, or adding on to the current texinfo sources ...
- define a simple xml format and use like xsl to translate into 
man/html/whatever and startup a sourceforge project to maintain it ... the 
benefit here would be a much lower learning curve for random people to 
contribute

the former i would need help with since ive never screwed around with texinfo 
source before not to mention i'd need to get the blessing of the larger 
binutils community to make it happen :)

either approach would be a 'document as i go' because as you rightly point 
out, this kind of project is really really boring to tackle beyond a few 
opcodes at a time
-mike

Re: assembler man pages ?

[Jim Blandy]

Mike Frysinger <vapier@gentoo.org> writes:
> On Tuesday 06 September 2005 02:22 pm, Jim Blandy wrote:
>> Mike Frysinger <vapier@gentoo.org> writes:
>> > for example, say i wanted quick info on the 'jne' instruction, i would do
>> > `man jne` and get back a reference page similar to `man 2 close`
>>
>> But it's a question of pragmatics: what's the interface, what's the
>> structure, and how do you get the information into it?  You'd pretty
>> much need to have chip vendors cooperating with you, because nobody's
>> going to retype all that.  It's boring enough doing the opcodes
>> library and the GCC machine description.
>
> of the different ways i imagined tackling the issue, here's the two i think 
> are most feasible:
> - integrate with binutils documentation/source code in an effort to keep down 
> duplicated information in multiple places ... maybe something like using 
> doxygen to turn comments placed around opcode definitions in the binutils 
> source into manpages, or adding on to the current texinfo sources ...
> - define a simple xml format and use like xsl to translate into 
> man/html/whatever and startup a sourceforge project to maintain it ... the 
> benefit here would be a much lower learning curve for random people to 
> contribute

For automated generation of pages, I'd expect the CGEN-generated stuff
to be the most promising.  CGEN does, after all, have the semantics,
syntax, and encodings in one place.

But that's not going to get you what I'd consider real documentation
--- a coherent, English explanation of what the instructions do.  And
the semantics are often going to be macro-generated RTL...  Not
exactly legible.

The presence of the indexed PDF's sort of places a lower bound on the
quality you'd have to acheive to make the effort worthwhile.  If you
can't do better than what the manufacturer provides us for free, it's
not worth it; better to spend the time fixing bugs.

Speaking only for myself and not for binutils (obviously), this is
a case where I'd need someone else to show it was a winning idea
before I contributed time.  (That's not an offer; I'm just explaining
how I, at least, think about these things.)

Re: assembler man pages ?

[Ian Lance Taylor]

Mike Frysinger <vapier@gentoo.org> writes:

> - integrate with binutils documentation/source code in an effort to keep down 
> duplicated information in multiple places ... maybe something like using 
> doxygen to turn comments placed around opcode definitions in the binutils 
> source into manpages, or adding on to the current texinfo sources ...

There are in general no comments describing instructions in the
binutils sources, and I don't think it would be appropriate to add
them.  (I make an exception for cgen, where they may be appropriate,
but most targets do not use cgen.)

> - define a simple xml format and use like xsl to translate into 
> man/html/whatever and startup a sourceforge project to maintain it ... the 
> benefit here would be a much lower learning curve for random people to 
> contribute

If you want to do this, my first instinct would be to just use
texinfo.  texinfo can already be converted into man pages, HTML, and
printed documentation.  This is already done in the binutils sources
themselves.

But this is a huge job with, frankly, a relatively minimal payoff.  I
wouldn't be inclined to work on it myself.

Ian

Re: assembler man pages ?

[David Daney]

Ian Lance Taylor wrote:
> 
> But this is a huge job with, frankly, a relatively minimal payoff.  I
> wouldn't be inclined to work on it myself.

I tend to agree.  In addition to being a huge job, it seems to me that 
it has the potential to introduce errors into the material.  This would 
leave us in the position of having to go back to the manufacturer's 
manuals for the definitive answer to any questions we would have.  So 
you would have done a lot of work but not eliminated the need for the 
manufacturer's manuals.  Or worse one might write buggy code based on 
buggy on-line documentation and then really wonder what was happening as 
the chip was not behaving as the on-line documentation said it should.

David Daney