OpenCores
URL https://opencores.org/ocsvn/open8_urisc/open8_urisc/trunk

Subversion Repositories open8_urisc

[/] [open8_urisc/] [trunk/] [Open8 Tools/] [README.2.OPEN8_AS.txt] - Blame information for rev 264

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 178 jshamlet
----------------------------------------------
2
PV2ASSembler Documentation - Index
3
----------------------------------------------
4
 
5
1..... Introduction
6
2..... Assembler Directives
7
3..... Assembler Syntax
8
 3.1.. Case Sensitivity
9
 3.2.. Comments
10
 3.3.. Labels
11
 3.4.. Number Types
12
 3.5.. Strings
13
 3.6.. Mnemonics
14
4..... Error Messages
15
5..... Bugs
16
6..... Temporary Files
17
7..... Compiling
18
 7.1.. Compiling Object Files
19
 7.2.. Compiling Library Files
20
8..... Linking
21
9..... Arithmetics
22
10.... PV2 Flags
23
11.... Good things to know about PV2
24
12.... Legal Note
25
 
26
 
27
----------------------------------------------
28
1.... Introduction
29
----------------------------------------------
30
 
31
This assembler was originally based on the WLA Assembler that can create
32
machine code for a boatload of retro consoles. It's really a piece of quality
33
work, and an indespensible tool for retro-console hackers.
34
 
35
The original WLA assembler can be found at http://www.iki.fi/~vhelin/wla.html
36
Please don't bother Ville Helin if PV2ASS does something wrong. No doubt I've
37
introduced a bug or two when I modified it for v8 uRISC code.
38
 
39
I forked WLA because I needed an assembler that supported the V8 uRISC
40
CPU which is the heart of the excellent single-use digital PV2 cameras,
41
available from RITZ and CVS Pharmacies for $20 at the time of this writing.
42
WLA is strong featurewise, so I thought that modding the WLA code would
43
provide a great assembler with very little time cost to me.
44
 
45
BTW, for more information on the most excellent PV2 camera, check out
46
the threads at http://www.linux-hacker.net/cgi-bin/UltraBoard/UltraBoard.pl?Action=ShowBoard&Board=cameras
47
 
48
This assembler is my attempt to create a dev community interested in extending
49
the firmware within camera itself - it's hard to write large programs when
50
you're hand-assembling code.
51
 
52
One last note - this documentation is based heavily on the original
53
WLA docs, with information not pertainent to the PV2/v8uRISC being removed.
54
However, there are still some game-references in the Directive examples, and
55
a lot of the sample assembly in this doc isn't v8uRISC code. This is a small
56
price to pay for such a strong assembler, but if it really bugs you, feel
57
free to update this doc and send the results to billwiley777@gmail.com!
58
 
59
 
60
----------------------------------------------
61
2.... Assembler Directives
62
----------------------------------------------
63
 
64
Here are the supported directives (with examples) in PV2ASS:
65
 
66
      .ASC "HELLO WORLD!"
67
      .ASCTABLE
68
      .ASCIITABLE
69
      .ASM
70
      .BR
71
      .BREAKPOINT
72
      .BYT 100, $30, %1000, "HELLO WORLD!"
73
      .DB 100, $30, %1000, "HELLO WORLD!"
74
      .DBCOS 0.2, 10, 3.2, 120, 1.3
75
      .DBRND 20, 0, 10
76
      .DBSIN 0.2, 10, 3.2, 120, 1.3
77
      .DEFINE IF $FF0F
78
      .DEF IF $FF0F
79
      .DS 256, $10
80
      .DSB 256, $10
81
      .DSTRUCT waterdrop INSTANCEOF water DATA "tingle", 40, 120
82
      .DSW 128, 20
83
      .DW 16000, 10, 255
84
      .DWCOS 0.2, 10, 3.2, 1024, 1.3
85
      .DWRND 20, 0, 10
86
      .DWSIN 0.2, 10, 3.2, 1024, 1.3
87
      .ELSE
88
      .EMPTYFILL $C9
89
      .ENDASM
90
      .ENDB
91
      .ENDE
92
      .ENDIF
93
      .ENDM
94
      .ENDME
95
      .ENDR
96
      .ENDRO
97
      .ENDS
98
      .ENDST
99
      .ENUM $C000
100
      .EQU IF $FF0F
101
      .FAIL
102
      .FCLOSE FP_DATABIN
103
      .FOPEN "data.bin" FP_DATABIN
104
      .FREAD FP_DATABIN DATA
105
      .FSIZE FP_DATABIN SIZE
106
      .IF DEBUG == 2
107
      .IFDEF IF
108
      .IFDEFM \2
109
      .IFEQ DEBUG 2
110
      .IFEXISTS "main.s"
111
      .IFGR DEBUG 2
112
      .IFGREQ DEBUG 1
113
      .IFLE DEBUG 2
114
      .IFLEEQ DEBUG 1
115
      .IFNDEF IF
116
      .IFNDEFM \2
117
      .IFNEQ DEBUG 2
118
      .INCBIN "sorority.bin"
119
      .INCDIR "/usr/programming/gb/include/"
120
      .INCLUDE "cgb_hardware.i"
121
      .INPUT NAME
122
      .MACRO TEST
123
      .ORG $150
124
      .OUTNAME "other.o"
125
      .PRINTT "Here we are...\n"
126
      .PRINTV DEC DEBUG+1
127
      .REDEFINE IF $F
128
      .REDEF IF $F
129
      .REPEAT 6
130
      .REPT 6
131
      .SEED 123
132
      .SECTION "Init" FORCE
133
      .SHIFT
134
      .STRUCT enemy_object
135
      .SYM SAUSAGE
136
      .SYMBOL SAUSAGE
137
      .UNDEFINE DEBUG
138
      .UNDEF DEBUG
139
      .WORD 16000, 10, 255
140
 
141
 
142
Descriptions:
143
 
144
----
145
.ASM
146
----
147
 
148
Tells PV2 to start assembling. Use .ASM to continue the work which has been
149
disabled with .ENDASM. .ASM and .ENDASM can be used to mask away big blocks
150
of code. This is analogous to the ANSI C -comments (/*...*/), but .ASM and
151
.ENDASM can be nested, unlike the ANSI C -counterpart.
152
 
153
This is not a compulsory directive.
154
 
155
-------
156
.ENDASM
157
-------
158
 
159
Tells PV2 to stop assembling. Use .ASM to continue the work.
160
 
161
This is not a compulsory directive.
162
 
163
----------------
164
.DBRND 20, 0, 10
165
----------------
166
 
167
Defines bytes, just like .DSB does, only this time they are filled with
168
(pseudo) random numbers. We use stdlib's rand() to generate the random
169
numbers. If you want to seed the random number generator, use .SEED.
170
 
171
The first parameter (20 in the example) defines the amount of numbers
172
we want to generate. The next two tell the range of the random numbers,
173
i.e. min and max.
174
 
175
Here's how it works:
176
 
177
.DBRND A, B, C
178
 
179
for (i = 0; i < A; i++)
180
  output_data((rand() % (C-B+1)) + B);
