Authoritative documentation of assembler for M1 machines?

[klapauciusisgreat]

I really appreciate this repository, and this isn't an issue with it as such, but I wanted to ask if anyone here can provide an actual documentation page for the assembler apple uses. It seems the mac OS X Assembler guide (old copy at http://personal.denison.edu/~bressoud/cs281-s07/Assembler.pdf )is out of date, and there isn't a meaningful guide for clang llvm assmbler (I guess, that's because it's a framework, not an assembler with macros and directives).

I sortof managed to muddle through some of the problems, but there are differences between apple's old documentation and the gas manual. E.g. macros - they can take named parameters. But you can't redefine symbols with .set (which is sometimes quite useful). I'd be great to have an authoritative manual, or alternatives to the apple assembler. E.g., is there a yasm etc that can be used ? I asked around in other places, but not much success yet.

I'm hesitant to make this an issue here, as this isn't y'all's fault. However, it seems y'all had to figure some of this out and it would be great to share any expertise you might have. If this is an unreasonable imposition, please feel free to close this without a comment.

Many thanks in advance.

[below]

It is an indeed excellent idea to make this an issue here, but I do not mind at all!
Unfortunately, however, I don't know either. As to the syntax itself, Apple is rather adamant that they are sticking to the ARM64 Reference Manual, and indeed, they are (whereas GNU as takes some liberties with that)

Concerning macros and directives, I have no idea, and there does not seem to be a real interest at Apple to publish such documentation these days.

Of course, all of this should be in the source code, but … "Code is Documentation" may not always work.

That said, I try to bring the topic up as often as possible, and maybe the growing popularity of this repository will put some some weight behind it.

Thank you for reminding me!

[klapauciusisgreat]

Thanks for the kind words! I'm dismayed by the apparent lack of interest in having a completely documented toolchain by the folks on stackexchange, apple forums etc.

Speaking of source code, is the source for the apple assembler actually published ? Apple claims everything is open source, but I have trouble finding the code, e.g. on https://opensource.apple.com/source/

I'm not above digging through it to answer my questions ;)

[below]

Searching a bit, and given that Apple likes to point to the ARM documentation: How does this look for a start? https://developer.arm.com/documentation/100067/0611

[klapauciusisgreat]

That looks great, especially https://developer.arm.com/documentation/100067/0611/armclang-Integrated-Assembler.

However, AFAIK, the apple assembler does not allow multiple statements in one line separated by ';', nor does this armclang documentation have any documentation on .set directives.

There's also https://developer.arm.com/documentation/100068/0612/migrating-from-armasm-to-the-armclang-integrated-assembler/symbol-definition-directives and https://developer.arm.com/documentation/100068/0612/migrating-from-armasm-to-the-armclang-integrated-assembler/overview-of-differences-between-armasm-and-gnu-syntax-assembly-code?lang=en

This seems to indicate that the new clangarm assembler follows the gnu as.

[klapauciusisgreat]

https://github.com/llvm/llvm-project/blob/92920c4fe3e29640e45153f3048105970b5b1e42/llvm/lib/MC/MCParser/AsmParser.cpp

seems to contain the good stuff.

[klapauciusisgreat]

I got what I needed to work and the major stumbling stones were

1. semicolons - they are treated as beginning of comment till end of line
2. can't redefine symbols with labels (I think this is due to llvm trying to assemble in a single pass, it's not specific to apple, but it's different to GAS.
3. vector move instructions in GAS mov v2.2d[0] have to be written as mov v2.d[0] in apple's as. Other size specifiers, like 16b work just fine.
4. GAS has a pseudo-op for loading full addresses (adr x0, label), apple's as requires

adrp x1, label@PAGE
add x1, x1, label@PAGEOFF

I'm still waiting to hear from apple, but I'm not sure anything will be forthcoming - they have escalated twice to another developer rep and then clammed up.

Maybe OK to close this issue ?

[klapauciusisgreat]

Apparently, there is another 'as' as part of the cctools project. That seems to be based on an ancient 'gas' codebase. Maybe it's worthwhile building it, at least so one has a working assembler with a source. If someone does successfully build and run that assembler, it would be great to update this issue.

https://github.com/apple-oss-distributions/cctools/tree/cctools-973.0.1/as

And, I think I found the modifications to llvm for the assembler:

https://github.com/apple-oss-distributions/llvmCore/tree/584b5da359e0201968e5c405e12cfbbcf0042a52/lib/AsmParser

At least, LLLexer.cpp has the code to handle semicolons as comments.

So I assume that one could mix these Apple llvmCore contributions into the official llvmCore project, and then build an 'as' binary that's identical to Apple's 'as'. If someone does, please drop instructions here :)

[bdlink]

This would make a good discussion entry, as it is not really an issue with the code base. Perhaps the repo could turn on discussions and move the thread there so it isn’t lost.