1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
.Dd June 7, 2022
.Dt UXNDEBUG 5
.Os uxndebug version 2
.Sh NAME
.Nm uxndebug ,
.Nm .tal.debug
.Nd uxntal debug info file format
.Sh DESCRIPTION
Version 2 of the format of debug information for an uxntal rom file is documented in this file.
.Pp
The basename of the file containing debug information for a source file
.Pa foo.tal
must be named
.Pa foo.tal.debug .
.Pp
Each line of the debug file is terminated by a single
.Aq 0x0A
line feed character, and contains one decimal number written in the ASCII characters
.Sq 0
-
.Sq 9
and an optional ASCII string label.
A label should be a full label, ie
.Qq absolute
or
.Qq absolute/sublabel .
If the number is not present then there should be no label.
A label should be separated from the number by a single space character, one
.Aq 0x20
byte.
.Pp
The first number in the file is a decimal version number written in ASCII characters, followed
by two line feeds.
.Pp
After these two line feeds, the debug information begins.
Hereafter,
.Dq Va byte number
refers to the number of
.Aq 0x0A
bytes encountered after the first two.
Therefore, after the first two, the
.Va "byte number"
starts at 0 and increases by one on each new line.
Therefore, for some systems, the value of the
.Va "byte number"
is equal to the line number in the file minus 2.
.Pp
The
.Va "byte number"
in the file corresponds to the
.Em byte
of the rom,
and the number written on that line signifies which
.Em token
in the source files was assembled into that
.Em byte .
The name of the debug file is used to identify which source file contains the relevant
.Em token Ns s .
.Pp
If a line after the version information does not contain any number, an unexpected error
has occurred in generating debug information for that byte and no information about a token should
be assumed.
However, a debug file may continue to be parsed even if an empty line is present;
later lines should not be affected by an error for earlier bytes.
.Sh FILES
For a source file
.Pa example.tal ,
the corresponding rom
.Pa example.rom
and debug information file
.Pa example.tal.debug
are created by running:
.Dl uxndebug -g example.tal example.rom
.Sh EXAMPLES
Consider a source file
.Pa test.tal :
.Bd -literal -offset indent -compact
|0100
#ff POP
@end
BRK
.Ed
.Pp
Running the command
.Dl uxndebug -g test.tal test.rom
produces files
.Pa test.tal.debug
and
.Pa test.rom .
.Pp
The file
.Pa test.tal.debug
contains:
.Bd -literal -offset indent -compact
1
2
2
3
4 end
.Ed
where after each number, the new line represents a
.Aq 0x0A
byte.
.Pp
The hexdump of the rom is
.Bd -literal -offset indent -compact
80 ff 02 00
.Ed
.Pp
This means that the first byte in the rom (the first line in
.Pa test.tal.debug
after the version line and blank line, so actually the third line in the file)
was produced by the second token in the source file, and the third byte
in the rom (the 3+2 = fifth line in the debug file) was produced by the third token in the source file,
and so on.
.Sh SEE ALSO
.Xr uxndebug 1
.Sh AUTHORS
.An phoebos Aq Mt ben@bvnf.space
|
