-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.txt
229 lines (177 loc) · 9.68 KB
/
README.txt
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
PandaForth by Torlus (c) 2005 - http://torlus.com/
Based on Bradford J. Rodriguez's CamelForth for the Z80 (c) 1994
===============================================================================
1. About Forth
2. About PandaForth
3. Contents
4. Running the demos
5. Building PandaForth
6. Writing your own code
7. Advanced topics
8. Credits
===============================================================================
1. About Forth
===============================================================================
If you don't know what Forth is, http://www.forth.org/ is a good starting point.
Basically Forth is a stack-based language using "reverse polish" notation.
It provides an interpreter which is able to be extended with new definitions.
Unlike BASIC interpreters, new "definitions" (or "functions", Forth users
generally talk about "words") are _compiled_ which means that there is no
difference in performance between newly created words, and the original ones
provided by the interpreter (except for those few written in assembly).
Forth is a kind of (unmanaged) virtual machine. Unlike Java virtual machines,
a Forth engine is very simple and will usually fit in less than 10Kb
(yes, "ten. kilo. bytes." :)). For design considerations about Forth, I highly
recommend Bradford J. Rodriguez's publications about them.
Check his site at http://www.zetetics.com/bj/papers/.
===============================================================================
2. About PandaForth
===============================================================================
PandaForth is a Direct-Threaded-Code 32-bits Forth, written in ARM assembly.
A few part of the source is in C, in order to use WinterMute's libgba functions,
but not for Forth implementation itself. It should be not too far from ANS-Forth
compliance, for the wordset at least.
One of its funniest features is that you can use the interpreter directly from
your computer if you have a MBV2 cable, by using the "console mode" of the tool
bundled with it.
(see http://www.devrs.com/gba/files/mbv2faqs.php if you don't know what it is)
If you don't have such a cable, you can still test the interpreter features on
hardware on in an emulator, as PandaForth is able to "embed" source with the
help of Damian Yerrick's GBFS library for GBA.
===============================================================================
3. Contents
===============================================================================
The archive contains the following folders :
source/ PandaForth source (C,asm) and libgbfs
source/cam80-12 CamelForth for Z80
libgba/ headers,lib and source for libgba
res/ some resources used by the demo
tools/ Windows/Linux build of GBFS tools, with source
forth/ Forth source : gba-related, demo
At the root of the archive, you will find :
demo.bat to build and run the demo (on emulator)
demoMBV2.bat to build a multiboot image and run it
through a MBV2 cable
buildall.bat script to build all the different configurations
Makefile
PFdemo.gba a ready-to-run cartridge build of the demo
*.gba other builds (without embedded source)
===============================================================================
4. Running the demos
===============================================================================
For the impatient, there is a "PFdemo.gba" ready to run on emulator or hardware.
You will see the interpreter in action, parsing some text, and after a while,
a silly little demo will run for a while. This file has been generated by running
"demo.bat".
If you have a look at the "demo.bat" file, you will notice that it uses GBFS.exe
to append some source files (located in "forth" directory) to an image.
If you are familiar with Forth, you can add your own stuff in these files, re-run
"demo.bat" to test the interpreter.
For the happy few that have a MBV2 cable, then run "demoMBV2.bat".
It will upload PandaForth to your GBA, then switch the PC in console mode,
allowing you then to communicate directly with the interpreter :)
In my configuration, I always get not-so-random "noise" from the PC side, but
the output from PC to GBA is working fine, so you can use the interpreter quite
easily.
===============================================================================
5. Building PandaForth
===============================================================================
If you didn't unpack the archive to C:\Forth as I suggested on my website, do it,
as some paths are absolute.
You will need to have the DevkitARM toolchain (I used r11), and MSYS. All these
items can be found at WinterMute's site at http://www.devkit.tk/.
With a PATH variable properly set up (C:\DevkitARM_r11\bin;C:\msys at the
beginning), you can run the "buildall.bat" script to build the different
configurations.
Note that there is support for XBOO cable, partially tested : the interpreter is
able to output characters to the PC, but for the moment there is no software
supporting a "console mode", as does MBV2's MB.exe.
The "buildall.bat" script will generate 3 files :
- PF.gba, that can run from a cartridge but has no link cable support.
- PFmbv2.gba, that can run from a cartridge and has mbv2 cable link support.
In this case, just run "mb.exe -c -x 255" before powering up the GBA to
enable console mode.
- PFmbv2_mb.gba, that is a multiboot image with mbv2 link support. This is the
one used in the "demoMBV2.bat" script. It uploads to your GBA via the mbv2,
then switch to console mode once it's done.
===============================================================================
6. Writing your own code
===============================================================================
The easier way is to edit or add files into the "forth" folder, so you'll be
able to use the "demo.bat" or "demoMBV2.bat" scripts.
One thing you need to know about file naming : GBFS tool "GBFS.exe" sorts the
files in alphabetical order, so the files will be interpreted by PandaForth
in this order. That's the reason why, for the demo, there is a "a_gba.pf" and
a "z_demo.pf", as the second source needs that the first one to be interpreted
before.
PandaForth is case-sensitive, so be careful when defining/using words :)
Useful commands :
- WORDS that returns the list of available Forth words.
- .S that shows the contents of the stack.
===============================================================================
7. Advanced topics
===============================================================================
* Emedding resources.
To make some resources (bitmaps, etc.) available to PandaForth, a simple and dirty
way is to create a VARIABLE pointing to them, and use .incbin to include them.
Open the "PF.s" source file, and go at the end of it.
You will see the following lines :
8<-----------------------------------------------------------------------------
head PAL_BALL3,9,"PAL_BALL3",dovar,PAL_BALL2
.incbin "C:/Forth/PF4ARM/res/pal3.pal"
.align
.set lastword, link_PAL_BALL3 /* last word */
8<-----------------------------------------------------------------------------
You can insert your declaration like this :
8<-----------------------------------------------------------------------------
head PAL_BALL3,9,"PAL_BALL3",dovar,PAL_BALL2
.incbin "C:/Forth/PF4ARM/res/pal3.pal"
.align
head SMILE,3,"8=]",dovar,PAL_BALL3
.incbin "C:/absolute/path/to/your/file.bin"
.align
.set lastword, link_SMILE /* last word */
enddict:
8<-----------------------------------------------------------------------------
the "head" macro adds an entry to Forth dictionary. The parameters are :
- label name (a name which format is correct as a label name for the assembler)
here : SMILE
- the length of your word (here : 8=] which is 3 characters long)
- the name that will be used within Forth (here : 8=] )
- the name of the previous label (here PAL_BALL3, that was previously the last word).
The "lastword" definition needs also to be changed to point to link_SMILE.
In PandaForth, executing 8=] will push the address of the beginning of your
resource onto the parameter stack.
This solution isn't very good, a better solution can be achieved by extending
PandaForth (see below).
* Extending PandaForth.
PandaForth is very close to CamelForth. I kept the BDOS word (CP/M function call),
which is hooked up to a C function called "service" (see the file "main.c").
BDOS take two parameters : one "service number" and one parameter.
Two service numbers are currently defined :
- 6, used for reading and writing to the console (used by the interpreter).
- 1, that waits for a vblank interrupt.
It's easy to add new functions here. The return value of the function will be
available from Forth in the parameter stack.
===============================================================================
8. Credits
===============================================================================
Many thanks to :
- Bradford J. Rodriguez, for his CamelForth and articles about Forth.
http://www.zetetics.com/bj/papers/
- WinterMute, for DevkitARM, libgba, xboo, and clean Makefile.
http://www.devit.tk/
- Damian Yerrick, for GBFS.
http://www.pineight.com/
- DaLK, for the gfx used in the demo.
- krb, for gba-tt tool I used for the demo.
http://www.pascalorama.com/
- BigRedPimp, for testing.
http://www.bigredpimp.com/
- All infomation sites about GBA, as usual...
http://www.gbadev.org/
http://www.devrs.com/
http://www.work.de/nocash/gbatek.htm
And greetings to people on EFNET #gbadev and #gbadevfr !
Enjoy,
Torlus