Adding asm examples

[Julio Merino]

Hello,

I would like to add some trivial, heavily-commented assembly code
examples to /usr/share/examples/asm/. The goal of these examples would
be to illustrate platform-specific stuff rather than teach the assembly
language itself (but this would be a side-effect anyway). For instance,
a "hello world" example would show how to craft an ELF file and how to
perform a couple of system calls according to the platform conventions.
There could be another example showing the C->ASM call protocol.

The reason I'm proposing this is because, out of pure curiosity, I've
started learning PowerPC assembly and such examples could come very
handy. (Books teach you the general assembly language but not how that
is put in practice in a specific platform/assembler... and 'gas' is
quite... special.) I found some sample code in the old wiki, but it
would be much more useful if it were in the tree.

These teeny-tiny examples would come with a Makefile ready for use and
some trivial tests to ensure that the sample code builds and runs on the
platforms that implement the specific tests.

Comments / objections?

Thanks!

[David Holland]

Post by Julio Merino
I would like to add some trivial, heavily-commented assembly code
examples to /usr/share/examples/asm/. The goal of these examples
would be to illustrate platform-specific stuff rather than teach
the assembly language itself (but this would be a side-effect
anyway). For instance, a "hello world" example would show how to
craft an ELF file and how to perform a couple of system calls
according to the platform conventions. There could be another
example showing the C->ASM call protocol.
The reason I'm proposing this is because, out of pure curiosity,
I've started learning PowerPC assembly and such examples could come
very handy. (Books teach you the general assembly language but not
how that is put in practice in a specific platform/assembler... and
'gas' is quite... special.) I found some sample code in the old
wiki, but it would be much more useful if it were in the tree.
These teeny-tiny examples would come with a Makefile ready for use
and some trivial tests to ensure that the sample code builds and
runs on the platforms that implement the specific tests.

Sounds like a good idea to me, provided you or someone you conscript
is willing to write and maintain them.

[David Holland]

Post by David Holland

Post by Julio Merino
I would like to add some trivial, heavily-commented assembly code
examples to /usr/share/examples/asm/. The goal of these examples
would be to illustrate platform-specific stuff rather than teach
the assembly language itself (but this would be a side-effect
anyway). For instance, a "hello world" example would show how to
craft an ELF file and how to perform a couple of system calls
according to the platform conventions. There could be another
example showing the C->ASM call protocol.
The reason I'm proposing this is because, out of pure curiosity,
I've started learning PowerPC assembly and such examples could come
very handy. (Books teach you the general assembly language but not
how that is put in practice in a specific platform/assembler... and
'gas' is quite... special.) I found some sample code in the old
wiki, but it would be much more useful if it were in the tree.
These teeny-tiny examples would come with a Makefile ready for use
and some trivial tests to ensure that the sample code builds and
runs on the platforms that implement the specific tests.

Sounds like a good idea to me, provided you or someone you conscript
is willing to write and maintain them.

Erm, I missed (that is, looked at but failed to register) the part
where they were going to get installed in /usr. That doesn't
necessarily seem like a great idea...

[Julio Merino]

Post by David Holland
Erm, I missed (that is, looked at but failed to register) the part
where they were going to get installed in /usr. That doesn't
necessarily seem like a great idea...

And, obviously, I think the opposite. These examples are not related to
the NetBSD source tree. They are something that is supposed to be
shipped with NetBSD, to be used as support material for proper
documentation (which we could ideally have in the form of manpages,
pointing to the relevant sample files from the examples section).

What you are basically saying is that, in order to use these examples,
you must have the source tree. That does not seem like a great idea
because you should be able to use the examples without ever wanting to
build NetBSD itself: they are intended for the end user or developer of
third-party applications, not for the developer of the system. (We
could as well not install the manpages because, well, you can read them
from the source tree too. Or we could get rid of
/usr/share/misc/operator again?)

[Jukka Ruohonen]