181
 
182
This is not a compulsory directive.
183
 
184
----------------
185
.DWRND 20, 0, 10
186
----------------
187
 
188
Analogous to .DBRND (but defines words).
189
 
190
This is not a compulsory directive.
191
 
192
-----------------------------
193
.DBCOS 0.2, 10, 3.2, 120, 1.3
194
-----------------------------
195
 
196
Defines bytes just like .DSB does, only this time they are filled with
197
cosine data. .DBCOS takes five arguments.
198
 
199
The first argument is the starting angle. Angle value ranges from 0 to
200
359.999..., but you can supply PV2 with values that are out of the range -
201
PV2 fixes them ok. The value can be integer or float.
202
 
203
The second one descibes the amount of additional angles. The example
204
will define 11 angles.
205
 
206
The third one is the adder value which is added to the angle value when
207
next angle is calculated. The value can be integer or float.
208
 
209
The fourth and fifth ones can be seen from the pseudo code below, which
210
also describes how .DBCOS works. The values can be integer or float.
211
 
212
Remember that cos (and sin) here returns values ranging from -1 to 1.
213
 
214
.DBCOS A, B, C, D, E
215
 
216
for (B++; B > 0; B--) {
217
  output_data((D * cos(A)) + E)
218
  A = keep_in_range(A + C)
219
}
220
 
221
This is not a compulsory directive.
222
 
223
-----------------------------
224
.DBSIN 0.2, 10, 3.2, 120, 1.3
225
-----------------------------
226
 
227
Analogous to .DBCOS, but does sin() instead of cos().
228
 
229
This is not a compulsory directive.
230
 
231
------------------------------
232
.DWCOS 0.2, 10, 3.2, 1024, 1.3
233
------------------------------
234
 
235
Analogous to .DBCOS (but defines words).
236
 
237
This is not a compulsory directive.
238
 
239
------------------------------
240
.DWSIN 0.2, 10, 3.2, 1024, 1.3
241
------------------------------
242
 
243
Analogous to .DBCOS (but defines words and does sin() instead of cos()).
244
 
245
This is not a compulsory directive.
246
 
247
--------------
248
.EMPTYFILL $C9
249
--------------
250
 
251
This byte is used in filling the unused areas of memory. EMPTYFILL
252
defaults to $00.
253
 
254
This is not a compulsory directive.
255
 
256
--------------------------------------
257
.INCDIR "/usr/programming/pv2/include/"
258
--------------------------------------
259
 
260
Changes the current include root directory. Use this to specify main
261
directory for the following .INCLUDE and .INCBIN directives.
262
If you want to change to the current working directory (PV2 also defaults
263
to this), use
264
 
265
.INCDIR ""
266
 
267
This is not a compulsory directive.
268
 
269
-------------------------
270
.INCLUDE "cgb_hardware.i"
271
-------------------------
272
 
273
Includes the specified file to the source file. If the file's not found
274
in the .INCDIR directory, PV2 tries to find it in the current working
275
directory.
276
 
277
This is not a compulsory directive.
278
 
279
----------------------
280
.INCBIN "sorority.bin"
281
----------------------
282
 
283
Includes the specified data file into the source file. .INCBIN caches
284
all files into memory, so you can .INCBIN any data file millions of
285
times, but it is loaded from hard drive only once.
286
 
287
You can optionally use SWAP after the file name, e.g.,
288
 
289
.INCBIN "kitten.bin" SWAP
290
 
291
.INCBIN data is divided into blocks of two bytes, and inside every block
292
the bytes are exchanged (like "SWAP r" does to nibbles). This requires that
293
the size of the file is even.
294
 
295
You can also force PV2 to skip n bytes from the beginning of the file
296
by writing for example:
297
 
298
.INCBIN "kitten.bin" SKIP 4
299
 
300
Four bytes are skipped from the beginning of kitten.bin and the rest
301
is incbinned.
302
 
303
It is also possible to incbin only n bytes from a file:
304
 
305
.INCBIN "kitten.bin" READ 10
306
 
307
Will read ten bytes from the beginning of kitten.bin.
308
 
309
You can also force PV2 to create a definition holding the size
310
of the file:
311
 
312
.INCBIN "kitten.bin" FSIZE size_of_kitten
313
 
314
And you can combine all these four commands:
315
 
316
.INCBIN "kitten.bin" SKIP 10 READ 8 SWAP FSIZE size_of_kitten
317
 
318
This example shows how to incbin eight bytes (swapped) after skipping
319
10 bytes from the beginning of file "kitten.bin", and how to get the
320
size of the file into a definition label "size_of_kitten". Note that the
321
order of the extra commands is important.
322
 
323
If the file's not found in the .INCDIR directory, PV2 tries to find it
324
in the current working directory.
325
 
326
This is not a compulsory directive.
327
 
328
-----------
329
.INPUT NAME
330
-----------
331
 
332
.INPUT is much like any Basic-language input: .INPUT asks the user
333
for a value or string. After .INPUT is the variable name used to store
334
the data.
335
 
336
.INPUT works like .REDEFINE, but the user gets to type in the data.
337
 
338
Here are few examples how to use input:
339
 
340
.PRINTT "The name of the TFT pic? "
341
.INPUT NAME
342
.NAME NAME
343
 
344
...
345
 
346
.PRINTT "Give the .DB amount.\n"
347
.INPUT S
348
.PRINTT "Give .DB data one at a time.\n"
349
.REPEAT S
350
  .INPUT B
351
  .DB B
352
.ENDR
353
 
354
...
355
 
356
This is not a compulsory directive.
357
 
358
-----
359
.FAIL
360
-----
361
 
362
Terminates the compiling process.
363
 
364
This is not a compulsory directive.
365
 
366
------------------
367
.FCLOSE FP_DATABIN
368
------------------
369
 
370
Closes the filehandle FP_DATABIN.
371
 
372
This is not a compulsory directive.
373
 
374
----------------------------
375
.FOPEN "data.bin" FP_DATABIN
376
----------------------------
377
 
378
Opens the file "data.bin" for reading and associates the filehandle with
379
name "FP_DATABIN".
380
 
381
This is not a compulsory directive.
382
 
383
----------------------
384
.FREAD FP_DATABIN DATA
385
----------------------
386
 
387
Reads one byte from "FP_DATABIN" and creates a definition called "DATA"
388
to hold it. "DATA" is an ordinary definition label, so you can .UNDEFINE it.
389
 
390
Here's an example on how to use .FREAD:
391
 
392
.fopen "data.bin" fp
393
.fsize fp t
394
.repeat t
395
.fread fp d
396
.db d+26
397
.endr
398
.undefine t, d
399
 
400
This is not a compulsory directive.
401
 
402
----------------------
403
.FSIZE FP_DATABIN SIZE
404
----------------------
405
 
406
Creates a definition called "SIZE", which holds the size of the file
407
associated with the filehandle "FP_DATABIN". "SIZE" is an ordinary
408
definition label, so you can .UNDEFINE it.
409
 
410
This is not a compulsory directive.
411
 
412
-----------
413
.MACRO TEST
414
-----------
415
 
