/[projet1]/public/pc/tools/osdk/main/Osdk/_final_/documentation/doc_assembler.htm
Defence Force logotype

Contents of /public/pc/tools/osdk/main/Osdk/_final_/documentation/doc_assembler.htm

Parent Directory Parent Directory | Revision Log Revision Log


Revision 70 - (show annotations)
Sun May 24 19:53:20 2009 UTC (10 years, 6 months ago) by dbug
File MIME type: text/html
File size: 15199 byte(s)
Added the complete source code of the OSDK.
Projects files are available for Visual Studio 6 and .net, plus a Code::Blocks setup (everything works except PictConv that relies on FreeImage - which does not build correctly on mingw)
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
2
3 <HTML lang=fr dir=ltr>
4 <HEAD>
5 <meta name="robots" content="noindex">
6 <meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1">
7 <title>OSDK - The assembler</title>
8 <link href="documentation.css" rel="stylesheet" type="text/css">
9 </HEAD>
10
11 <BODY>
12
13 <hr>
14 <A href="documentation.htm"><img src="arrow_back.gif"></A>
15 <img src="pics/osdk_logo_small.png">
16 <hr>
17
18 <h1>The assembler</h1>
19
20 <p id=chapter>Description</p>
21
22 </p>XA supports both the standard 6502 opcodes as well as the CMOS versions
23 (Rockwell 65c02). Not supported are the 6502 undocumented opcodes, they have
24 to be put in by hand (with ".byte" directives).
25 </p>
26
27
28
29 <p id=chapter>Parameters and features</p>
30
31 <p>The assembler contains only a single programm called "xa".
32 It takes one or more Source files into one object file, that can directly
33 be used.
34 But the assembler also has a mode to produce relocatable files, conforming
35 to the 'o65' fileformat (See fileformat.txt).
36 </p>
37 <p>
38 Call:
39 </p>
40 <pre>
41 xa [options] Source1 [Source2 ...]
42 </pre>
43 Object: this is the name, the output (object) file gets
44 Error: Here you will find the Error listing.
45 Label: this is the label list
46 <p>
47
48 <pre>
49 '-C' gives error codes when using CMOS-opcodes. Default is not to complain.
50 '-c' do not produce o65 executable, but object files that can contain undefined references.
51 '-v' go into verbose mode
52 '-R' do not produce absolute code, but do relocation and all that.
53 '-o filename' set output filename
54 '-e filename' set errorlog filename
55 '-l filename' set labellist filename
56 '-r' add crossreference list to labellist output (i.e list of filename/line where label is used)
57 '-M' allow ':' to appear in comments after a semicolon (MASM mode)
58 '-b? adr' set segment start address for ? = t(ext), d(ata), b(ss) or z(ero) segment.
59 '-A adr' If the _file_ starts at adr in a ROM, then the text segment need not be relocated.
60 That of course only works, if the data/bss/zero segments are not occupied by other programs too!
61 '-G' omit writing the exported globals to the file.
62 '-B' Show lines with '.(' or '.)' pseudo opcodes
63 '-Llabel' defines 'label' as absolute, undefined reference
64 '-DDEF=TEXT' define a preprocessor replacement
65 '-Ipath' additional include path for include files. Is evaluated before
66 the XAINPUT environment variable. One path per '-I',
67 multiple '-Ipath' allowed.
68 </pre>
69
70 Omitting the errorfile or labelfile Parameter will cause xa to not
71 write these files. Using '-x' will cause xa to take the name of the
72 first source file and change the extension (on an Atari there is only
73 one, like in DOS) to 'obj', 'err' and 'lab' respectively - if the old
74 behaviour is selected with the '-x' option or the files are defined with
75 "-l" and "-e". If no output file is given, "a.o65" is used.
76 <p>
77
78
79 <p id=chapter>Environment variables</p>
80
81 You can use the variables XAOUTPUT and XAINPUT to adjust the directory
82 structure. If source or include files are not found, the Path in XAINPUT
83 is being searched for the files. The different paths are separated by a
84 comma (','). XAINPUT gives the directory where the *.obj, *.err and
85 *.lab files are put.
86 If they are not set, there will be no search, respectively the files
87 are saved to the current directory.
88 <p>
89 The label file is a readable ASCII-file and lists all the labels
90 together with their block-count (see below) and their address.
91 The error file lists the version of the assembler, date and time of the
92 assembler run, all the error messages and the stuff being printed
93 with #echo and #print and last but not least a statistics of used
94 resources.
95
96
97
98
99
100 <p id=chapter>Some specific details</p>
101
102 When using addressing modes that could be zeropage or absolute, zeropage
103 will be taken if possible. This can be prevented by prefixing the address
104 with a '!'. Then absolute addressing is taken, regardless of the address.
105 <p>
106 Values or Addresses can be expressed by arithmetik expressions with
107 hierachy and bracket. The following operands are understood:
108 <p><pre>
109 123 -decimal
110 $234 -hexadecimal
111 &123 -octal
112 %010110 -binary
113 * -program counter
114 "A" -ASCII-code
115 labelx -label
116 -(lab1+1) -expression
117 </pre>
118 The following operands can be used (third column is priority):
119 <p><pre>
120 + -addition 9
121 - -subtraction 9
122 * -multiplication 10
123 / -integer-division 10
124 &lt;&lt; -shift left 8
125 &gt;&gt; -shift right 8
126 &gt;=,=&gt; -more or equal 7
127 &lt;=,=&lt; -less or equal 7
128 &lt; -less 7
129 &gt; -more 7
130 = -equal 6
131 &lt;&gt;,&gt;&lt; -not equal 6
132 && -logical AND 2
133 || -Logical OR 1
134 & -Bitwise AND 5
135 | -Bitwise OR 3
136 ^ -Bitwise XOR 4
137 </pre>
138 Operators with higher priority are evaluated first.
139 Brackets can be used as usual.
140 <p>
141 Valid expressions are, e.g.:
142 <p><pre>
143 LDA base+number*2,x
144 </pre>
145 For Addressing modes that do not start with a bracket, you can even use
146 a bracket at the beginning of an expression. Otherwise try this:
147 <p><pre>
148 LDX (1+2)*2,y ; Wrong!
149 LDX 2*(1+2),y ; Right!
150 </pre>
151 Before an expression you can use these unitary operators:
152 <p><pre>
153 &lt; Gives the low byte of the expression
154 &gt; Gives the high byte
155
156 LDA #&lt;adresse
157 </pre>
158 Single Assembler statements are being separated by a ':' (You remember
159 the C64 :-) or a newline. Behind Each statement, separated by a ';'
160 you can write some comments. The next colon or a newline ends the
161 comment and starts a new statement.
162 In MASM compatibility mode ('-M' command line option), then a colon
163 in a comment is ignored, i.e. the comment lasts till the newline.
164 <p>
165 <h3> Pseudo opcodes, Block structures and where Labels are valid </h3>
166
167 In addition to the 6502 opcodes you have the following Pseudo opcodes:
168
169 <ul>
170 <li>
171 <b>'.byt'</b> and <b>'.asc'</b> are identical and save values to the memory (object file) bytewise.
172 <pre>
173 .byt value1,value2,value3, ...
174 .asc "text1","text2", ...</pre>
175 </li>
176
177 <li>
178 <b>'.word'</b> does the same with words (2 Bytes).
179 <pre>
180 .word value1,value2, ...</pre>
181 </li>
182
183 <li>
184 <b>'.dsb'</b> fills a block with a given length with the value of fillbyte.
185 If fillbyte is not given, zero is taken.
186 <pre>
187 .dsb length ,fillbte</pre>
188 </li>
189
190 <li>
191 <b>'*='</b> changes the programm counter.
192 The programm counter is not saved to the file as no rewind is being done.
193 Just the internal counter is reloaded.
194 If a value is given when the assembler has been started in relocation mode
195 ('-R command line option), the assembler goes into no-relocation mode, i.e
196 assembles everything without creating relocation table entries.
197 For '*=' without a value, the assembler switches back to relocation mode.
198 The absolute code is 'embedded' in the text segment, so the text segment
199 program counter is increased by the length of the absolute code.
200
201 <p>One usage of this feature is for example to set the adress of buffers in BSS in the overlay memory on the oric:
202 <pre>
203 .bss
204 *=$C000
205 BigBuffer .dsb 256</pre>
206
207 </p>
208 </li>
209
210 <li>
211 <b>'.('</b> opens a new 'block'. All labels in a block are local, i.e.
212 are only visible from inside the block - including sub-blocks.
213 An error is returned if a label is defined that is already defined
214 'above'.
215 </li>
216
217 <li>
218 With <b>'.)'</b> the block is closed. You can have a stack of up to 16 blocks
219 in each other (i.e. 16 times '.(' before the first '.)' will work, 17 not).
220 </li>
221
222 <li>
223 <b>'.text'</b>, <b>'.data'</b>, <b>'.bss'</b>, <b>'.zero'</b> switch between the different segments.
224 <ul>
225 <li>The text segment is where the code goes in.</li>
226 <li>The data segment is where some initialized data goes in (it's actually like a second text segment).</li>
227 <li>The data segment might be allocated separated from the text segment.</li>
228 <li>The contents of the bss and the zero segment are not saved, just the labels are evaluated. Here goes the uninitialized data stuff.</li>
229 <li>The zero segment allows allocation of zeropage space, bss is normal address space.</li>
230 </ul>
231 These opcodes can be used in relative and absolute mode.
232 </li>
233
234 <li>
235 <b>'.align'</b> aligns the current segment to a byte boundary given by the value.
236 Allowed values are 2, 4, and 256.
237 When using relative mode, the align value is written to the file header, such that relocation keeps the alignment.
238 <p>Note: It seems that this directive is totaly bugged, at least I never managed to ge it to do what I wanted to do.
239 Since one of the most common use of allignement on the 6502 is to allign data on a multiple of 256 bytes (page), it's possible
240 to hack around by using this work around:
241 </p>
242 <pre>
243 .dsb 256-(*&255)
244 // The program counter from this point is alligned on the next multiple of 256</pre>
245 </li>
246
247 <li>
248 <b>'.fopt'</b> works like ".byte", but saves the bytes as a fileoption (see
249 fileformat.txt). The length is computed automatically, so the first
250 byte in the ".fopt" list of values should be the type.
251 For example, the following line sets the filename for the object file.
252 <p><pre>
253 .fopt 0, "filename", 0
254 </pre>
255 </li>
256 </ul>
257
258 <h3>Labels</h3>
259
260 A label is defined by not being an opcode:
261 <p><pre>
262 label1 LDA #0 ; assignes the programm counter
263 label2 =1234 ; explicit definition
264 label3 label4 label5 ; implicit programm counter
265 label6 label7 = 3 ; label6 becomes the program counter, while
266 ; label7 is set to 3
267 label8: sta label2 ; As ':' divides opcodes, this is also
268 ; working
269 </pre>
270 You can use more than one label for definition, except for explicit
271 definition.
272 <ul>
273 <li>Labels are case sensitive.
274 </li>
275 <li>If a label is proceeded by a '+', this label is defined global.
276 </li>
277 <li>If a label is proceeded by a '&', this label is defined one level 'up'
278 in the block hierachy, and you can use more than one '&'.
279 </li>
280 <li>Redefinition of a label is possible by proceeding it with a dash '-':
281 <p>
282 <p><pre>
283 -sysmem +=4 ; here you can use ==, +=, -=, *=, /=, &=, |=
284 -syszp =123
285 </pre>
286 </li>
287 </ul>
288
289 <h3> Preprocessor </h3>
290
291 The preprocessor is very close to the one of the language C.
292 So in addition to the ';'-comments you can also use C-like
293 comments in '/*' and '*/'. Comments can be nested.
294 <p><pre>
295 #include "filename" includes a file on exactly this position.
296 if the file is not found, it is searched using
297 XAINPUT.
298
299 #echo comment gives a comment to the error file.
300
301 #file "filename" Set the internal line counter in order to get correct line numbers at link phase
302
303 #print expression prints an expression to the error file (after preprocessing and calculating)
304
305 #printdef DEFINED prints the definition of a preprocessor define to the error file.
306
307 #define DEF text defines 'DEF' by 'text'
308
309 #ifdef DEF The source code from here to the following #endif
310 or #else is only assembled if 'DEF' is defined
311 with #define.
312
313 #else just else... (optionally)
314
315 #endif ends an #if-construct. This is a must to end #IF*
316
317 #ifndef DEF .... if DEF is not defined
318
319 #if expression .... if expression is not zero
320
321 #iflused label .... if a label has already been used
322
323 #ifldef label .... if a label is already defined
324 </pre>
325 #iflused and #ifldef work an labels, not on preprocessor defs! With these
326 commands a kind of library is easily built:
327 <p><pre>
328 #iflused label
329 #ifldef label
330 #echo label already defined, not from library
331 #else
332 label lda #0
333 ....
334 #endif
335 #endif
336 </pre>
337 You can have up to 15 #if* on stack before the first #endif
338 <p>
339 You can also use #define with functions, like in C.
340 <p><pre>
341 #define mult(a,b) ((a)*(b))
342 </pre>
343 The preprocessor also allows continuation lines. I.e. lines that end
344 with a '\' directly before the newline have the following line
345 concatenated to it.
346 <p>
347
348 <p id=chapter>Historic</p>
349
350 <p>Here is the list of all releases with a short description of things that changed:
351 </p>
352
353 <p id=dateentry>2.1.7</p>
354 - removed the '-x' switch from XA code. I will progressively remove all the legacy stuff when replacement features already exist, in this case -o, -e and -l
355
356 <p id=dateentry>2.1.6</p>
357 - debogged the #file directive that was actually giving valid file names only for the errors that happened during pass 1.
358
359 <p id=dateentry>2.1.5</p>
360 - added a #file directive<br>
361 - corrected some error messages<br>
362
363 <p id=dateentry>2.1.4h (25nov1998)</p>
364 - preprocessor fix, improve file65.
365
366 <p id=dateentry>2.1.4g (25nov1998)</p>
367 - fix "!" addressing syntax, add reference list for labels.
368
369 <p id=dateentry>2.1.4f (21apr1998)</p>
370 - cross-compilable for DOS with make dos
371
372 <p id=dateentry>2.1.4e</p>
373 - some bugfixes concerning o65 fileformat, as well as a fileformat change.
374
375 <p id=dateentry>2.1.4</p>
376 - preprocessor understands continuation lines, more command line options available.
377
378 <p id=dateentry>2.1.3</p>
379 - a new feature of the fileformat: aligned segments. Segments can be aligned to 2, 4, or 256 byte address boundary.
380 A new pseudo-opcode has been introduced, ".align", that aligns the address in the current segment to the value given.
381 ".align 4" aligns the segment address to a 4-byte boundary.
382
383 Also the pseudo-opcodes ".data", ".bss", ".zero" and ".text" to switch segments can now be used in absolute mode,
384 i.e. when started without relocation. They work as they do in relative mode, but the data segment is discarded
385 (this might change in the future, but currently it doesn't work) and no relocation tables or label tables and no
386 o65 file header are written.
387 Advantages are that you can use the same code base for relative and absolute mode programs, and you don't have to manage the variable space yourself.
388
389
390
391 <p id=dateentry>2.1.2a</p>
392 - linker, relocator and file utility for 'o65' format included, some bugs fixed.
393
394 <p id=dateentry>2.1.1e</p>
395 - started supporting the 'o65' file format
396
397 <p id=dateentry>2.0.7d</p>
398 - now understands the #undef preprocessor directive.
399
400 <p id=dateentry>Version 2.0.7.c</p>
401 - the include statements can now contain '\' or '/' as directory separator, and both are accepted (with DIRCHAR='/').
402
403
404 <hr>
405 <A href="documentation.htm"><img src="arrow_back.gif"></A>
406 <img src="pics/osdk_logo_small.png">
407 <hr>
408
409 </BODY>
410 </HTML>
411
412

  ViewVC Help
Powered by ViewVC 1.1.26