Post by Julio Merino
And, obviously, I think the opposite. These examples are not related to
the NetBSD source tree. They are something that is supposed to be
shipped with NetBSD, to be used as support material for proper
documentation (which we could ideally have in the form of manpages,
pointing to the relevant sample files from the examples section).
What you are basically saying is that, in order to use these examples,
you must have the source tree. That does not seem like a great idea
because you should be able to use the examples without ever wanting to
build NetBSD itself: they are intended for the end user or developer of
third-party applications, not for the developer of the system. (We
could as well not install the manpages because, well, you can read them
from the source tree too. Or we could get rid of
/usr/share/misc/operator again?)

I am not sure whether I follow. To me it seems that you are also trying to
test something with these examples (i.e. src/tests/examples/t_asm.sh). We've
discussed toolchain/assembly/etc. -specific tests in PR toolchain/44848.
I think a little more discussion should be devoted to the question on how
to build a consistent and maintainable test setup for assembly, linking, etc.

- Jukka.

[Julio Merino]

Post by Jukka Ruohonen

Post by Julio Merino
And, obviously, I think the opposite. These examples are not related to
the NetBSD source tree. They are something that is supposed to be
shipped with NetBSD, to be used as support material for proper
documentation (which we could ideally have in the form of manpages,
pointing to the relevant sample files from the examples section).
What you are basically saying is that, in order to use these examples,
you must have the source tree. That does not seem like a great idea
because you should be able to use the examples without ever wanting to
build NetBSD itself: they are intended for the end user or developer of
third-party applications, not for the developer of the system. (We
could as well not install the manpages because, well, you can read them
from the source tree too. Or we could get rid of
/usr/share/misc/operator again?)

I am not sure whether I follow. To me it seems that you are also trying to
test something with these examples (i.e. src/tests/examples/t_asm.sh). We've

Those tests are there to ensure that the example builds cleanly and runs
as expected. Building sample code as part of the tests is a
prerequisite to ensure that the sample code remains sane; otherwise, it
may break for who-knows-what-reason and nobody will notice :-/

Note that the same can be said about all the sample configuration files
in /usr/share/examples/. We should have automated tests to (at least)
parse those files with the corresponding tools to ensure they are valid.

[Jukka Ruohonen]

Post by Julio Merino
Those tests are there to ensure that the example builds cleanly and runs
as expected. Building sample code as part of the tests is a
prerequisite to ensure that the sample code remains sane; otherwise, it
may break for who-knows-what-reason and nobody will notice :-/

I mean whether it is a "hello world" written in assembly or in C (or in Lua),
it should be exploited to systematically test the issues Martin raised in
the noted PR.

- Jukka.

[Jean-Yves Migeon]

Post by Julio Merino
These teeny-tiny examples would come with a Makefile ready for use and
some trivial tests to ensure that the sample code builds and runs on the
platforms that implement the specific tests.
Comments / objections?
Thanks!

That's a good idea; I had to implement MD payloads to test for
executable mappings in ATF lately, but only implemented x86 because my
knowledge of other assembly and platforms is limited.

The "Hello World" example is a nice introduction. IMHO, another good
addition would be function calls with 3 or 4 arguments (with maybe one
on stack) and fetching/manipulating the return value.

[Valeriy E. Ushakov]

Post by Julio Merino
I would like to add some trivial, heavily-commented assembly code
examples to /usr/share/examples/asm/. The goal of these examples would
be to illustrate platform-specific stuff rather than teach the assembly
language itself (but this would be a side-effect anyway). For instance,
a "hello world" example would show how to craft an ELF file and how to
perform a couple of system calls according to the platform conventions.
There could be another example showing the C->ASM call protocol.
The reason I'm proposing this is because, out of pure curiosity, I've
started learning PowerPC assembly and such examples could come very
handy. (Books teach you the general assembly language but not how that
is put in practice in a specific platform/assembler... and 'gas' is
quite... special.) I found some sample code in the old wiki, but it
would be much more useful if it were in the tree.
These teeny-tiny examples would come with a Makefile ready for use and
some trivial tests to ensure that the sample code builds and runs on the
platforms that implement the specific tests.
Comments / objections?

Frankly, I think it's pretty pointless. I think that the target
audience for these examples is pretty much nonexistent. People who
*think* they are the target audience are better off reading psABI &co
instead.

-uwe

[Joerg Sonnenberger]

Post by Valeriy E. Ushakov
Frankly, I think it's pretty pointless. I think that the target
audience for these examples is pretty much nonexistent. People who
*think* they are the target audience are better off reading psABI &co
instead.