416
Begins a macro called 'TEST'.
417
 
418
You can use '\@' inside a macro to e.g., separate a label from the other
419
macro 'TEST' occurrences. '\@' is replaced with an integer number
420
indicating the amount of times the macro has been called previously so
421
it is unique to every macro call. '\@' can also be used inside strings
422
inside a macro or just as a plain value. Look at the following examples
423
for more information.
424
 
425
Also, if you want to use macro arguments in e.g., calculation, you can
426
type '\X' where X is the number of the argument. Another way to refer
427
to the arguments is to use their names given in the definition of the
428
macro (see the examples for this).
429
 
430
Remember to use .ENDM to finish the macro definition. Note that you
431
cannot use .INCLUDE inside a macro. Note that PV2's macros are in fact
432
more like procedures than real macros, because PV2 doesn't substitute
433
macro calls with macro data. Instead PV2 jumps to the macro when it
434
encounters a macro call at compile time.
435
 
436
You can call macros from inside a macro. Note that the preprocessor
437
does not expand the macros. PV2 traverses through the code according to
438
the macro calls, so macros really define a very simple programming
439
language.
440
 
441
Here are some examples:
442
 
443
.MACRO NOPMONSTER
444
       .REPT 32         ; it's just an example...
445
       NOP
446
       .ENDR
447
.ENDM
448
 
449
.MACRO LOAD_ABCD
450
       LD A, \1
451
       LD B, \2
452
       LD C, \3
453
       LD D, \4
454
       NOPMONSTER
455
       LD HL, 1<<\1
456
.INCBIN \5
457
.ENDM
458
 
459
.MACRO QUEEN
460
 
461
QUEEN\@:
462
        LD   A, \1
463
        LD   B, \1
464
        CALL QUEEN\@
465
 
466
        .DB  "\@", 0     ; will translate into a zero terminated string
467
                         ; holding the amount of macro QUEEN calls.
468
        .DB  "\\@", 0    ; will translate into a string containing
469
                         ; \@.
470
        .DB  \@          ; will translate into a number indicating
471
                         ; the amount of macro QUEEN calls.
472
 
473
.ENDM
474
 
475
.MACRO LOAD_ABCD_2 ARGS ONE, TWO, THREE, FOUR, FIVE
476
       LD A, ONE
477
       LD B, TWO
478
       LD C, THREE
479
       LD D, FOUR
480
       NOPMONSTER
481
       LD HL, 1< \2, etc.).
482
.SHIFT can thus only be used inside a .MACRO.
483
 
484
This is not a compulsory directive.
485
 
486
---------
487
.ORG $150
488
---------
489
 
490
Defines the starting address. The default starting address is $0
491
 
492
This is not a compulsory directive.
493
 
494
------------
495
.DS 256, $10
496
------------
497
 
498
.DS is an alias for .DSB.
499
 
500
This is not a compulsory directive.
501
 
502
-------------
503
.DSB 256, $10
504
-------------
505
 
506
Defines 256 bytes of $10.
507
 
508
This is not a compulsory directive.
509
 
510
----------------------------------------------------------
511
.DSTRUCT waterdrop INSTANCEOF water DATA "tingle", 40, 120
512
----------------------------------------------------------
513
 
514
Defines an instance of struct water, called waterdrop, and fills
515
it with the given data. Before calling .DSTRUCT we must have defined
516
the structure, and in this example it could be like:
517
 
518
.STRUCT water
519
name   ds 8
520
age    db
521
weight dw
522
.ENDST
523
 
524
Note that the keywords INSTANCEOF and DATA are optional, so
525
 
526
.DSTRUCT waterdrop, water, "tingle", 40, 120
527
 
528
also works. Also note that PV2 fills the missing bytes with the data
529
defined with .EMPTYFILL, or $00 if no .EMPTYFILL has been issued.
530
 
531
In this example you would also get the following labels:
532
 
533
waterdrop
534
waterdrop.name
535
waterdrop.age
536
waterdrop.weight
537
 
538
This is not a compulsory directive.
539
 
540
------------
541
.DSW 128, 20
542
------------
543
 
544
Defines 128 words (two bytes) of 20.
545
 
546
This is not a compulsory directive.
547
 
548
-----------------------------------
549
.DB 100, $30, %1000, "HELLO WORLD!"
550
-----------------------------------
551
 
552
Defines bytes.
553
 
554
This is not a compulsory directive.
555
 
556
------------------------------------
557
.BYT 100, $30, %1000, "HELLO WORLD!"
558
------------------------------------
559
 
560
.BYT is an alias for .DB.
561
 
562
This is not a compulsory directive.
563
 
564
------------
565
.SYM SAUSAGE
566
------------
567
 
568
PV2 treats symbols ("SAUSAGE" in this example) like labels, but they
569
only appear in the symbol files PV2LINK outputs. Useful for finding out
570
the location where PV2LINK puts data.
571
 
572
This is not a compulsory directive.
573
 
574
---------------
575
.SYMBOL SAUSAGE
576
---------------
577
 
578
.SYMBOL is an alias for .SYM.
579
 
580
This is not a compulsory directive.
581
 
582
---
583
.BR
584
---
585
 
586
Inserts a breakpoint that behaves like a .SYM without a name. Breakpoints
587
can only be seen in PV2LINK's symbol file.
588
 
589
This is not a compulsory directive.
590
 
591
-----------
592
.BREAKPOINT
593
-----------
594
 
595
.BREAKPOINT is an alias for .BR.
596
 
597
This is not a compulsory directive.
598
 
599
-----------
600
.ASCIITABLE
601
-----------
602
 
603
.ASCIITABLE's only purpose is to provide character mapping for .ASC.
604
Take a look at the example:
605
 
606
.ASCIITABLE
607
MAP "A" TO "Z" = 0
608
MAP "!" = 90
609
.ENDA
610
 
611
Here we set such a mapping that character 'A' is equal to 0, 'B'
612
is equal to 1, 'C' is equal to 2, and so on, and '!' is equal to 90.
613
 
614
After you've given the .ASCIITABLE, use .ASC to define bytes using
615
this mapping (.ASC is an alias for .DB, but with .ASCIITABLE mapping).
616
For example, .ASC "AB!" would define bytes 0, 1 and 90.
617
 
618
Note that the following works as well:
619
 
620
.ASCIITABLE
621
MAP 'A' TO 'Z' = 0
622
MAP 65 = 90
623
.ENDA
624
 
625
Also note that the characters that are not given any mapping in
626
.ASCIITABLE map to themselves (i.e., 'A' maps to 'A', etc.).
627
 
628
This is not a compulsory directive.
629
 
630
---------
631
.ASCTABLE
632
---------
633
 
634
.ASCTABLE is an alias for .ASCIITABLE.
635
 
636
This is not a compulsory directive.
637
 
638
-------------------
639
.ASC "HELLO WORLD!"
640
-------------------
641
 
642
.ASC is an alias for .DB, but if you use .ASC it will remap
643
the characters using the mapping given via .ASCIITABLE.
644
 
645
This is not a compulsory directive.
646
 
