-
Notifications
You must be signed in to change notification settings - Fork 16
Expand file tree
/
Copy pathda65.html
More file actions
934 lines (705 loc) · 32.7 KB
/
da65.html
File metadata and controls
934 lines (705 loc) · 32.7 KB
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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.83">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>da65 Users Guide</TITLE>
</HEAD>
<BODY>
<H1>da65 Users Guide</H1>
<H2>
<A HREF="mailto:uz@cc65.org">Ullrich von Bassewitz</A>,<BR>
<A HREF="mailto:greg.king5@verizon.net">Greg King</A></H2>
<HR>
<EM>da65 is a 6502/65C02 disassembler that is able to read user-supplied
information about its input data, for better results. The output is ready for
feeding into ca65, the macro assembler supplied with the cc65 C compiler.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="da65.html#s1">Overview</A></H2>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="da65.html#s2">Usage</A></H2>
<UL>
<LI><A NAME="toc2.1">2.1</A> <A HREF="da65.html#ss2.1">Command line option overview</A>
<LI><A NAME="toc2.2">2.2</A> <A HREF="da65.html#ss2.2">Command line options in detail</A>
</UL>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="da65.html#s3">Detailed workings</A></H2>
<UL>
<LI><A NAME="toc3.1">3.1</A> <A HREF="da65.html#ss3.1">Supported CPUs</A>
<LI><A NAME="toc3.2">3.2</A> <A HREF="da65.html#ss3.2">Attribute map</A>
<LI><A NAME="toc3.3">3.3</A> <A HREF="da65.html#ss3.3">Labels</A>
<LI><A NAME="toc3.4">3.4</A> <A HREF="da65.html#ss3.4">Info File</A>
</UL>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="da65.html#s4">Info File Format</A></H2>
<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="da65.html#ss4.1">Comments</A>
<LI><A NAME="toc4.2">4.2</A> <A HREF="da65.html#ss4.2">Specifying global options</A>
<LI><A NAME="toc4.3">4.3</A> <A HREF="da65.html#ss4.3">Specifying Ranges</A>
<LI><A NAME="toc4.4">4.4</A> <A HREF="da65.html#ss4.4">Specifying Labels</A>
<LI><A NAME="toc4.5">4.5</A> <A HREF="da65.html#ss4.5">Specifying Segments</A>
<LI><A NAME="toc4.6">4.6</A> <A HREF="da65.html#ss4.6">Specifying Assembler Includes</A>
<LI><A NAME="toc4.7">4.7</A> <A HREF="da65.html#ss4.7">An Info File Example</A>
</UL>
<P>
<H2><A NAME="toc5">5.</A> <A HREF="da65.html#s5">Helper scripts</A></H2>
<P>
<H2><A NAME="toc6">6.</A> <A HREF="da65.html#s6">Copyright</A></H2>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Overview</A></H2>
<P>da65 is a disassembler for 6502/65C02 code. It is supplied as a utility with
the cc65 C compiler and generates output that is suitable for the ca65
macro assembler.</P>
<P>Besides generating output for ca65, one of the design goals was that the user
is able to feed additional information about the code into the disassembler,
for improved results. This information may include the location and size of
tables, and their format.</P>
<P>One nice advantage of this concept is that disassembly of copyrighted binaries
may be handled without problems: One can just pass the information file for
disassembling the binary, so everyone with a legal copy of the binary can
generate a nicely formatted disassembly with readable labels and other
information.</P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">Usage</A></H2>
<H2><A NAME="ss2.1">2.1</A> <A HREF="#toc2.1">Command line option overview</A>
</H2>
<P>The assembler accepts the following options:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
---------------------------------------------------------------------------
Usage: da65 [options] [inputfile]
Short options:
-d Debug mode
-g Add debug info to object file
-h Help (this text)
-i name Specify an info file
-m Run multiple passes to resolve labels
-o name Name the output file
-v Increase verbosity
-F Add formfeeds to the output
-S addr Set the start/load address
-s Accept line markers in the info file
-V Print the disassembler version
Long options:
--argument-column n Specify argument start column
--comment-column n Specify comment start column
--comments n Set the comment level for the output
--cpu type Set cpu type
--debug Debug mode
--debug-info Add debug info to object file
--formfeeds Add formfeeds to the output
--help Help (this text)
--hexoffs Use hexadecimal label offsets
--info name Specify an info file
--label-break n Add newline if label exceeds length n
--mnemonic-column n Specify mnemonic start column
--multi-pass Run multiple passes to resolve labels
--pagelength n Set the page length for the listing
--start-addr addr Set the start/load address
--sync-lines Accept line markers in the info file
--text-column n Specify text start column
--verbose Increase verbosity
--version Print the disassembler version
---------------------------------------------------------------------------
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss2.2">2.2</A> <A HREF="#toc2.2">Command line options in detail</A>
</H2>
<P>Here is a description of all the command line options:</P>
<P>
<DL>
<P>
<A NAME="option--argument-column"></A> </P>
<DT><B><CODE>--argument-column n</CODE></B><DD>
<P>Specifies the column where the argument for a mnemonic or pseudo instruction
starts.</P>
<P>
<A NAME="option--comment-column"></A> </P>
<DT><B><CODE>--comment-column n</CODE></B><DD>
<P>Specifies the column where the comment for an instruction starts.</P>
<P>
<A NAME="option--comments"></A> </P>
<DT><B><CODE>--comments n</CODE></B><DD>
<P>Set the comment level for the output. Valid arguments are 0..4. Greater
values will increase the level of additional information written to the
output file in form of comments.</P>
<P>
<A NAME="option--cpu"></A> </P>
<DT><B><CODE>--cpu type</CODE></B><DD>
<P>Set the CPU type. The option takes a parameter, which may be one of
<UL>
<LI>6502 - NMOS 6502 (all legal instructions)</LI>
<LI>6502X - NMOS 6502 with all undocumented instructions</LI>
<LI>6502DTV - the emulated CPU of the C64DTV device</LI>
<LI>65SC02 - first CMOS instruction set (no bit manipulation, no wai/stp)</LI>
<LI>65C02 - full CMOS instruction set (has bit manipulation and wai/stp)</LI>
<LI>65816 - the CPU of the SNES, and the SCPU</LI>
<LI>HuC6280 - the CPU of the PC engine</LI>
<LI>4510 - the CPU of the Commodore C65</LI>
<LI>45GS02 - the CPU of the Commodore MEGA65</LI>
<LI>M740 - a Microcontroller by Mitsubishi</LI>
</UL>
</P>
<DT><B><CODE>-d, --debug</CODE></B><DD>
<P>Enables debug mode, something that should not be needed for mere
mortals:-)</P>
<P>
<A NAME="option--formfeeds"></A> </P>
<DT><B><CODE>-F, --formfeeds</CODE></B><DD>
<P>Add formfeeds to the generated output. This feature is useful together
with the <CODE>
<A HREF="#option--pagelength">--pagelength</A></CODE> option.
If <CODE>--formfeeds</CODE> is given, a formfeed is added to the output after each
page.</P>
<DT><B><CODE>-g, --debug-info</CODE></B><DD>
<P>This option adds the <CODE>.DEBUGINFO</CODE> command to the output file, so the
assembler will generate debug information when re-assembling the generated
output.</P>
<DT><B><CODE>-h, --help</CODE></B><DD>
<P>Print the short option summary shown above.</P>
<P>
<A NAME="option--hexoffs"></A> </P>
<DT><B><CODE>--hexoffs</CODE></B><DD>
<P>Output label offsets in hexadecimal instead of decimal notation.</P>
<P>
<A NAME="option--info"></A> </P>
<DT><B><CODE>-i name, --info name</CODE></B><DD>
<P>Specify an info file. The info file contains global options that may
override or replace command line options plus information about the code
that has to be disassembled. See the separate section
<A HREF="#infofile">Info File Format</A>.</P>
<P>
<A NAME="option-o"></A> </P>
<DT><B><CODE>-o name</CODE></B><DD>
<P>Specify a name for an output file. The default is to use <CODE>stdout</CODE>, so
without this switch or the corresponding
<A HREF="#global-options">global option</A> <CODE>
<A HREF="#OUTPUTNAME">OUTPUTNAME</A></CODE>,
the output will go to the terminal.</P>
<P>
<A NAME="option--label-break"></A> </P>
<DT><B><CODE>--label-break n</CODE></B><DD>
<P>Adds a newline if the length of a label exceeds the given length.
Note: If the label would run into the code in the mid column, a
linefeed is always inserted regardless of this setting.</P>
<P>This option overrides the
<A HREF="#global-options">global option</A>
<CODE>
<A HREF="#LABELBREAK">LABELBREAK</A></CODE>.</P>
<DT><B><CODE>-m, --multi-pass</CODE></B><DD>
<P>This option causes the disassembler to run multiple passes over the input
binary to find and create all necessary labels. Without this option the
disassembler may detect the necessity for a label in the final pass, when
output was already partially generated. It will output numerical addresses
or program counter relative expressions in this case.</P>
<P>
<A NAME="option--mnemonic-column"></A> </P>
<DT><B><CODE>--mnemonic-column n</CODE></B><DD>
<P>Specifies the column where a mnemonic or pseudo instruction is output.</P>
<P>
<A NAME="option--pagelength"></A> </P>
<DT><B><CODE>--pagelength n</CODE></B><DD>
<P>Sets the length of a listing page in lines. After this number of lines, a
new page header is generated. If the <CODE>
<A HREF="#option--formfeeds">--formfeeds</A></CODE> is also given, a formfeed is inserted before
generating the page header.</P>
<P>A value of zero for the page length will disable paging of the output.</P>
<P>
<A NAME="option--start-addr"></A> </P>
<DT><B><CODE>-S addr, --start-addr addr</CODE></B><DD>
<P>Specify the start/load address of the binary code that is going to be
disassembled. The given address is interpreted as an octal value if
preceded with a '0' digit, as a hexadecimal value if preceded
with '0x', '0X', or '$', and as a decimal value in all other cases. If no
start address is specified, $10000 minus the size of the input file is used.</P>
<P>
<A NAME="option--sync-lines"></A> </P>
<DT><B><CODE>-s, --sync-lines</CODE></B><DD>
<P>Accept line markers in the info file in the following syntax:
<BLOCKQUOTE><CODE>
<PRE>
#line <lineno> ["<filename>"]
# <lineno> "<filename>" [<flag>] ...
</PRE>
</CODE></BLOCKQUOTE>
This option is intended for preprocessing info files with "cpp" or "m4".</P>
<P>
<A NAME="option--text-column"></A> </P>
<DT><B><CODE>--text-column n</CODE></B><DD>
<P>Specifies the column where additional text is output. This additional text
consists of the bytes encoded in this line in text representation.</P>
<DT><B><CODE>-v, --verbose</CODE></B><DD>
<P>Increase the disassembler verbosity. Usually only needed for debugging
purposes. You may use this option more than one time for even more
verbose output.</P>
<DT><B><CODE>-V, --version</CODE></B><DD>
<P>Print the version number of the assembler. If you send any suggestions
or bugfixes, please include the version number.</P>
</DL>
</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Detailed workings</A></H2>
<H2><A NAME="ss3.1">3.1</A> <A HREF="#toc3.1">Supported CPUs</A>
</H2>
<P>With the command line option <CODE>
<A HREF="#option--cpu">--cpu</A></CODE>, the
disassembler may be told which CPU to support:</P>
<P>
<UL>
<LI>6502 - NMOS 6502 (all legal instructions)</LI>
<LI>6502X - NMOS 6502 with all undocumented instructions</LI>
<LI>6502DTV - the emulated CPU of the C64DTV device</LI>
<LI>65SC02 - first CMOS instruction set (no bit manipulation, no wai/stp)</LI>
<LI>65C02 - CMOS with Rockwell extensions</LI>
<LI>W65C02 - full CMOS instruction set (has bit manipulation and wai/stp)</LI>
<LI>65CE02 - CMOS with CSG extensions</LI>
<LI>4510 - the CPU of the Commodore C65</LI>
<LI>45GS02 - the CPU of the Commodore MEGA65</LI>
<LI>HuC6280 - the CPU of the PC engine</LI>
<LI>M740 - a Microcontroller by Mitsubishi</LI>
<LI>65816 - the CPU of the SNES, and the SCPU</LI>
</UL>
</P>
<P>for more details on the various CPUs, see <CODE>
<A HREF="cpus.html">here</A></CODE>.</P>
<H3><A NAME="6502-mode"></A> 6502 mode</H3>
<P>The default (no CPU given on the command line or in the <CODE>GLOBAL</CODE> section of
the info file) is the 6502 CPU. The disassembler knows all "official" opcodes
for this CPU. Invalid opcodes are translated into <CODE>.byte</CODE> commands.</P>
<H3><A NAME="6502X-mode"></A> 6502X mode</H3>
<P>Using 6502X as CPU the illegal opcodes of 6502 CPU are detected and displayed.</P>
<H3><A NAME="DTV-mode"></A> DTV mode</H3>
<P>6502DTV setting recognizes the emulated CPU instructions of the C64DTV device.</P>
<H3><A NAME="65SC02-mode"></A> 65SC02 mode</H3>
<P>The first CMOS instruction set, without bit manipulation or wai/stp.</P>
<H3><A NAME="65C02-mode"></A> 65C02 mode</H3>
<P>The 65C02 understands the same opcodes as the 65SC02, plus 16 additional bit
manipulation and bit test-and-branch commands.</P>
<H3><A NAME="W65C02-mode"></A> W65C02 mode</H3>
<P>This mode also supports wai/stp.</P>
<H3><A NAME="65CE02-mode"></A> 65CE02 mode</H3>
<H3><A NAME="4510-mode"></A> 4510 mode</H3>
<P>When disassembling 4510 code, due to handling of 16-bit wide branches, da65
can produce output that can not be re-assembled, when one or more of those
branches point outside of the disassembled memory. This can happen when text
or binary data is processed.</P>
<H3><A NAME="45GS02-mode"></A> 45GS02 mode</H3>
<P>All compound instructions are supported.</P>
<H3><A NAME="HUC6280-mode"></A> HUC6280 mode</H3>
<P>All special opcodes are supported.</P>
<H3><A NAME="M740-mode"></A> M740 mode</H3>
<P>All special opcodes are supported.</P>
<H3><A NAME="65816-mode"></A> 65816 mode</H3>
<P>The 65816 support requires annotating ranges with the M and X flag states.
This can be recorded with an emulator that supports Code and Data Logging,
for example. Disassemble one bank at a time.</P>
<H2><A NAME="ss3.2">3.2</A> <A HREF="#toc3.2">Attribute map</A>
</H2>
<P>The disassembler works by creating an attribute map for the whole address
space ($0000 - $FFFF). Initially, all attributes are cleared. Then, an
external info file (if given) is read. Disassembly is done in several passes.
In all passes, with the exception of the last one, information about the
disassembled code is gathered and added to the symbol and attribute maps. The
last pass generates output using the information from the maps.</P>
<H2><A NAME="ss3.3">3.3</A> <A HREF="#toc3.3">Labels</A>
</H2>
<P>Some instructions may generate labels in the first pass, while most other
instructions do not generate labels, but use them if they are available. Among
others, the branch and jump instructions will generate labels for the target
of the branch in the first pass. External labels (taken from the info file)
have precedence over internally generated ones. They must be valid identifiers
as specified for the ca65 assembler. Internal labels (generated by the
disassembler) have the form <CODE>Labcd</CODE>, where <CODE>abcd</CODE> is the hexadecimal
address of the label in upper case letters. You should probably avoid using
such label names for external labels.</P>
<H2><A NAME="ss3.4">3.4</A> <A HREF="#toc3.4">Info File</A>
</H2>
<P>The info file is used to pass additional information about the input code to
the disassembler. This includes label names, data areas or tables, and global
options like input and output file names. See the
<A HREF="#infofile">next section</A> for more information.</P>
<H2><A NAME="infofile"></A> <A NAME="s4">4.</A> <A HREF="#toc4">Info File Format</A></H2>
<P>The info file contains lists of specifications grouped together. Each group
directive has an identifying token and an attribute list enclosed in curly
braces. Attributes have a name followed by a value. The syntax of the value
depends on the type of the attribute. String attributes are placed in double
quotes, numeric attributes may be specified as decimal numbers or hexadecimal
with a leading dollar sign. There are also attributes where the attribute
value is a keyword; in this case, the keyword is given as-is (without quotes or
anything). Each attribute is terminated by a semicolon.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
group-name { attribute1 attribute-value; attribute2 attribute-value; }
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="ss4.1">4.1</A> <A HREF="#toc4.1">Comments</A>
</H2>
<P>Comments start with a hash mark (<CODE>#</CODE>) or a double slash (<CODE>//</CODE>)
and extend from the position of the mark to the end of the current line.
Hash marks or double slashes inside of strings will <EM>not</EM> start a comment,
of course.</P>
<H2><A NAME="global-options"></A> <A NAME="ss4.2">4.2</A> <A HREF="#toc4.2">Specifying global options</A>
</H2>
<P>Global options may be specified in a group with the name <CODE>GLOBAL</CODE>. The
following attributes are recognized:</P>
<P>
<DL>
<DT><B><CODE>ARGUMENTCOLUMN</CODE></B><DD>
<P>This attribute specifies the column in the output, where the argument for
an opcode or pseudo instruction starts. The corresponding command line
option is
<CODE>
<A HREF="#option--argument-column">--argument-column</A></CODE>.</P>
<DT><B><CODE>COMMENTCOLUMN</CODE></B><DD>
<P>This attribute specifies the column in the output, where the comment starts
in a line. It is only used for in-line comments. The corresponding command
line option is
<CODE>
<A HREF="#option--comment-column">--comment-column</A></CODE>.</P>
<P>
<A NAME="COMMENTS"></A> </P>
<DT><B><CODE>COMMENTS</CODE></B><DD>
<P>This attribute may be used instead of the <CODE>
<A HREF="#option--comments">--comments</A></CODE> option on the command line. It takes a numerical
parameter between 0 and 4. Higher values increase the amount of information
written to the output file in form of comments.</P>
<DT><B><CODE>CPU</CODE></B><DD>
<P>This attribute may be used instead of the <CODE>
<A HREF="#option--cpu">--cpu</A></CODE> option on the command line. For possible values see
there. The value is a string and must be enclosed in quotes.</P>
<DT><B><CODE>HEXOFFS</CODE></B><DD>
<P>This attribute is followed by a boolean value. If true, offsets to labels are
output in hex, otherwise they're output in decimal notation. The default is
false. The attribute may be changed on the command line using the <CODE>
<A HREF="#option--hexoffs">--hexoffs</A></CODE> option.</P>
<DT><B><CODE>INPUTNAME</CODE></B><DD>
<P>This attribute is followed by a string value, which gives the name of the
input file to read. If it is present, the disassembler does not accept an
input file name on the command line.</P>
<DT><B><CODE>INPUTOFFS</CODE></B><DD>
<P>This attribute is followed by a numerical value that gives an offset into
the input file which is skipped before reading data. The attribute may be
used to skip headers or unwanted code sections in the input file.</P>
<DT><B><CODE>INPUTSIZE</CODE></B><DD>
<P><CODE>INPUTSIZE</CODE> is followed by a numerical value that gives the amount of
data to read from the input file. Data beyond <CODE>INPUTOFFS + INPUTSIZE</CODE>
is ignored.</P>
<P>
<A NAME="LABELBREAK"></A> </P>
<DT><B><CODE>LABELBREAK</CODE></B><DD>
<P><CODE>LABELBREAK</CODE> is followed by a numerical value that specifies the label
length that will force a newline. To have all labels on their own lines,
you may set this value to zero.</P>
<P>See also the <CODE>
<A HREF="#option--label-break">--label-break</A></CODE>
command line option. A <CODE>LABELBREAK</CODE> statement in the info file will
override any value given on the command line.</P>
<DT><B><CODE>MNEMONICCOLUMN</CODE></B><DD>
<P>This attribute specifies the column in the output, where the mnemonic or
pseudo instruction is placed. The corresponding command line option is
<CODE>
<A HREF="#option--mnemonic-column">--mnemonic-column</A></CODE>.</P>
<DT><B><CODE>NEWLINEAFTERJMP</CODE></B><DD>
<P>This attribute is followed by a boolean value. When true, a newline is
inserted after each <CODE>JMP</CODE> instruction. The default is false.</P>
<DT><B><CODE>NEWLINEAFTERRTS</CODE></B><DD>
<P>This attribute is followed by a boolean value. When true, a newline is
inserted after each <CODE>RTS</CODE> instruction. The default is false.</P>
<P>
<A NAME="OUTPUTNAME"></A> </P>
<DT><B><CODE>OUTPUTNAME</CODE></B><DD>
<P>This attribute is followed by string value, which gives the name of the
output file to write. If it is present, specification of an output file on
the command line using the <CODE>
<A HREF="#option-o">-o</A></CODE> option is
not allowed.</P>
<P>The default is to use <CODE>stdout</CODE> for output, so without this attribute or
the corresponding command line option <CODE>
<A HREF="#option-o">-o</A></CODE>
the output will go to the terminal.</P>
<DT><B><CODE>PAGELENGTH</CODE></B><DD>
<P>This attribute may be used instead of the <CODE>
<A HREF="#option--pagelength">--pagelength</A></CODE> option on the command line. It takes a numerical
parameter. Using zero as page length (which is the default) means that no
pages are generated.</P>
<DT><B><CODE>STARTADDR</CODE></B><DD>
<P>This attribute may be used instead of the <CODE>
<A HREF="#option--start-addr">--start-addr</A></CODE> option on the command line. It takes a numerical
parameter. The default for the start address is $10000 minus the size of
the input file. (This assumes that the input file is a ROM that contains the
reset and irq vectors.)</P>
<DT><B><CODE>TEXTCOLUMN</CODE></B><DD>
<P>This attribute specifies the column, where the data bytes are output
translated into ASCII text. It is only used if
<CODE>
<A HREF="#COMMENTS">COMMENTS</A></CODE> is set to at least 4. The
corresponding command line option is
<CODE>
<A HREF="#option--text-column">--text-column</A></CODE>.</P>
</DL>
</P>
<H2><A NAME="ss4.3">4.3</A> <A HREF="#toc4.3">Specifying Ranges</A>
</H2>
<P>The <CODE>RANGE</CODE> directive is used to give information about address ranges. The
following attributes are recognized:</P>
<P>
<DL>
<DT><B><CODE>COMMENT</CODE></B><DD>
<P>This attribute is only allowed if a label is also given. It takes a string
as argument. See the description of the <CODE>
<A HREF="#infofile-label">LABEL</A></CODE> directive for an explanation.</P>
<DT><B><CODE>END</CODE></B><DD>
<P>This gives the end address of the range. The end address is inclusive, that
means, it is part of the range. Of course, it may not be smaller than the
start address. Optionally, the end may be given as a decimal offset instead
of an absolute address, "+3", to specify it as a size.</P>
<DT><B><CODE>NAME</CODE></B><DD>
<P>This is a convenience attribute. It takes a string argument and will cause
the disassembler to define a label for the start of the range with the
given name so a separate <CODE>
<A HREF="#infofile-label">LABEL</A></CODE>
directive is not needed.</P>
<DT><B><CODE>START</CODE></B><DD>
<P>This gives the start address of the range.</P>
<DT><B><CODE>TYPE</CODE></B><DD>
<P>This attribute specifies the type of data within the range. The attribute
value is one of the following keywords:</P>
<P>
<DL>
<DT><B><CODE>ADDRTABLE</CODE></B><DD>
<P>The range consists of data and is disassembled as a table of words
(16 bit values). The difference to the <CODE>WORDTABLE</CODE> type is that
a label is defined for each entry in the table.</P>
<DT><B><CODE>BYTETABLE</CODE></B><DD>
<P>The range consists of data and is disassembled as a byte table.</P>
<DT><B><CODE>CODE</CODE></B><DD>
<P>The range consists of code.</P>
<DT><B><CODE>DBYTETABLE</CODE></B><DD>
<P>The range consists of data and is disassembled as a table of dbytes
(double byte values, 16 bit values with the low byte containing the
most significant byte of the 16 bit value).</P>
<DT><B><CODE>DWORDTABLE</CODE></B><DD>
<P>The range consists of data and is disassembled as a table of double
words (32 bit values).</P>
<DT><B><CODE>RTSTABLE</CODE></B><DD>
<P>The range consists of data and is disassembled as a table of words (16 bit
values). The values are interpreted as words that are pushed onto the
stack and jump to it via <CODE>RTS</CODE>. This means that they contain
<CODE>address-1</CODE> of a function, for which a label will get defined by the
disassembler.</P>
<DT><B><CODE>SKIP</CODE></B><DD>
<P>The range is simply ignored when generating the output file. Please note
that this means that reassembling the output file will <EM>not</EM> generate
the original file, not only because of the missing piece in between, but
also because the following code will be located on wrong addresses. Output
generated with <CODE>SKIP</CODE> ranges will need manual rework.</P>
<DT><B><CODE>TEXTTABLE</CODE></B><DD>
<P>The range consists of readable text.</P>
<DT><B><CODE>WORDTABLE</CODE></B><DD>
<P>The range consists of data and is disassembled as a table of words
(16 bit values).</P>
</DL>
</P>
<DT><B><CODE>UNIT</CODE></B><DD>
<P>Split the table into sections of this size. For example, if you have a
ByteTable of size 48, but it has logical groups of size 16, specifying
16 for UNIT adds newlines after every 16 bytes. UNIT is always in bytes.</P>
<DT><B><CODE>ADDRMODE</CODE></B><DD>
<P>When disassembling 65816 code, this specifies the M and X flag states
for this range. It's a string argument of the form "mx". Capital letters
mean the flag is enabled.</P>
</DL>
</P>
<H2><A NAME="infofile-label"></A> <A NAME="ss4.4">4.4</A> <A HREF="#toc4.4">Specifying Labels</A>
</H2>
<P>The <CODE>LABEL</CODE> directive is used to give names for labels in the disassembled
code. The following attributes are recognized:</P>
<P>
<DL>
<DT><B><CODE>ADDR</CODE></B><DD>
<P>Followed by a numerical value. Specifies the value of the label.</P>
<DT><B><CODE>COMMENT</CODE></B><DD>
<P>Attribute argument is a string. The comment will show up in a separate line
before the label, if the label is within code or data range, or after the
label if it is outside.</P>
<P>Example output:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
foo := $0001 ; Comment for label named "foo"
; Comment for label named "bar"
bar:
</PRE>
</CODE></BLOCKQUOTE>
</P>
<DT><B><CODE>NAME</CODE></B><DD>
<P>The attribute is followed by a string value which gives the name of the
label. Empty names are allowed; in this case the disassembler will create
an unnamed label. (See the assembler docs for more information about unnamed
labels.)</P>
<DT><B><CODE>SIZE</CODE></B><DD>
<P>This attribute is optional and may be used to specify the size of the data
that follows. If a size greater than 1 is specified, the disassembler will
create labels in the form <CODE>label+offs</CODE> for all bytes within the given
range, where <CODE>label</CODE> is the label name given with the <CODE>NAME</CODE>
attribute, and <CODE>offs</CODE> is the offset within the data.</P>
<DT><B><CODE>PARAMSIZE</CODE></B><DD>
<P>This optional attribute is followed by a numerical value. It tells the
assembler that subroutine calls to this label are followed by
"inline parameters" with the given number of bytes, like this:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
JSR LabelWithParamSize2
.byte $00, $10
(return here)
code...
</PRE>
</CODE></BLOCKQUOTE>
</P>
</DL>
</P>
<H2><A NAME="infofile-segment"></A> <A NAME="ss4.5">4.5</A> <A HREF="#toc4.5">Specifying Segments</A>
</H2>
<P>The <CODE>SEGMENT</CODE> directive is used to specify a segment within the
disassembled code. The following attributes are recognized:</P>
<P>
<DL>
<DT><B><CODE>START</CODE></B><DD>
<P>This attribute is followed by a numerical value which specifies the start
address of the segment.</P>
<DT><B><CODE>END</CODE></B><DD>
<P>This attribute is followed by a numerical value which specifies the end
address of the segment. The end address is the last address that is a part of
the segment.</P>
<DT><B><CODE>NAME</CODE></B><DD>
<P>This attribute is followed by a string value which gives the name of the
segment.</P>
</DL>
</P>
<P>All attributes are mandatory. Segments must not overlap. The disassembler will
change back to the (default) <CODE>.code</CODE> segment after the end of each defined
segment. That might not be what you want. As a rule of thumb, if you're using
segments, you should define segments for all disassembled code.</P>
<H2><A NAME="infofile-asminc"></A> <A NAME="ss4.6">4.6</A> <A HREF="#toc4.6">Specifying Assembler Includes</A>
</H2>
<P>The <CODE>ASMINC</CODE> directive is used to give the names of input files containing
symbol assignments in assembler syntax:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
Name = value
Name := value
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>The usual conventions apply for symbol names. Values may be specified as hex
(leading $), binary (leading %) or decimal. The values may optionally
be signed.</P>
<P>NOTE: The include file parser is very simple. Expressions are not allowed, and
anything but symbol assignments is flagged as an error (but see the
<CODE>IGNOREUNKNOWN</CODE> directive below).</P>
<P>The following attributes are recognized:</P>
<P>
<DL>
<DT><B><CODE>FILE</CODE></B><DD>
<P>This attribute is followed by a string value. It specifies the name of the
file to read.</P>
<DT><B><CODE>COMMENTSTART</CODE></B><DD>
<P>This optional attribute is followed by a character constant. It specifies the
character that starts a comment. The default value is a semicolon. This
value is ignored if <CODE>IGNOREUNKNOWN</CODE> is true.</P>
<DT><B><CODE>IGNOREUNKNOWN</CODE></B><DD>
<P>This attribute is optional and is followed by a boolean value. It allows to
ignore input lines that don't have a valid syntax. This allows to read in
assembler include files that contain more than just symbol assignments.
Note: When this attribute is used, the disassembler will ignore any errors
in the given include file. This may have undesired side effects.</P>
</DL>
</P>
<H2><A NAME="ss4.7">4.7</A> <A HREF="#toc4.7">An Info File Example</A>
</H2>
<P>The following is a short example for an info file that contains most of the
directives explained above:</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
# This is a comment. It extends to the end of the line
GLOBAL {
OUTPUTNAME "kernal.s";
INPUTNAME "kernal.bin";
STARTADDR $E000;
PAGELENGTH 0; # No paging
CPU "6502";
};
# One segment for the whole stuff
SEGMENT { START $E000; END $FFFF; NAME "kernal"; };
RANGE { START $E612; END $E631; TYPE Code; };
RANGE { START $E632; END $E640; TYPE ByteTable; };
RANGE { START $EA51; END $EA84; TYPE RtsTable; };
RANGE { START $EC6C; END $ECAB; TYPE RtsTable; };
RANGE { START $ED08; END $ED11; TYPE AddrTable; };
# Zero-page variables
LABEL { NAME "fnadr"; ADDR $90; SIZE 3; };
LABEL { NAME "sal"; ADDR $93; };
LABEL { NAME "sah"; ADDR $94; };
LABEL { NAME "sas"; ADDR $95; };
# Stack
LABEL { NAME "stack"; ADDR $100; SIZE 255; };
# Indirect vectors
LABEL { NAME "cinv"; ADDR $300; SIZE 2; }; # IRQ
LABEL { NAME "cbinv"; ADDR $302; SIZE 2; }; # BRK
LABEL { NAME "nminv"; ADDR $304; SIZE 2; }; # NMI
# Jump table at end of kernal ROM
LABEL { NAME "kscrorg"; ADDR $FFED; };
LABEL { NAME "kplot"; ADDR $FFF0; };
LABEL { NAME "kiobase"; ADDR $FFF3; };
LABEL { NAME "kgbye"; ADDR $FFF6; };
# Hardware vectors
LABEL { NAME "hanmi"; ADDR $FFFA; };
LABEL { NAME "hares"; ADDR $FFFC; };
LABEL { NAME "hairq"; ADDR $FFFE; };
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="s5">5.</A> <A HREF="#toc5">Helper scripts</A></H2>
<P><CODE>util/parse-bsnes-log.awk</CODE> is a supplied script for 65816 disassembly,
to parse bsnes-plus Code-Data log files and output the RANGE sections
for your info file. For typical usage, you'd check the S-CPU log and trace
log mask boxes in the bsnes-plus debugger, play through the game, then grep
for the bank you're disassembling, and pass that to this script.</P>
<P>
<BLOCKQUOTE><CODE>
<PRE>
grep ^83 my-game-log | parse-bsnes-log.awk
</PRE>
</CODE></BLOCKQUOTE>
</P>
<H2><A NAME="s6">6.</A> <A HREF="#toc6">Copyright</A></H2>
<P>da65 (and all cc65 binutils) is (C) Copyright 1998-2011, Ullrich von
Bassewitz. For usage of the binaries and/or sources, the following
conditions do apply:</P>
<P>This software is provided 'as-is', without any expressed or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.</P>
<P>Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:</P>
<P>
<OL>
<LI> The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.</LI>
<LI> Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.</LI>
<LI> This notice may not be removed or altered from any source
distribution.</LI>
</OL>
</P>
</BODY>
</HTML>