May I point !X86 && !PPC assembler writers to src/lib/csu to complete
the set of platforms with compiler-indepdent crtbegin/crtend sections?

Joerg

[Julio Merino]

Post by Joerg Sonnenberger

Post by Valeriy E. Ushakov
Frankly, I think it's pretty pointless. I think that the target
audience for these examples is pretty much nonexistent. People who
*think* they are the target audience are better off reading psABI &co
instead.

May I point !X86 && !PPC assembler writers to src/lib/csu to complete
the set of platforms with compiler-indepdent crtbegin/crtend sections?

No. You are completely missing the point of what an example is.

[Emmanuel Dreyfus]

Post by Valeriy E. Ushakov
Frankly, I think it's pretty pointless. I think that the target
audience for these examples is pretty much nonexistent.

I disagree. I had from time to time to write small routines in assembly
languages I was not familiar with (I am not familiar to anything beyond
6809, Z80 and 68000), and some code sample of NetBSD-grade quality would
have helped a lot.

[David Young]

Post by Emmanuel Dreyfus

Post by Valeriy E. Ushakov
Frankly, I think it's pretty pointless. I think that the target
audience for these examples is pretty much nonexistent.

I disagree. I had from time to time to write small routines in assembly
languages I was not familiar with (I am not familiar to anything beyond
6809, Z80 and 68000), and some code sample of NetBSD-grade quality would
have helped a lot.

Heartily seconded.

Dave

[Mouse]

Post by David Young

Frankly, I think it's pretty pointless. [...]

I disagree. ["I'd have use for it"]

Heartily seconded.

I think this is valuable enough that if NetBSD chooses to not do this,
I will volunteer space to host the examples.

/~\ The ASCII Mouse
\ / Ribbon Campaign
X Against HTML ***@rodents-montreal.org
/ \ Email! 7D C8 61 52 5D E7 2D 39 4E F1 31 3E E8 B3 27 4B

[Julio Merino]

Post by Valeriy E. Ushakov
Frankly, I think it's pretty pointless. I think that the target
audience for these examples is pretty much nonexistent. People who
*think* they are the target audience are better off reading psABI &co
instead.

I agree with you that examples are not an excuse for not having
documentation. But having documentation is not an excuse for not having
examples either: they serve two very different purposes. Just look at
any manpage describing an API: it probably contains a piece of code in
it to demonstrate how to use it. Or just look at any programming book;
the problem is, though, that no programming book is going to talk about
the specifics of NetBSD.

I'd certainly have hunted down and read tons and tons of documentation
to come up with a trivial "hello world" myself, but I'd have spent
hours, if not days, to get something extremely rudimentary working.
It's only because I found a very similar program online that I'd
understand the very basics in a few minutes.

Having a little piece of code that is working right away, that you can
just copy/paste and tweak to experiment with something else that you
want to try while learning, is valuable. FYI, several other people,
here and elsewhere, have expressed the same feeling. (OK: this is most
valuable if you already know another language because then you can draw
parallels very quickly.)

[Valeriy E. Ushakov]

Post by Julio Merino

Post by Valeriy E. Ushakov
Frankly, I think it's pretty pointless. I think that the target
audience for these examples is pretty much nonexistent. People who
*think* they are the target audience are better off reading psABI &co
instead.

I agree with you that examples are not an excuse for not having
documentation. But having documentation is not an excuse for not having
examples either: they serve two very different purposes. Just look at
any manpage describing an API: it probably contains a piece of code in
it to demonstrate how to use it. Or just look at any programming book;
the problem is, though, that no programming book is going to talk about
the specifics of NetBSD.
I'd certainly have hunted down and read tons and tons of documentation
to come up with a trivial "hello world" myself, but I'd have spent
hours, if not days, to get something extremely rudimentary working.
It's only because I found a very similar program online that I'd
understand the very basics in a few minutes.
Having a little piece of code that is working right away, that you can
just copy/paste and tweak to experiment with something else that you
want to try while learning, is valuable. FYI, several other people,
here and elsewhere, have expressed the same feeling. (OK: this is most
valuable if you already know another language because then you can draw
parallels very quickly.)