647
------------------
648
.DW 16000, 10, 255
649
------------------
650
 
651
Defines words (two bytes each). .DW takes only numbers and
652
characters as input, not strings.
653
 
654
This is not a compulsory directive.
655
 
656
--------------------
657
.WORD 16000, 10, 255
658
--------------------
659
 
660
.WORD is an alias for .DW.
661
 
662
This is not a compulsory directive.
663
 
664
----------------
665
.DEFINE IF $FF0F
666
----------------
667
 
668
Assigns a number or a string to a definition label.
669
 
670
By default all defines are local to the file where they are
671
presented. If you want to make the definition visible to all the
672
files in the project, use .EXPORT.
673
 
674
Here are some examples:
675
 
676
.DEFINE X 1000
677
.DEFINE FILE "PD-03.TFT"
678
.DEFINE TXT1 "hello and welcome", 1, "to the PV2", 0
679
.DEFINE BYTES 1, 2, 3, 4, 5
680
.DEFINE COMPUTATION X+1
681
.DEFINE DEFAULTV
682
 
683
All definitions with multiple values are marked as data strings,
684
and .DB is about the only place where you can later on use them.
685
 
686
.DEFINE BYTES 1, 2, 3, 4, 5
687
.DB 0, BYTES, 6
688
 
689
is the same as
690
 
691
.DB 0, 1, 2, 3, 4, 5, 6
692
 
693
If you omit the definition value (in our example "DEFAULTV"), PV2
694
will default to 0.
695
 
696
Note that you must do your definition before you use it, otherwise
697
PV2 will use the final value of the definition. Here's an example
698
of this:
699
 
700
.DEFINE AAA 10
701
.DB AAA            ; will be 10.
702
.REDEFINE AAA 11
703
 
704
but
705
 
706
.DB AAA            ; will be 11.
707
.DEFINE AAA 10
708
.REDEFINE AAA 11
709
 
710
You can also create definitions on the command line. Here's an
711
example of this:
712
 
713
pv2ass -vl -DMOON -DNAME=john -DPRICE=100 -DADDRESS=$100 math.s
714
 
715
MOON's value will be 0, NAME is a string definition with value "john",
716
PRICE's value will be 100, and ADDRESS's value will be $100.
717
 
718
Note that
719
 
720
.DEFINE AAA = 10   ; the same as ".DEFINE AAA 10".
721
 
722
works as well.
723
 
724
This is not a compulsory directive.
725
 
726
-------------
727
.DEF IF $FF0F
728
-------------
729
 
730
.DEF is an alias for .DEFINE.
731
 
732
This is not a compulsory directive.
733
 
734
-------------
735
.EQU IF $FF0F
736
-------------
737
 
738
.EQU is an alias for .DEFINE.
739
 
740
This is not a compulsory directive.
741
 
742
----------------
743
.REDEFINE IF $0F
744
----------------
745
 
746
Assigns a new value or a string to an old definition. If the
747
definition doesn't exist, .REDEFINE performs .DEFINE's work.
748
 
749
When used with .REPT REDEFINE helps creating tables:
750
 
751
.DEFINE CNT 0
752
 
753
.REPT 256
754
.DB CNT
755
.REDEFINE CNT CNT+1
756
.ENDR
757
 
758
This is not a compulsory directive.
759
 
760
-------------
761
.REDEF IF $0F
762
-------------
763
 
764
.REDEF is an alias for .REDEFINE.
765
 
766
This is not a compulsory directive.
767
 
768
--------------
769
.IF DEBUG == 2
770
--------------
771
 
772
If the condition is fulfilled the following piece of code is
773
acknowledged until .ENDIF/.ELSE occurs in the text, otherwise
774
it is skipped. Operands must be immediate values or strings.
775
 
776
The following operators are supported:
777
<  - less than
778
<= - less or equal to
779
>  - greater than
780
>= - greater or equal to
781
== - equals to
782
!= - doesn't equal to
783
 
784
All IF (yes, including .IFDEF, .IFNDEF, etc) directives can be
785
nested.
786
 
787
This is not a compulsory directive.
788
 
789
---------
790
.IFDEF IF
791
---------
792
 
793
If "IF" is defined, then the following piece of code is acknowledged
794
until .ENDIF/.ELSE occurs in the text, otherwise it is skipped.
795
 
796
This is not a compulsory directive.
797
 
798
------------------
799
.IFEXISTS "main.s"
800
------------------
801
 
802
If "main.s" file can be found, then the following piece of code is
803
acknowledged until .ENDIF/.LESE occurs in the text, otherwise it is
804
skipped.
805
 
806
By writing the following few lines you can include a file if it exists
807
without breaking the compiling loop if it doesn't exist.
808
 
809
.IFEXISTS FILE
810
.INCLUDE FILE
811
.ENDIF
812
 
813
This is not a compulsory directive.
814
 
815
---------------
816
.UNDEFINE DEBUG
817
---------------
818
 
819
Removes the supplied definition label from system. If there is no
820
such label as given no error is displayed as the result would be the
821
same.
822
 
823
You can undefine as many definitions as you wish with one .UNDEFINE:
824
 
825
.UNDEFINE NUMBER, NAME, ADDRESS, COUNTRY
826
.UNDEFINE NAME, AGE
827
 
828
This is not a compulsory directive.
829
 
830
------------
831
.UNDEF DEBUG
832
------------
833
 
834
.UNDEF is an alias for .UNDEFINE.
835
 
836
This is not a compulsory directive.
837
 
838
----------
839
.IFNDEF IF
840
----------
841
 
842
If "IF" is not defined, then the following piece of code is acknowledged
843
until .ENDIF/.ELSE occurs in the text, otherwise it is skipped.
844
 
845
This is not a compulsory directive.
846
 
847
----------
848
.IFDEFM \2
849
----------
850
 
851
If the specified argument is defined (argument number two, in the example),
852
then the following piece of code is acknowledged until .ENDIF/.ELSE occurs
853
in the macro, otherwise it is skipped.
854
 
855
This is not a compulsory directive. .IFDEFM works only inside a macro.
856
 
857
-----------
858
.IFNDEFM \2
859
-----------
860
 
861
If the specified argument is not defined, then the following piece of
862
code is acknowledged until .ENDIF/.ELSE occurs in the macro, otherwise
863
it is skipped.
864
 
865
This is not a compulsory directive. .IFNDEFM works only inside a macro.
866
 
867
-------------
868
.IFEQ DEBUG 2
869
-------------
870
 
871
If the value of DEBUG equals to 2, then the following piece of code is
872
acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped.
873
Both arguments can be computations, defines or immediate values.
874
 
875
This is not a compulsory directive.
876
 
877
--------------
878
.IFNEQ DEBUG 2
879
--------------
880
 
881
If the value of DEBUG doesn't equal to 2, then the following piece of
882
code is acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is
883
skipped. Both arguments can be computations, defines or immediate
884
values.
885
 
886
This is not a compulsory directive.
887
 
888
-------------
889
.IFLE DEBUG 2
890
-------------
891
 
