#791 unddocumented z80 instructions

[Ragozini Arturo]

The best and more accurate description of the Z80, fixing a lot of small bugs in the official documentation and filling a lot of undocumented features is this
http://www.z80.info/zip/z80-documented.pdf

I've noted that the ASM code generated by SDCC does not support a lot of possible optimisations related to the use of ixh ixl iyh iyl as single 8 bit registers.

Moreover it seems to generate undue tests on A when it can use the flag results from operations on other 8bit registers.
It seems to not take into account the fact that the INC/DEC instructions on all 8bit registers affect the Z flag, not only the opcodes on A.

[Ragozini Arturo]

Ignore the last statement about INC/DEC as I'm not able to replicate the case where I had
dec c
ld a,c
or a,a
jr z,%00XXX

In all successive experiments the code is correctly doing
dec c
jr z,%00XXX

[Sebastian Riedel]

There is a rule to optimize it, but it probably depends on a not being used.
The new calling convention ends functions that have to clean their arguments from stack withjr (hl) instead of ret.
The peephole optimizer can’t say anything about jr (hl), so it assumes a being used.

[Ragozini Arturo]

The compiler could gain a lot by supporting low/high ix and iy. Currently, if normal registers are already used, the compiler books room on the stack and uses IX to point at it using (IX+n). The generated code is slow because of the slowness of the opcodes using the index registers and of the setup time.
If you need up to four 8 bit variables, you can avoid to allocate their room on the stack and use directly IXL, IXH, IYL, IYH. There is no set up time and the opcodes using the above registers are much faster that accessing data in ram through the index registers.

[Sebastian Riedel]

(This only focuses on the first section)

Are any instructions of http://www.z80.info/zip/z80-documented.pdf not listed in https://clrhome.org/table/? (undocumented is red)

Which are missing? undocumented ixh etc. variants of DD, DDCB, FD, FDCB?

Looking at the docu it looks like sll, in (c) is generally missing in upstream. But I would need to study the tests and emitted opcodes.

Which opcodes are missing for your existing asm?

[Ragozini Arturo]

In my existing asm I use all the opcodes involving IXL, IXH, IYL, IYH, which are unsupported by asz80. These registers are used in many libraries e.g. in the PT3 player, that is a reference among music players for z80 machines with AY8910 chip (ZX spectrum, CPC Amstrad, MSX 1 & 2...).
https://github.com/MMaciocia/RC2014-YM2149/blob/master/MM-PTxPlay.asm
They are used also in the unpack routine of same data compression tools (e.g. Pletter).
https://github.com/nanochess/Pletter/blob/master/unpack.asm

Your table seems complete, but it is missing of the full description of the way flags work. You can see how flags are affected by all instructions in the table from page 26 in the z80-documented file.
The SLL and IN (C) are respectively at page 11 (§3.1) and at page 43 (as in f,(c)). Note that in the same document there is a paragraph about errors in the Zilog documentation (pag. 24).

About the fact that the quality of the generated code could improve by allowing the compiler to use IXL, IXH, IYL, IYH, consider that, once all normal registers are used, in all the cases a function is using less than 4 temporary char variables there will be no need of allocating room on the stack and of accessing to the RAM through IX.

Another important resource that seems not utilized by the compiler is the alternate register set accessed by EXX and by EX AF,AF'. I see that it is very difficult, due to the restrictions in the handling of the exchange of values, to write a compiler using also this feature, nevertheless, using A, IX,IY and the stack to exchange values between the two set of registers leads to optimal code both for performance and size.

[Sebastian Riedel]

The flags only matter for the code generator (?), peephole optimizer and emulator.
I’m only focusing on the assembler here.

sdasz80 already has extensions for

and/add/sub/add/adc/sbc a, ixh/ixl/iyh/iyl
inc/dec ixh/ixl/iyh/iyl
ld ixh/ixl/iyh/iyl, #
ld ixh/ixl/iyh/iyl, r
ld r, ixh/ixl/iyh/iyl
ld ixh/ixl/iyh/iyl, ixh/ixl/iyh/iyl

also sll

[Ragozini Arturo]

I wasn't able to make them work. In these ticket pages I've seen that there is an unresolved bug in the version of sdasz80 distributed with SDCC preventing to use the directive
.allow_undocumented
Moreover this latter directive seems not documented in the online asz80 documentation

[Sebastian Riedel]

Support for undocumented instruction is an sdasz80 extension. asz80 doesn’t have that.

It looks like it was added for Z80N and eZ80 (both not supported by upstream) and enabled there by default.

[Ragozini Arturo]

Thanks! I will try .zxn as workaround as you suggest here .
Btw I did a quick search on google without a result, where do I find official sdasz80 manuals ?

[Sebastian Riedel]

There is no manual. And I have no idea how Alan builds the manual for ASxxxx.
You sadly have to read the source code.

sdcc/sdas/asz80/z80pst.c has the basic mnemonics, that file is pretty short and readable

sdcc/sdas/asz80/z80adr.c translates the arguments into symbols, also rather short. *adr.c usually has lists with accepted registers.

sdcc/sdas/asz80/z80mch.c handles the cycle counting, opcode emission and is rather long. machine(mp) is the most interesting part and searching for symbols you know from sdcc/sdas/asz80/z80adr.c usually helps.