You still haven't answered my question, who are the target audience?

I look at other files in /usr/share/examples and I do understand how
in the context of using netbsd our users (me included) can benefit
from them when they need to configure postfix, racoon or fstab just to
name a few at random.

If I squint at it just the right way I can, in principle, see the
purpose of the specific example you committed *provided* that there
are also a MI man page on our ELF notes and arch-specific SYS(2) pages
on syscall ABI (lib/libc/arch/*/SYS.h). But your example as committed
fails to even use symbolic note and syscall names that netbsd headers
do provide!

In another forum you said that your guess is that I "already know
everything there is to know about assembly in all existing
architectures in the world" and made a conjecture that therefore I
think that "people that don't are stupid and don't deserve to have
some trivial code to start learning." I think I can quote that
safely, since the comment was public.

Both allegations are false, so here is a hint from someone who doesn't
already know about all architectures and who had to learn about them:
gcc -S on simple C test programs, objdump and readelf on existing
binaries can already provide you with most of the examples you
conceivably need. And you don't need to use absolutely bare-bones
manually crafted ELF binaries to (learn to) program in asm, you write
asm routines that you call from and that can call back into C
programs. This way you can concentrate on learning the asm and not on
overcoming heroically unnecessary problems that are unrelated to what
you need to learn (soviet times joke about making love standing in a
hammock, wearing full scuba gear omitted).

I don't find examples "stupid" (I didn't use that word either, btw),
but I still have my doubts about target audience, hence my choice of
"pointless". I also think that linuxish examples/howtos don't quite
become netbsd, so, as I said, if you want to provide documentation for
these areas, please, do it properly.

-uwe

[Julio Merino]

Post by Valeriy E. Ushakov
[...]
You still haven't answered my question, who are the target audience?

Me, for example: someone who is reading a book on architecture X, finds
something interesting that wants to try (like inspecting some particular
register values) and has no trivial way to do so right away because all
the examples in the book are written for a different assembler and I
have no idea how to manually construct a pure assembler binary for
NetBSD that performs the correct syscalls. (My memories vaguely include
dos x86 code, which is very different as you may know. E.g. I wouldn't
know how to write an x86 hello world for NetBSD right now.)

Some other people in this thread have expressed why they think this
would be valuable to them. Granted, in the current form, the code does
not cover their "use cases" yet. The most obvious of these is having an
example that shows how to write an asm function that can be called from C.

Post by Valeriy E. Ushakov
If I squint at it just the right way I can, in principle, see the
purpose of the specific example you committed *provided* that there
are also a MI man page on our ELF notes and arch-specific SYS(2) pages
on syscall ABI (lib/libc/arch/*/SYS.h). But your example as committed
fails to even use symbolic note and syscall names that netbsd headers
do provide!

Well, I will gladly improve that. As I said in the commit message, I'm
not experienced at this point to know if the code is good or not. I was
actually expecting it not to be... but there is nothing preventing it
from being improved!

Post by Valeriy E. Ushakov
[...]
I don't find examples "stupid" (I didn't use that word either, btw),
but I still have my doubts about target audience, hence my choice of
"pointless". I also think that linuxish examples/howtos don't quite
become netbsd, so, as I said, if you want to provide documentation for
these areas, please, do it properly.

My apologies; that comment was out of tone, although it was not
addressed to you in particular. I have actually read the word stupid
elsewhere in a discussion about this particular thread.

[Martin Husemann]

Post by Julio Merino
Me, for example: someone who is reading a book on architecture X, finds
something interesting that wants to try (like inspecting some particular
register values) and has no trivial way to do so right away because all
the examples in the book are written for a different assembler and I
have no idea how to manually construct a pure assembler binary for
NetBSD that performs the correct syscalls.

Yeah, well, what uwe says, and the way you are demonstrating in the example
surely looks like the most complex possible way.

Why not just do something like:

.text
.global main
main:
... some asm stuff
call printf
ret

and "assemble" it by running "gcc test.S"?

Martin

[Valeriy E. Ushakov]

Post by Julio Merino

Post by Valeriy E. Ushakov
[...]
You still haven't answered my question, who are the target audience?