892
If the value of DEBUG is less than 2, then the following piece of code is
893
acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped.
894
Both arguments can be computations, defines or immediate values.
895
 
896
This is not a compulsory directive.
897
 
898
---------------
899
.IFLEEQ DEBUG 2
900
---------------
901
 
902
If the value of DEBUG is less or equal to 2, then the following piece of code is
903
acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped.
904
Both arguments can be computations, defines or immediate values.
905
 
906
This is not a compulsory directive.
907
 
908
-------------
909
.IFGR DEBUG 2
910
-------------
911
 
912
If the value of DEBUG is greater than 2, then the following piece of code is
913
acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped.
914
Both arguments can be computations, defines or immediate values.
915
 
916
This is not a compulsory directive.
917
 
918
---------------
919
.IFGREQ DEBUG 2
920
---------------
921
 
922
If the value of DEBUG is greater or equal to 2, then the following piece of code is
923
acknowledged until .ENDIF/.ELSE occurs in the text, otherwise it is skipped.
924
Both arguments can be computations, defines or immediate values.
925
 
926
This is not a compulsory directive.
927
 
928
-----
929
.ELSE
930
-----
931
 
932
If the previous .IFxxx failed then the following text until
933
.ENDIF is acknowledged.
934
 
935
This is not a compulsory directive.
936
 
937
------
938
.ENDIF
939
------
940
 
941
This terminates any .IFxxx directive.
942
 
943
This is not a compulsory directive, but if you use any .IFxxx then
944
you need also to apply this.
945
 
946
---------
947
.REPEAT 6
948
---------
949
 
950
Repeats the text enclosed between ".REPEAT x" and ".ENDR" x times (6 in
951
this example). You can use .REPEATs inside .REPEATs. 'x' must be >= 0.
952
 
953
This is not a compulsory directive.
954
 
955
-------
956
.REPT 6
957
-------
958
 
959
.REPT is an alias for .REPEAT.
960
 
961
This is not a compulsory directive.
962
 
963
-----
964
.ENDR
965
-----
966
 
967
Ends the repetition.
968
 
969
This is not a compulsory directive, but when .REPEAT is used this one is
970
required to terminate it.
971
 
972
-----------
973
.ENUM $C000
974
-----------
975
 
976
Starts enumeration from $C000. Very useful for defining variables.
977
 
978
To start a descending enumeration, put "DESC" after the starting
979
address. PV2 defaults to "ASC" (ascending enumeration).
980
 
981
You can also add "EXPORT" after these if you want to export all
982
the generated definitions automatically.
983
 
984
Here's an example of .ENUM:
985
 
986
...
987
.STRUCT mon                ; check out the documentation on
988
name ds 2                  ; .STRUCT
989
age  db
990
.ENDST
991
 
992
.ENUM $A000
993
_scroll_x DB               ; db  - define byte (byt and byte work also)
994
_scroll_y DB
995
player_x: DW               ; dw  - define word (word works also)
996
player_y: DW
997
map_01:   DS  16           ; ds  - define size (bytes)
998
map_02    DSB 16           ; dsb - define size (bytes)
999
map_03    DSW  8           ; dsw - define size (words)
1000
monster   INSTANCEOF mon 3 ; three instances of structure mon
1001
dragon    INSTANCEOF mon   ; one mon
1002
.ENDE
1003
...
1004
 
1005
Previous example transforms into following definitions:
1006
 
1007
.DEFINE _scroll_x      $A000
1008
.DEFINE _scroll_y      $A001
1009
.DEFINE player_x       $A002
1010
.DEFINE player_y       $A004
1011
.DEFINE map_01         $A006
1012
.DEFINE map_02         $A016
1013
.DEFINE map_03         $A026
1014
.DEFINE monster        $A036
1015
.DEFINE monster.name   $A036
1016
.DEFINE monster.age    $A038
1017
.DEFINE monster.1      $A036
1018
.DEFINE monster.1.name $A036
1019
.DEFINE monster.1.age  $A038
1020
.DEFINE monster.2      $A039
1021
.DEFINE monster.2.name $A039
1022
.DEFINE monster.2.age  $A03B
1023
.DEFINE monster.3      $A03C
1024
.DEFINE monster.3.name $A03C
1025
.DEFINE monster.3.age  $A03E
1026
.DEFINE dragon         $A03F
1027
.DEFINE dragon.name    $A03F
1028
.DEFINE dragon.age     $A041
1029
 
1030
DB, DW, DS, DSB, DSW and INSTANCEOF can also be in lowercase. You
1031
can also use a dotted version of the symbols, but it doesn't advance
1032
the memory address. Here's an exmple:
1033
 
1034
.ENUM $C000 DESC EXPORT
1035
bigapple_h db
1036
bigapple_l db
1037
bigapple:  .dw
1038
.ENDE
1039
 
1040
And this is what is generated:
1041
 
1042
.DEFINE bigapple_h $BFFF
1043
.DEFINE bigapple_l $BFFE
1044
.DEFINE bigapple   $BFFE
1045
.EXPORT bigapple, bigapple_l, bigapple_h
1046
 
1047
This way you can generate a 16bit variable address along with pointers
1048
to its parts.
1049
 
1050
If you want more flexible variable positioning, take a look at
1051
.RAMSECTIONs.
1052
 
1053
This is not a compulsory directive.
1054
 
1055
-----
1056
.ENDE
1057
-----
1058
 
1059
Ends the enumeration.
1060
 
1061
This is not a compulsory directive, but when .ENUM is used this one is
1062
required to terminate it.
1063
 
1064
--------------------
1065
.STRUCT enemy_object
1066
--------------------
1067
 
1068
Begins the definition of a structure. These structures can be placed
1069
inside RAMSECTIONs and ENUMs. Here's an example:
1070
 
1071
.STRUCT enemy_object
1072
id    dw               ; the insides of a .STRUCT are 1:1 like in .ENUM
1073
x     db               ; except that no structs inside structs are
1074
y     db               ; allowed.
1075
data  ds  10
1076
info  dsb 16
1077
stats dsw  4
1078
.ENDST
1079
 
1080
This also creates a definition "_sizeof_[struct name]", in our example
1081
this would be "_sizeof_enemy_object", and the value of this definition
1082
is the size of the object, in bytes (2+1+1+10+16+4*2 = 38 in the example).
1083
 
1084
You'll get the following definitions as well:
1085
 
1086
enemy_object.id    (== 0)
1087
enemy_object.x     (== 2)
1088
enemy_object.y     (== 3)
1089
enemy_object.data  (== 4)
1090
enemy_object.info  (== 14)
1091
enemy_object.stats (== 30)
1092
 
1093
After defining a .STRUCT you can create an instance of it in a .RAMSECTION /
1094
.ENUM by typing
1095
 
1096
 INSTANCEOF  [optional, the number of structures]
1097
 
1098
Here's an example:
1099
 
1100
.RAMSECTION "enemies" BANK 4 SLOT 4
1101
enemies   INSTANCEOF enemy_object 4
1102
enemyman  INSTANCEOF enemy_object
1103
enemyboss INSTANCEOF enemy_object
1104
.ENDS
1105
 