[Sebastian Riedel]

Should be fixed in [r13287]

[Sebastian Riedel]

Also what do you mean with

The assembler is very bare bone and, due to bugs and its odd opcode notation, is not the best to integrate existing libraries in C projects.

in your review?

[Ragozini Arturo]

The main problems that make hard to port existing ASM to sdasz80 are
1) the need of A as operand in all 8 bit math and logical operations (e.g. and A,B instead and B)
2) the strange notation for offeset involving IX and IY where (IX+n) becomes n(iX)
3) the need of # as prefix for numeric constants (this can be very hard to fix)
4) the need of a "." for as prefix for commands like db, dw, org
Aside for the oddness in the ASM notation, the assembler does not seem to have any fancy features present in other Z80 macro assemblers (eg. support foruser defined structures) and it was missing the support for undocumneted z80 instructions (but you fixed that in the last update). The lack of documentation couldhave affected my understanding of ifs features, maybe having a manual or just a description of the differences by asz80, could help.

[Sebastian Riedel]

1 and 2 can certainly be changed. (new asgb accepts that kind of syntax)
3 and 4 are inherently ASxxxx syntax, which can’t be changed, but maybe it’s possible that 4 could be fixed with defines. I’m not sure.
The assembler independent part should be the same for sdasz80 and asz80 (macros, if etc.)

[Ragozini Arturo]

Another thing, error reporting in the last sdasz80 is broken. It seems that after certainkind of errors or after a given number of errors, no error at all is reported

If you run
sdasz80 audio.s
you will getno error, but the code is missing of a bunch of labels so it cannot be correct

The label SRCAUD is called at line 1218, but no error is generated
The REL file is broken naturally, but I was expecting an error report

[Sebastian Riedel]

I get errors

~/projects/sdcc-code/sdcc/bin/sdasz80 -ploff audio.s
audio.s:1168: Error: <i> File not found.
audio.s:1170: Error: <i> File not found.
audio.s:1172: Error: <i> File not found.
audio.s:1174: Error: <i> File not found.
audio.s:1176: Error: <i> File not found.
audio.s:1178: Error: <i> File not found.
audio.s:1180: Error: <i> File not found.
audio.s:1218: Error: <u> undefined symbol encountered during assembly
audio.s:1318: Error: <q> missing or improper operators, terminators, or delimiters
audio.s:1319: Error: <q> missing or improper operators, terminators, or delimiters
removing 

From the listing:

      00064F CDr5Fr06         [17] 1217         call    SRCFMP
u     000652 CD 00 00         [17] 1218         call    SRCAUD
      000655 3Ar40r02         [13] 1219         ld  a,(CHIPS)
      ...
                           000000  1315 .if withAUD=1
                                   1316 FM3TXT: .db "AUD"
                                   1317 .endif
q     0006E4 41                    1318 FM2TXT: .db "APRL"
q     0006E5 4F                    1319 FMTEXT: .db "OPLL"

But please open a separate bug ticket for this. And you can’t use .db like .str.

Edit: FM2TXT: .db "A","P","R","L" would work, but FM2TXT: .str "APRL" is just easier

[Ragozini Arturo]

Ok, I will. BTW, what is -ploff ?
In the meanwhile I've found .ascii as well (but other assemblers accept DB also for strings)

[Sebastian Riedel]

$ sdasz80 -h

-l prints the listing
-o creates the rel file, otherwise there would only be a listing
-ff is a listing setting that marks relocatable addresses with r

      00005C 22r01r00         [16]  203         LD (PT3_MODADDR),HL

-p makes the listing print less \f

[Ragozini Arturo]

The version is the one from the last SDCC build, accepting .z80 .allow_undocumented

It reports this string
F:\SDCC\MSX_Fusion-C_V1.3\WorkingFolder\sdcc_megarom-master>F:\SDCC\bin\sdasz80

sdas Assembler V02.00 + NoICE + SDCC mods (Zilog Z80 / Hitachi HD64180 / ZX-Next / eZ80)

Copyright (C) 2012 Alan R. Baldwin
This program comes with ABSOLUTELY NO WARRANTY.

[Aoineko]

I have not found documentation about this.
Arturo said we can use the --allow-undocumented-instructions command line parameter, but is there also a pragma to enable this feature per file?

[Philipp Klaus Krause]

Currently, there is no such pragma, and the only documentation of the option is sdcc --help

[Philipp Klaus Krause]

AFAIK, current SDCC makes reasonable use of undocumented instructions (in particular those for iyl and iyh) when --allow-undocumented-instructions is used with sufficiently high --max-allocs-per-node, so I'm closing this ticket.

[Ragozini Arturo]

Any hope to add support for EXX and AX AF,AF' the code generation of SDCC ?

[Philipp Klaus Krause]

Since those are not undocumented,, they are outside the scope of this ticket.
But: In the short term, probably not. Currently the main focus of SDCC developers apparently is on bugfixing, frontend improvements, standard compliance.
Also using the second register set is not that easy: some users want to have it reserved for use by their interrupt routines or a BIOS. An data transfer between the two sets is not that easy, so it would take quite some effort to implement efficient use of the second register set.
But it is a free compiler and one never really knows what topic SDCC developers might work on next, or for what feature or bugfix users provide patches.