Me, for example: someone who is reading a book on architecture X, finds
something interesting that wants to try (like inspecting some particular
register values) and has no trivial way to do so right away because all
the examples in the book are written for a different assembler and I
have no idea how to manually construct a pure assembler binary for
NetBSD that performs the correct syscalls. (My memories vaguely include
dos x86 code, which is very different as you may know. E.g. I wouldn't
know how to write an x86 hello world for NetBSD right now.)

I don't think that constructing standalone binaries is a good way,
didactically, to learn an assembler.

Post by Julio Merino
Some other people in this thread have expressed why they think this
would be valuable to them. Granted, in the current form, the code does
not cover their "use cases" yet. The most obvious of these is having an
example that shows how to write an asm function that can be called from C.

As I said, cc -S is your friend here. It will give you infinite
examples of exactly what you want, where you use C to express what you
want. Throw in -fpic, -fomit-frame-pointer etc for more fun.

-uwe

[David Holland]

Post by Valeriy E. Ushakov
I don't think that constructing standalone binaries is a good way,
didactically, to learn an assembler.

Right.

Post by Valeriy E. Ushakov

Post by Julio Merino
Some other people in this thread have expressed why they think this
would be valuable to them. Granted, in the current form, the code does
not cover their "use cases" yet. The most obvious of these is having an
example that shows how to write an asm function that can be called from C.

As I said, cc -S is your friend here. It will give you infinite
examples of exactly what you want, where you use C to express what you
want. Throw in -fpic, -fomit-frame-pointer etc for more fun.

I'm not convinced that reading compiler output is a good way to get
started on anything.

I also don't think hand-coding things like ".note.netbsd.ident" is
desirable in any circumstances and it certainly shouldn't be in an
*example*.

And I still object to installing these examples. For their ostensible
intended purpose they can and should live purely in the source tree.

[Julio Merino]

Post by David Holland
I'm not convinced that reading compiler output is a good way to get
started on anything.

Exactly my point. I could also RTFS of things people have pointed out,
but that's not my idea of "learner-friendly" material; specially for a
complete newbie in a topic.

Post by David Holland
I also don't think hand-coding things like ".note.netbsd.ident" is
desirable in any circumstances and it certainly shouldn't be in an
*example*.

Agreed. I'm willing to change that, but I'm trying to hold further
changes until this thread "stabilizes".

[Valeriy E. Ushakov]

Post by Julio Merino

Post by David Holland
I'm not convinced that reading compiler output is a good way to get
started on anything.

I'm not referring to random compiler output. I'm referring to
compiler output of small programs that demonstrate some specific
scenarios, like a function call, a structure member access, etc. E.g.

extern void bar(int, int, int);
void foo() { bar(1, 2, 3); }

The mail that started the thread presupposes a book, which should
already provide enough background to read compiler output for such
test programs. All books on assembler will cover calling conventions
&c anyway and psABI is not that hard to read either.

Actually, I would say that reading compiler output (in general) is not
that bad way to start, either. As some linguist said, a very
effective way to really improve your $human_language (he was talking
about Sanskrit, iirc) is to prepare a critical edition of some text in
that language. Immersion might seem tough, but it is effective.
Anyway, my advice was about simple programs which shouldn't unduly
strain anyone, really.

Post by Julio Merino
Exactly my point. I could also RTFS of things people have pointed out,
but that's not my idea of "learner-friendly" material; specially for a
complete newbie in a topic.

I understand your enthusiasm, but I still don't think teaching
complete newbies assembly programming to be something that netbsd
should consider a useful goal. Especially so when the examples you
choose are hardly "learner-friendly".

As I said, you are not helping any newbies, yourself included, when
you start with completely standalone manually crafted binaries. The
first example you start with is mostly just confusing (any perceived
"look ma, no libc" coolness factor notwithstanding) and irrelevant
(very very few people should even care, definitely not the newbies).

If you are excited about that coolness factor, make a blog post about
it or something, but it doesn't need to be in the repo. It's like
vanity configs.