1106
This will create labels like "enemies", "enemies.id", "enemies.x", "enemies.y"
1107
and so on. Label "enemies" is followed by four "enemy_object" structures,
1108
and only the first one is labeled. After there four come "enemyman" and
1109
"enemyboss" instances.
1110
 
1111
Take a look at the documentation on .RAMSECTION & .ENUM, they have more
1112
examples of how you can use .STRUCTs.
1113
 
1114
A WORD OF WARNING: Don't use labels b, B, w and W inside a struct as e.g.,
1115
PV2 sees enemy.b as a byte sized reference to enemy. All other labels should
1116
be safe.
1117
 
1118
lda enemy1.b  ; load a byte from zeropage address enemy1 or from the address
1119
              ; of enemy1.b??? i can't tell you, and PV2 can't tell you...
1120
 
1121
This is not a compulsory directive.
1122
 
1123
------
1124
.ENDST
1125
------
1126
 
1127
Ends the structure definition.
1128
 
1129
This is not a compulsory directive, but when .STRUCT is used this one is
1130
required to terminate it.
1131
 
1132
---------
1133
.SEED 123
1134
---------
1135
 
1136
Seeds the random number generator.
1137
 
1138
This is not a compulsory directive. The random number generator is
1139
initially seeded with the output of time(), which is, according to
1140
the manual, "the time since the Epoch (00:00:00 UTC, January 1, 1970),
1141
measured in seconds". So if you don't .SEED the random number generator
1142
yourself with a constant value, .DBRND and .DWRND give you different
1143
values every time you run PV2.
1144
 
1145
---------------------
1146
.SECTION "Init" FORCE
1147
---------------------
1148
 
1149
Section is a continuous area of data which is placed into the output
1150
file according to the section type and .ORG directive
1151
values.
1152
 
1153
The example begins a section called "Init". Before a section can be
1154
declared, .ORG must be used unless PV2 is in library file
1155
output mode. Library file's sections must all be FREE ones. .BANK tells
1156
the bank number where this section will be later relocated into. .ORG
1157
tells the offset for the relocation from the beginning of .BANK.
1158
 
1159
You can supply the preferred section size (bytes) inside the section
1160
name string. Here's an example:
1161
 
1162
.SECTION "Init_100" FREE
1163
 
1164
will create a section ("Init") with size of 100 bytes, unless the actual
1165
data overflows from the section, in which case the section size is
1166
enlarged to contain all the data. Note that the syntax for explicit
1167
section size defining is: "NAME_X", where "NAME" is the name of the
1168
section and "X" is the size (decimal or hexadecimal value).
1169
 
1170
You can also give the size of the section the following way:
1171
 
1172
.SECTION "Init" SIZE 100 FREE
1173
 
1174
It's possible to force PV2LINK to align the FREE, SEMIFREE and SUPERFREE
1175
sections by giving the alignment as follows:
1176
 
1177
.SECTION "Init" SIZE 100 ALIGN 4 FREE
1178
 
1179
And if you want that PV2 returns the ORG to what it was before issuing
1180
the section, put RETURNORG at the end of the parameter list:
1181
 
1182
.SECTION "Init" SIZE 100 ALIGN 4 FREE RETURNORG
1183
 
1184
By default PV2 advances the ORG, so, for example, if your ORG was $0 before
1185
a section of 16 bytes, then the ORG will be 16 after the section.
1186
 
1187
Note also that if your section name begins with double underlines (e.g.,
1188
"__UNIQUE_SECTION!!!") the section will be unique in the sense that
1189
when PV2LINK recieves files containing sections which share the same
1190
name, PV2LINK will save only the first of them for further processing,
1191
all others are deleted from memory with corresponding labels, references
1192
and calculations.
1193
 
1194
If a section name begins with an exclamation mark ('!') it tells
1195
PV2LINK to not to drop it, even if you use PV2LINK's ability to discard
1196
all unreferenced sections and there are no references to the section.
1197
 
1198
FORCE after the name of the section tells PV2 that the section _must_ be
1199
inserted so it starts at .ORG. FORCE can be replaced with FREE which
1200
means that the section can be inserted somewhere in the defined bank,
1201
where there is room. You can also use OVERWRITE to insert the section
1202
into the memory regardless of data collisions. Using OVERWRITE you can
1203
easily patch an existing ROM image just by .BACKGROUND'ing the ROM image and
1204
inserting OVERWRITE sections into it. SEMIFREE sections are also
1205
possible and they behave much like FREE sections. The only difference
1206
is that they are positioned somewhere in the bank starting from .ORG.
1207
SUPERFREE sections are also available, and they will be positioned into
1208
the first suitable place inside the first suitable bank (candidates
1209
for these suitable banks have the same size with the slot of the section,
1210
no other banks are considered). You can also leave away the type
1211
specifier as the default type for the section is FREE.
1212
 
1213
You can name the sections as you wish, but there is one special name.
1214
A section called "BANKHEADER" is placed in the front of the bank
1215
where it is defined. These sections contain data that is not in the
1216
memory map of the machine, so you can't refer to the data of a
1217
BANKHEADER section, but you can write references to outside. So no
1218
labels inside BANKHEADER sections. These special sections are useful
1219
when writing e.g., MSX programs. Note that library files don't take
1220
BANKHEADER sections.
1221
 
1222
Here's an example of a "BANKHEADER" section:
1223
 
1224
.BANK 0
1225
.ORG 0
1226
.SECTION "BANKHEADER"
1227
        .DW MAIN
1228
        .DW VBI
1229
.ENDS
1230
 
1231
.SECTION "Program"
1232
MAIN:    CALL   MONTY_ON_THE_RUN
1233
VBI:     PUSH   HL
1234
         ...
1235
         POP    HL
1236
         RETI
1237
.ENDS
1238
 
1239
Here's an example of an ordinary section:
1240
 
1241
.BANK 0
1242
.ORG $150
1243
.SECTION "Init" FREE
1244
        DI
1245
        LD  SP, $FFFE
1246
        SUB A
1247
        LD  ($FF00+R_IE), A
1248
.ENDS
1249
 
1250
This tells PV2 that a FREE section called "Init" must be located somewhere
1251
in bank 0. If you replace FREE with SEMIFREE the section will be inserted
1252
somewhere in the bank 0, but not in the $0-$14F area. If you replace FREE
1253
with SUPERFREE the section will be inserted somewhere in the
1254
 
1255
Here's the order in which PV2 writes the sections:
1256
1. FORCE
1257
2. SEMIFREE & FREE
1258
3. SUPERFREE
1259
4. OVERWRITE
1260
 
1261
Before the sections are inserted into the output file, they are sorted by
1262
size, so that the biggest section gets processed first and the smallest
1263
last.
1264
 
1265
You can also create a RAM section. For more information about them, please
1266
read the .RAMSECTION directive explanation.
1267
 
1268
This is not a compulsory directive.
1269
 
1270
--------------
1271
.EXPORT work_x
1272
--------------
1273
 
