List files structure documentation

[stevexyz]

I was trying to setup this very promising debugger for my ZX80/ZX81 development, but trying to setup the launch.json file I stumped on the list files.

I'm using the very powerful fasmg with EZ80 includes and some other custom scripts (you can see it in the "Extreme 1k programs for ZX80 and ZX81: starter kit" at https://sinclairzxworld.com/viewtopic.php?f=6&t=2349).

This setup currently produces a sigle listing with "address" and "sourcefile,line") as you can see below as an example:

00000000 (pippo.asm,1):  00                      nop
00000001 (pippo.asm,2):  C3 0C 00                jp test
00000004 (pippo.asm,4):  00                      nop
00000005 (pippo.asm,5):  18 05                   jr test
00000007 (test.inc,1):   00                      nop
00000008 (test.inc,2):   3A 0C 00                ld a,(test)
0000000B (pippo.asm,8):  00                      nop
0000000C (pippo.asm,9):  00                      test: nop
0000000D (pippo.asm,10): 00                      nop 

(discussed here: https://sinclairzxworld.com/viewtopic.php?t=2289&p=23674#p23674)

I can adapt the file to a new format, but I didn't find any description of the format accepted.

PS: I've also a simple symbols file with a list labels and addresses (the only help in debuggers until now I was not able to get to see the full listing with my comments)...

[maziac]

The DeZog does not support the fasmg assembler.

Best supported is sjasmplus. If you manage to convert to this format it should work.

I don't have a format description and I guess sjasmplus is also lacking one.

But you can find a sample output here: https://github.com/maziac/z80-sample-program/blob/master/z80-sample-program.list

DeZog can do without a symbols file. It grep the labels from the list file. But it will also accept symbols that are added at the end of the list file. You can find an example here (it's a different file than above): https://github.com/maziac/z80-sample-program/blob/develop/z80-sample-program.list

[stevexyz]

I try to specify some rules if I understand the format:

1. one single list file is used to specify multiple sources (included) and the source file name is being gathered by DeZog from the comment line "# file opened:"
2. the format is using fixed lenght fields (if not please specify how the fields are being identified) in this way: a. 3 chars: line number b. 2 chars: "+ " for includes or "++" for includes of includes, else spaces c: 4 chars: exadecimal address d: 14 chars: compiled code (with ... on overflow and sometime a strange ~) e: the rest is the source text

I assume that just 1 and 2.a and 2.c are being used by DeZog, correct?

[maziac]

1. one single list file is used to specify multiple sources (included) and the source file name is being gathered by DeZog from the comment line "# file opened:" => yes
2. the format is using fixed lenght fields (if not please specify how the fields are being identified) in this way: a. 3 chars: line number => It should be 4 chars b. 2 chars: "+ " for includes or "++" for includes of includes, else spaces c: 4 chars: exadecimal address d: 14 chars: compiled code (with ... on overflow and sometime a strange ~) e: the rest is the source text

I think you are right that 2.b isn't used (but I'm not 100% sure anymore). However the '# file closed:' is also important.

If in doubt you can also have a look at loadAsmListfile in src/labels.ts. Although I have to apologize beforehand: It is overcomplicated because it tries to handle 3 different assembler formats at the same time. (I don't dare to rewrite it...)

[stevexyz]

I tryed to do the "adapter" but I think something is not digested since the debugger do very strange things and position in very strange places of the code. I looked at the label.ts file and indeed is pretty "articulated"... In stead of rewriting it, I was thinking it would be much easier form me and for whoever else would like to use it to have another value for the "asm" field as for example "DeZogInternalStructures", and with this value DeZog simply skips all the parsing and just directly do the load of the internal structures. It should be enough simple and surely more powerful than anything else. What do you think about it? In case you are ok with the idea simply define a the structure to fill (e.g. in json or xml or anything structure else)... Thank you!

[maziac]

I don't fully understand: "...DeZog simply skips all the parsing and just directly do the load of the internal structures..." How should this work? Who should fill this structure?

Maybe I could split up the function in labels.ts in the future to make it more simple to add other assemblers. That would definitely an advantage.

[stevexyz]

I don't fully understand: "...DeZog simply skips all the parsing and just directly do the load of the internal structures..." How should this work? Who should fill this structure?

I mean that the label.ts is loading its internal data structures "parsing" the list files. What I can do (and whoever else want to interface directly with DeZog) is writing a json file with the exact structure of the internal data and then you can simply load the json inside these structures.

I said json since I thought this would be good, but you can choose any format you like. You should just formalize how this file should be composed (or these files in case you prefer to have one for each structure).

If I got it properly the insternal structures are:

    /// Map that associates memory addresses (PC values) with line and files.
    private fileLineNrs = new Map<number,SourceFileEntry>();

    /// Map of arrays of line numbers. The key of the map is the filename.
    /// The array contains the correspondent memory address for the line number.
    private lineArrays = new Map<string,Array<number>>();

    /// An element contains either the offset from the last
    /// entry with labels or an array of labels for that number.
    private labelsForNumber = new Array<any>();

    /// Map with all labels (from labels file) and corresponding values.
    private numberForLabel = new Map<string,number>();//ValueLocation>();

    /// Map with label / file location association.
    private labelLocations = new Map<string,{file: string, lineNr: number}>()

    /// Map with the z88dk labels/symbols.
    private z88dkMappings=new Map<string, number>();

[maziac]

You mean to pass a json (or whatever) file to DeZog instead of a list file?

[stevexyz]

You mean to pass a json (or whatever) file to DeZog instead of a list file?

Yes

[stevexyz]

What do you think about it?

[maziac]

To be honest, I‘m not too enthusiastic about it. I‘d rather refactor the current implementation to make it easier to add new parsers.

[stevexyz]

Surely your call (even if I'm not a typescript expert I was trying to look into the code to better understand or make the changes but as you said at the beginning is not so straightforward)...

[stevexyz]

Just to know if there is some progress on the refactorization or there are other options to add new assemblers

[maziac]

Good timing.

I have been working on this the last weeks. Today the new release 1.5.3 has gone out which should make it much easier to add a new assembler, please see https://github.com/maziac/DeZog/releases/tag/v1.5.3

You'll find also a guide here: https://github.com/maziac/DeZog/blob/master/design/AddingNewAssemblers.md Let me know if you are missing something.

[stevexyz]

Very good! :)

Documentation seems nice, I'll have surely a look on it to implement the z80 fasmg compatibility, even if I'm not so familiar with that VS programming language. I'll let you know!