The other example you mentioned (taking arguments from a C call) is so
trivial/essential that your textbook and architecture manual should
already have it - duplicating that material in /usr/share/examples
hardly adds any value. There are also a lot of permutations:
returning a struct, passing a struct, passing floating point values,
passing sufficiently many arguments to run out of registers and
different combinations of the above. Asking compiler (with a suitable
test program) is easier and doesn't limit you to the few examples
manually crafted for you by someone. There are also architectures
where you cannot just say: "oh passing arguments is easy, you just
load them to registers M to N (or push them into the stack)," - make a
nice looking example and feel good about it. For VAX you will have to
explain the call frame layout as automagically created by call*
instructions. For SPARC you will have to explain register windows.
For IA64 you will have to explain the version of register windows
created by Escher on a bad trip. And all that is already done by
textbooks, manuals and standards.


PS: What's next, a C tutorial?

-uwe

[jean-Yves Migeon]

Post by Valeriy E. Ushakov
PS: What's next, a C tutorial?

You may find this answer funny, but having C tutorial with skeleton for
driver development (examples: block, char devices, network MAC/PHYs,
etc.) would be quite helpful, instead of wading through hundreds
(thousands?) of NetBSD's handbook pages.

IMHO the assembly examples serve the same purpose. I always find more
practical to have small, understandable examples at hand rather than
overly-big-complex-documentation.

The less oubvious part is figuring out that these examples exist and
remain visible on the long run (now they are because we are talking
about them, but what about months/years later?). There are lots of
interesting stuff under /usr/share/examples and /usr/pkg/share/examples,
however most people/users do not know about this.

[Julio Merino]

Post by Valeriy E. Ushakov

Post by Julio Merino
Exactly my point. I could also RTFS of things people have pointed out,
but that's not my idea of "learner-friendly" material; specially for a
complete newbie in a topic.

I understand your enthusiasm, but I still don't think teaching
complete newbies assembly programming to be something that netbsd
should consider a useful goal.
Especially so when the examples you
choose are hardly "learner-friendly".

As I have mentioned countless times already: the particular example I
posted is poor, precisely due to my lack of knowledge on the area. It
can (and will, according to the suggestions already in the thread) be
fixed to be more representative, so please stop looking at that example.

See? If I could have looked at something, I'd not have made those
mistakes, but I did them because I looked at the "wrong example" online.
How could I know that creating a libc-less program was stupid? How
could I know it was "look ma, no libc"-cool? By the way, making fun of
people does not seem like a good way to convince them that they are
wrong; it's just gonna piss them off.

Post by Valeriy E. Ushakov
As I said, you are not helping any newbies, yourself included,

Why do you keep assuming that this is useless, including to myself? How
can you decide what I can find or cannot find useful? It may be useless
to you, but I'd have found it extremely helpful if it had been there...
just as the example code I found online did (although it pushed me in
the wrong direction, because it is not reviewed).

[Valeriy E. Ushakov]

Post by Julio Merino

Post by Valeriy E. Ushakov

Post by Julio Merino
Exactly my point. I could also RTFS of things people have pointed out,
but that's not my idea of "learner-friendly" material; specially for a
complete newbie in a topic.

I understand your enthusiasm, but I still don't think teaching
complete newbies assembly programming to be something that netbsd
should consider a useful goal.

I still didn't get an answer to this question. What does this all
have to do with netbsd?

Post by Julio Merino

Post by Valeriy E. Ushakov
Especially so when the examples you
choose are hardly "learner-friendly".

As I have mentioned countless times already: the particular example I
posted is poor, precisely due to my lack of knowledge on the area. It
can (and will, according to the suggestions already in the thread) be
fixed to be more representative, so please stop looking at that example.

This is the only example that was committed and which is at least
netbsd-specific. What else was there to look at? Ok, I will stop.

You also mentioned that

| There could be another example showing the C->ASM call protocol.

for which I suggested that there's nothing netbsd-specific about it
and you can trivially obtain this kind of examples from the compiler.
I think dsl@ also expressed his agreement with that last suggestion
earlier in the thread.

Compile

int foo(int a) { return a; }

with -S, rename the output to .S add it to your SRCS and hack away.
Call foo() from your main.c. Change signature of foo to suit your
needs.

Have you actually tried that?

Post by Julio Merino
By the way, making fun of people does not seem like a good way to
convince them that they are wrong; it's just gonna piss them off.

It was never my intention to make fun of you. The "look ma" comment,
if that was what triggered your reaction, was about the original linux
example that I vaguely remember seeing in passing some time ago.