1274
Exports the definition "work_x" to outside world. Exported definitions are
1275
visible to all object files and libraries in the linking procedure. Note
1276
that you can only export value definitions, not string definitions.
1277
 
1278
You can export as many definitions as you wish with one .EXPORT:
1279
 
1280
.EXPORT NUMBER, NAME, ADDRESS, COUNTRY
1281
.EXPORT NAME, AGE
1282
 
1283
This is not a compulsory directive.
1284
 
1285
--------------------------
1286
.PRINTT "Here we are...\n"
1287
--------------------------
1288
 
1289
Prints the given text into stdout. Good for debugging stuff. PRINTT takes
1290
only a string as argument, and the only supported formatting symbol is '\n'
1291
(line feed).
1292
 
1293
This is not a compulsory directive.
1294
 
1295
-------------------
1296
.PRINTV DEC DEBUG+1
1297
-------------------
1298
 
1299
Prints the value of the supplied definition or computation into stdout.
1300
Computation must be solvable at the time of printing (just like definitions
1301
values). PRINTV takes two parameters. The first describes the type of the
1302
print output. "DEC" means decimal, "HEX" means hexadecimal.
1303
 
1304
Use PRINTV with PRINTT as PRINTV doesn't print linefeeds, only the result.
1305
Here's an example:
1306
 
1307
.PRINTT "Value of \"DEBUG\" = $"
1308
.PRINTV HEX DEBUG
1309
.PRINTT "\n"
1310
 
1311
This is not a compulsory directive.
1312
 
1313
------------------
1314
.OUTNAME "other.o"
1315
------------------
1316
 
1317
Changes the name of the output file. Here's and example:
1318
 
1319
pv2ass -o test.s
1320
 
1321
would normally output "test.o", but if you had written
1322
 
1323
.OUTNAME "new.o"
1324
 
1325
somewhere in the code PV2 would write the output to new.o instead.
1326
 
1327
This is not a compulsory directive.
1328
 
1329
 
1330
----------------------------------------------
1331
3.... Assembler Syntax
1332
----------------------------------------------
1333
 
1334
 
1335
3.1. Case Sensitivity
1336
 
1337
PV2ASS is case sensitive, so be careful.
1338
 
1339
 
1340
3.2. Comments
1341
 
1342
Comments begin with ';' or '*' and end along with the line. ';' can be
1343
used anywhere, but '*' can be placed only at the beginning of a new line.
1344
 
1345
PV2ASS also has ANSI-C -like commenting. This means you can start a
1346
multiline comment with "/*" and end it with "*/". Additionally, it has
1347
.ASM and .ENDASM directives. These function much like ANSI-C comments, but
1348
unlike the ANSI-C comments these can be nested.
1349
 
1350
 
1351
3.3. Labels
1352
 
1353
Labels are ordinary strings (which can also end to a ':'). Labels starting
1354
with "_" are considered to be local labels and do not show outside sections
1355
where they were defined, or outside object files, if they were not defined
1356
inside a section.
1357
 
1358
Here are few examples of different labels:
1359
 
1360
VBI_IRQ:
1361
VBI_IRQ2
1362
_VBI_LOOP:
1363
main:
1364
 
1365
3.4. Number Types
1366
 
1367
1000 - decimal
1368
$100 - hexadecimal
1369
100h - hexadecimal
1370
%100 - binary
1371
'x'  - character
1372
 
1373
Remember that if you use the suffix 'h' to give a hexadecimal value,
1374
and the value begins with an alphabet, you must place a zero in front of it
1375
so PV2 knows it's not a label (e.g., "0ah" instead of "ah").
1376
 
1377
 
1378
3.5. Strings
1379
 
1380
Strings begin with and end to '"'. Note that no 0 is inserted to indicate
1381
the termination of the string like in e.g., ANSI C. You'll have to do it
1382
yourself. You can place quotation marks inside strings the way C
1383
preprocessors accept them.
1384
 
1385
Here are some examples of strings:
1386
 
1387
"Hello world!"
1388
"He said: \"Please, kiss me honey.\""
1389
 
1390
 
1391
----------------------------------------------
1392
4.... Error Messages
1393
----------------------------------------------
1394
 
1395
 
1396
There are quite a few of them in PV2ASS, but most of them are not very
1397
informative. Coder beware.
1398
 
1399
 
1400
----------------------------------------------
1401
5.... Bugs
1402
----------------------------------------------
1403
 
1404
 
1405
Report bugs to billwiley777@gmail.com
1406
 
1407
 
1408
----------------------------------------------
1409
6.... Temporary Files
1410
----------------------------------------------
1411
 
1412
 
1413
Note that PV2 will generate two temporary files while it works. Both files
1414
are placed into the current working directory.
1415
 
1416
The filenames are ".wla%PID%a" and ".wla%PID%b" (%PID% is the process id).
1417
 
1418
When PV2 finishes its work these two files are deleted as they serve
1419
of no further use.
1420
 
1421
 
1422
----------------------------------------------
1423
7.... Compiling
1424
----------------------------------------------
1425
 
1426
 
1427
7.1. Compiling Object Files
1428
 
1429
To compile an object file use:
1430
 
1431
"pv2ass -[itvx]o [DEFINITIONS]  [OUTPUT FILE]"
1432
 
1433
These object files can be linked together (or with library files) later
1434
with "pv2link".
1435
 
1436
Name object files so that they can be recognized as object files. Normal
1437
suffix is ".o" (PV2 default). This can also be changed with .OUTNAME.
1438
 
1439
With object files you can reduce the amount of compiling when editing
1440
small parts of the program. Note also the possibility of using local
1441
labels (starting with "_").
1442
 
1443
Note! When you compile objects, group 1 directives are saved for linking
1444
time, when they are all compared and if they differ, an error message is
1445
shown. It is advisable to use something like an include file to hold all
1446
the group 1 directives for that particular project and include it to every
1447
object file.
1448
 
1449
Here are some examples of definitions:
1450
 
1451
-DIEXIST
1452
-DDAY=10
1453
-DBASE=$10
1454
-DNAME=elvis
1455
 
1456
And here's an PV2 example creating definitions on the command line:
1457
 
1458
pv2ass -o -DDEBUG -DVERBOSE=5 -DNAME="math v1.0" math.s
1459
 
1460
DEBUG's value will be 0, VERBOSE's 5 and NAME is a string definition
1461
with value "math v1.0".
1462
 
1463
 
1464
7.2. Compiling Library Files
1465
 
1466
To compile a library file use:
1467
 
1468
"pv2ass -[itvx]l [DEFINITIONS]  [OUTPUT FILE]"
1469
 
1470
Name object files so that they can be recognized as library files. Normal
1471
suffix is ".lib" (PV2 default).
1472
 
1473
With library files you can reduce the amount of compiling. Library files
1474
are meant to hold general functions that can be used in different projects.
1475
Note also the possibility of using local labels (starting with "_").
1476
Library files consist only of FREE sections.
1477
 
1478
 
1479
----------------------------------------------
1480
8... Linking
1481
----------------------------------------------
1482
 
1483
 
1484
After you have produced one or more object files and perhaps some library
1485
files, you might want to link them together to produce a ROM image / program
1486
file. "pv2link" is the program you use for that. Here's how you use it:
1487
 
1488
"pv2link [-divsS]{b/r}  "
1489
 
1490
Choose 'b' for program file or 'r' for ROM image linking.
1491
 
1492
Link file is a text file that contains information about the files you want
1493
to link together. Here's the format:
1494
 
1495
1. You must define the group for the files. Put the name of the group
1496
inside brackets. Valid group definitions are
1497
 
1498
[objects]
1499
[libraries]
1500
[header]
1501
[footer]
1502
[definitions]
1503
 
1504
2. Start to list the file names.
1505
 
1506
[objects]
1507
main.o
1508
vbi.o
1509
level_01.o
1510
...
1511
 
1512
3. Give parameters to the library files:
1513
 
1514
[libraries]
1515
bank 0 slot 1 speed.lib
1516
bank 4 slot 2 map_data.lib
1517
...
1518
 
1519
Here you can also use "base" to define the 65816 CPU bank number
1520
(like .BASE works in PV2):
1521
 
1522
[libraries]
1523
bank 0 slot 1 base $80 speed.lib
1524
bank 4 slot 2 base $80 map_data.lib
1525
...
1526
 
1527
You must tell PV2LINK the bank and the slot for the library files.
1528
 
1529
4. If you want to use header and/or footer in your project,
1530
you can type the following:
1531
 
1532
[header]
1533
header.dat
1534
[footer]
1535
footer.dat
1536
 
1537
5. If you want to make value definitions, here's your chance:
1538
 
1539
[definitions]
1540
debug 1
1541
max_str_len 128
1542
start $150
1543
...
1544
 
1545
If flag 'v' is used, PV2LINK displays information about ROM file after a
1546
succesful linking.
1547
 
1548
If flag 'd' is used, PV2LINK discards all unreferenced FREE and SEMIFREE
1549
sections. This way you can link big libraries to your project and PV2LINK
1550
will choose only the used sections, so you won't be linking any dead code/data.
1551
 
1552
If flag 's' is used, a symbol information file is created.
1553
If flag 'S' is used, a symbol information file with breakpoints is created.
1554
 
1555
If flag 'i' is given, PV2LINK will write list files. Note that you must
1556
compile the object and library files with -i flag as well. Otherwise PV2LINK
1557
has no extra information it needs to build list files. Here is an example of
1558
a list file: Let's assume you've compiled a source file called "main.s" using
1559
the 'i' flag. After you've linked the result also with the 'i' flag PV2LINK
1560
has created a list file called "main.lst". This file contains the source
1561
text and the result data the source compiled into. List files are good for
1562
debugging.
1563
 
1564
Make sure you don't create duplicate labels in different places in the
1565
memory map as they break the linking loop. Duplicate labels are allowed when
1566
they overlap each other in the destination machine's memory. Look at the
1567
following example:
1568
 
1569
...
1570
.BANK 0
1571
.ORG $150
1572
 
1573
        ...
1574
        LD      A, 1
1575
        CALL    LOAD_LEVEL
1576
        ...
1577
 
1578
LOAD_LEVEL:
1579
        LD      HL, $2000
1580
        LD      (HL), A
1581
        CALL    INIT_LEVEL
1582
        RET
1583
 
1584
.BANK 1
1585
.ORG 0
1586
 
1587
INIT_LEVEL:
1588
        ...
1589
        RET
1590
 
1591
.BANK 2
1592
.ORG $0
1593
 
1594
INIT_LEVEL:
1595
        ...
1596
        RET
1597
...
1598
 
1599
 
1600
Here duplicate INIT_LEVEL labels are accepted as they both point to the
1601
same memory address (in the program's point of view).
1602
 
1603
 
1604
----------------------------------------------
1605
9... Arithmetics
1606
----------------------------------------------
1607
 
1608
 
1609
PV2 is able to solve really complex calculations like
1610
 
1611
-((HELLO / 2) | 3)
1612
skeletor_end-skeletor
1613
10/2.5
1614
 
1615
so you can write something like
1616
 
1617
LD HL, data_end-data
1618
LD A, (pointer + 1)
1619
CP (TEST + %100) & %10101010
1620
 
1621
PV2LINK also has this ability so it can compute the pending calculations
1622
PV2 wasn't able to solve.
1623
 
1624
The following operators are valid:
1625
 
1626
(, ), | (or), & (and), ^ (power), << (shift left), >> (shift right), +, -,
1627
# (modulo), ~ (xor), *, /, < (get the low byte) and > (get the high byte).
1628
 
1629
Note that you can do NOT using XOR:
1630
 
1631
VALUE_A ~ $FF   = 8bit NOT
1632
VALUE_B ~ $FFFF = 16bit NOT
1633
 
1634
PV2 computes internally with real numbers so (5/2)*2 produces 5, not 4.
1635
 
1636
 
1637
 
1638
----------------------------------------------
1639
10... PV2ASS Flags
1640
----------------------------------------------
1641
 
1642
 
1643
Here are short descriptions for the flags you can give to PV2ASS:
1644
 
1645
You can supply PV2ASS with some (or all or none) of the following option flags.
1646
 
1647
i - Add list file information. Adds extra information to the output so
1648
    PV2LINK can produce list files.
1649
M - PV2 generates makefile rules describing the dependencies of the main
1650
    source file. Use only with flags 'o' and 'l'.
1651
q - Quiet mode. .PRINT* -directives output nothing.
1652
t - Test compile. Doesn't output any files.
1653
v - Verbose mode. Shows a lot of information about the compiling process.
1654
x - Extra compile time definitions. PV2 does extra work by creating
1655
    few helpful definitions on the fly.
1656
 
1657
One (and only one) of the following command flags must be defined.
1658
 
1659
l - Output a library file.
1660
o - Output an object file.
1661
 
1662
Examples:
1663
 
1664
[seravy@localhost tbp]# pv2ass -voi testa.s
1665
[seravy@localhost tbp]# pv2ass -oM testa.s
1666
[seravy@localhost tbp]# pv2ass -l testb.s testb.lib
1667
 
1668
Note that the first example produces file named "testa.o".
1669
 
1670
 
1671
----------------------------------------------
1672
11... Good things to know about PV2ASS
1673
----------------------------------------------
1674
 
1675
 
1676
- Is 64 bytes too little for a string (file names, labels, definition labels,
1677
  etc)? Check out "MAX_NAME_LENGTH" in defines.h.
1678
- PV2ASS preprocessor doesn't expand macros and repetitions. Those are actually
1679
  traversed in the assembling phase.
1680
- PV2ASS's source code is mainly a huge mess, but PV2LINK is quite well
1681
  structured and written. So beware!
1682
- Do not write ".E" into your sources as PV2ASS uses it internally to mark
1683
  the end of a file.
1684
 
1685
 
1686
----------------------------------------------
1687
12... Legal Note
1688
----------------------------------------------
1689
 
1690
PV2ASS and PV2LINK is licensed as GPL software, as are any helper programs.
1691
 
1692
Code in the examples section is licensed under the BSD license.
1693
 
1694
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.