Post by Julio Merino

Post by Valeriy E. Ushakov
As I said, you are not helping any newbies, yourself included,

Why do you keep assuming that this is useless, including to myself? How
can you decide what I can find or cannot find useful?

Why do you keep assuming that your learning experience is
representative of that of a typical subset of netbsd users? That is,
to repeat myself, what is the target audience and how it is relevant
to netbsd. Why we as a project want to commit ourselves to
maintaining assembler tutorials for N+1 architectures?

I don't prescribe you how you should learn an assembler, though I
tried to provide hints based on my experience with learning (FSVO
"learning") assemblers for more than half a dozen architectures. But
when you want to commit your examples, it's no longer just about your
own learning experience. I think I can question both the quality and
relevance of the examples in particular and the wisdom of having such
examples in tree in general.

Post by Julio Merino
It may be useless to you, but I'd have found it extremely helpful if
it had been there... just as the example code I found online did
(although it pushed me in the wrong direction, because it is not
reviewed).

When you say that you as a newbie found this or that example helpful,
nobody can really argue with that as it's a statement about you ("I
found it helpful"), not about an example. If I decide to learn
somthing I may find some techniques or examples helpful that would
horrify experienced practitioners. Yet they will also be in no
position to challenge my statement that I found those examples
helpful.

Now, please, can we finally start discussing the examples per se?

Have you tried "cc -S" route? Did you find that it suck? Confusing?
Do you still want a hand-written example after trying cc -S?

And there's also that question about netbsd relevant target audience
that I'd still like to get an answer for. I dont think that you have
shown how teaching complete newbies assembler programming is relevant
to their day-to-day use of netbsd.

-uwe

[Julio Merino]

Post by Valeriy E. Ushakov

Post by Julio Merino

Post by Valeriy E. Ushakov

Post by Julio Merino
Exactly my point. I could also RTFS of things people have pointed out,
but that's not my idea of "learner-friendly" material; specially for a
complete newbie in a topic.

I understand your enthusiasm, but I still don't think teaching
complete newbies assembly programming to be something that netbsd
should consider a useful goal.

I still didn't get an answer to this question. What does this all
have to do with netbsd?

Unless I'm really mistaken, the way to perform syscalls and the way to
arrange the parameters to them is specific to the OS. (In x86, IIRC,
Linux uses int 0x80 to invoke a syscall; do we use the same? Do we
arrange registers in the same way?)

I'm not as sure about this, but: I also believe that the calling
conventions from C to ASM and viceversa are not universal and they
depend on the specific OS ABI, the platform and the compiler in use.

So if any of these assertions is slightly true, then, these examples are
NetBSD-specific.

Post by Valeriy E. Ushakov

Post by Julio Merino

Post by Valeriy E. Ushakov
Especially so when the examples you
choose are hardly "learner-friendly".

As I have mentioned countless times already: the particular example I
posted is poor, precisely due to my lack of knowledge on the area. It
can (and will, according to the suggestions already in the thread) be
fixed to be more representative, so please stop looking at that example.

This is the only example that was committed and which is at least
netbsd-specific. What else was there to look at? Ok, I will stop.

An attempt to clarify: nothing yet, because I have intentionally avoided
touching anything until we resolved this thread. (The commits were
premature, driven by early supportive comments and my lack of time for
this stuff, so I didn't want to make the situation any worse by
committing more stuff during the discussion. Maybe the actual
postponing of the changes is making things worse...)

Post by Valeriy E. Ushakov
You also mentioned that
| There could be another example showing the C->ASM call protocol.
for which I suggested that there's nothing netbsd-specific about it
and you can trivially obtain this kind of examples from the compiler.
earlier in the thread.
Compile
int foo(int a) { return a; }
with -S, rename the output to .S add it to your SRCS and hack away.
Call foo() from your main.c. Change signature of foo to suit your
needs.
Have you actually tried that?

No (well, see below). Why should I? I know I could jump through hoops
to get to the information I need. But this information belongs in
documentation, and documentation usually comes with supporting code, so
the intent of this is to provide the latter.

Post by Valeriy E. Ushakov

Post by Julio Merino
By the way, making fun of people does not seem like a good way to
convince them that they are wrong; it's just gonna piss them off.

It was never my intention to make fun of you. The "look ma" comment,
if that was what triggered your reaction, was about the original linux
example that I vaguely remember seeing in passing some time ago.

Alright. I'm just misreading text and overreacting; sorry about that.

Post by Valeriy E. Ushakov

Post by Julio Merino

Post by Valeriy E. Ushakov
As I said, you are not helping any newbies, yourself included,

Why do you keep assuming that this is useless, including to myself? How
can you decide what I can find or cannot find useful?

Why do you keep assuming that your learning experience is
representative of that of a typical subset of netbsd users?

Because other people, not only me, have expressed that they find this a
good idea.

Post by Valeriy E. Ushakov
Have you tried "cc -S" route? Did you find that it suck? Confusing?
Do you still want a hand-written example after trying cc -S?

I have been refusing to due to what I said above: it's not learning
material.

However, I just did try it and the output is "meh". It includes some
things (not talking about the machine code itself, but about the .*
tags) that I can't explain right away. Yes, I could now "info gcc",
look for the appropriate statements, etc. but that's the "jumping
through hoops" mentioned earlier...

Also, and because these output files will always rely on libc, they are
effectively not showing me anything about how they interact with the
kernel (which is what I was mostly curious about).

[David Holland]

Post by Julio Merino
Also, and because these output files will always rely on libc, they are
effectively not showing me anything about how they interact with the
kernel (which is what I was mostly curious about).

If *this* is what you want to know about, go read the syscall stubs in
libc. The asm code you want is already there.

[David Holland]

Post by Valeriy E. Ushakov

Post by David Holland
I'm not convinced that reading compiler output is a good way to get
started on anything.

I'm not referring to random compiler output. I'm referring to
compiler output of small programs that demonstrate some specific
scenarios, like a function call, a structure member access, etc. E.g.
extern void bar(int, int, int);
void foo() { bar(1, 2, 3); }

Even so. I don;t know PPC asm, but I know that with mips there are a
number of nonobvious things that can be explained properly (and thus
become much clearer) with a worked example.

Admittedly I don't see any of that in the example that's been
committed.

Also, compilers often do crazy things and the output is often very
unclear. This is particularly noticeable with intel where the compiler
will do things like use LEA for mukltiplication, but it's true
elsewhere as well.

(And it's much, much worse with compilers that compile to higher-level
languages than assembler. Imagine trying to learn C from cfront
output.)

Post by Valeriy E. Ushakov
The mail that started the thread presupposes a book, which should
already provide enough background to read compiler output for such
test programs. All books on assembler will cover calling conventions
&c anyway and psABI is not that hard to read either.

Um. I must have missed that part too. (That makes me what, 0 for 3 in
this?)

If you have a book, what's the point? I thought the idea was to
provide worked examples for developers who don't know the
architecture, don't have the books, but find themselves needing to
adjust MD bits regardless. *That* would be useful.

[David Laight]

Post by Valeriy E. Ushakov

Post by Julio Merino
Some other people in this thread have expressed why they think this
would be valuable to them. Granted, in the current form, the code does
not cover their "use cases" yet. The most obvious of these is having an
example that shows how to write an asm function that can be called from C.

As I said, cc -S is your friend here. It will give you infinite
examples of exactly what you want, where you use C to express what you
want. Throw in -fpic, -fomit-frame-pointer etc for more fun.

And -fverbose-asm
I've often used compiler genereated code to help understand how
an instruction set works.
Generally the code is easier to read with -O2 or -O3.

David

[Joerg Sonnenberger]

Post by Valeriy E. Ushakov
If I squint at it just the right way I can, in principle, see the
purpose of the specific example you committed *provided* that there
are also a MI man page on our ELF notes and arch-specific SYS(2) pages
on syscall ABI (lib/libc/arch/*/SYS.h). But your example as committed
fails to even use symbolic note and syscall names that netbsd headers
do provide!

In fact, I find this more harmful. It is exactly the kind of dependency
we don't want to have. It makes people believe that randomly changing
the startup code is a supported configuration etc. There are other
issues, like adding yet another place where code changes with the kernel
version without good reason etc.

Joerg