goverlays.s
22.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
##########################################################################
#
# This code #includes clipping, lighting, and init code, and ensures
# the proper overlay is in place when needed.
#
##########################################################################
###########################################################################
#################### HOW FAST3D OVERLAYS WORK #############################
###########################################################################
#
# There are two areas of memory in IMEM which use overlays. The first is
# the newt area (where the newton raphson routine exists) and the second is
# the light/clip/init area (where either lighting code, clipping code, init
# code, or done code exists).
#
# NEWT OVERLAY:
#
# To start a task the rspboot microcode is loaded into the beginning of
# IMEM. The rspboot microcode extends from IMEM address 0 beyond IMEM
# address 0x80. Once the rspboot microcode has checked the state of the DP
# and loaded the DMEM into place, it loads the gspFast3D microcode and
# jumps into the gspFast3D entry point. The section of the rspboot
# micrcode which loads IMEM and jumps into gspFast3D is in the first part
# of IMEM, and is entirely above IMEM address 0x80 (the parts of the
# rspboot microcode which come after 0x80 are used for loading DMEM and
# run before the gspFast3D microcode is loaded). The gspFast3D microcode
# is loaded at IMEM address 0x80. The entry point for the gspFast3D microcode
# is at IMEM 0x80, and the code at this address (in gspFast3D) jumps to the
# gspFast3D init routine which is later in memory. The init routine loads
# the newt overlay which begins at IMEM address 0. This overlay consists
# of the newton raphson routine followed by the beginning of the gspFast3D
# microcode's main loop. This Newt overlay overwrites the jump to the init
# code which existed at IMEM address 0x80. As you can see the main loop
# is loaded partially in the initial load of gspFast3D code and partially
# in the load of the newt overlay. (see the note below on how the build is
# done for information on how this code is created).
#
#
# NEWT OVERLAY MEMORY MAP:
#
# IMEM rspboot code gspFast3D code newt overlay
# ADDR
# ----- ------------------- ---------------------- ------------------
# 0x00 | j DMEMLOAD |NEWTON:
# . |IMEMLOAD: | <newton raphson
# . | code to load | code>
# . | gspFast3D IMEM | .
# . | . | .
# . | . | .
# . | . | .
# . | j 0x80 (entry | .
# . | pt of | .
# . | gspFast3D) | .
# . |DMEMLOAD: | .
# . | code to check | .
# . | state of DP | j return
# . | and load |MAINLOOP:
# . | DMEM for | <gspFast3d
# . | gspFast3D | main loop
# . | microcode | code>
# . | . | .
# . | . | .
# . | . | .
# 0x80 | . | j DOINIT | .
# . | . | <rest of main loop>
# . | . | .
# . | . | .
# . | j IMEMLOAD | .
# . |<end> | .
# . | .
# . | .
# . | .
# . | .
# . | .
# . | .
# . | .
# . | .
# . | .
# . |DOINIT:
# . | <init code>
# . | <load newt overlay>
# . | .
# . | .
# . | j MAINLOOP
# . | nop
# . | nop
# . | nop
# . | .
# . | .
# . | .
# . | nop
# . | nop
# . | nop
# . | <setup code>
# . | .
# . | .
# . | .
# 0xffc |<end of gspFast3D code>
#
#
# CLIP/LIGHTING/INIT/DONE OVERLAY:
#
# The other overlay allows lighting and clipping to share codespace.
# It uses the same area of IMEM which originally contains the gspFast3D
# INIT code. There are entry points for Clipping and Lighting (startClip
# and doLight respectively). In the original load of gspFast3D microcode
# the INIT code lies just after these two entry points. The Clipping
# entry point contains code to load the clipping overlay. The Lighting
# entry point contains code to load the lighting overlay. The overlay
# loading routine (not shown in the memory map below) returns to the address
# stored in register $30 (the overeturn register). The startclip entry point
# loads overeturn=startClip so that once the clipping overlay is loaded the
# SP jumps back to the startClip routine. The lighting entry point loads
# overeturn=doLight so that once the lighting overlay is loaded theSP jumps
# back to the doLight routine. If the light overlay is loaded and the
# light entry point is called, then the lighting code is right there and
# it executes. If the clip overlay is loaded and the clip entry point is
# called, there is a jump into the clip routine (which is already loaded)
# and it executes. If the lighting or clipping entry point is called and
# the wrong overlay is in place then the code at the entry point causes
# the correct overlay to be loaded and jumped to. Therefore it is not
# neccessary to check whether the correct overlay is loaded or not; the
# SP simply jumps to the code it wants, and either that code is there (and
# it executes) or it's not there (and the overlay is loaded and executes).
#
# When the task is done (or a yield occurs) then the SP must execute the done
# routine. This routine is also an overlay which shares IMEM addresses with
# the clip/light/init routines. When the SP determines that it is done (or
# needs to yield) then it sets overeturn=startClip and then jumps to the
# overlay loading routine which causes the done overlay to be loaded at
# the startClip address. The overlay routine then returns to the startClip
# address (which now contains the done code) and the done code (or yield
# code) executes.
#
# CLIP/LIGHTING/INIT/DONE OVERLAY MEMORY MAP:
#
# IMEM gspFast3D code light overlay clip overlay
# ADDR gspFast3D gflight gclip.only
# ---------- ----------------- ------------------- -------------------
# . |
# . |
# . |
# startClip: | | |
# . |<load clip |<load clip |j doclip
# . | overlay | overlay |
# . | and return to | and return to |
# . | startClip> | startClip> |
# . | | |
# . | | |
# doLight: | | |
# . |<load light |<do lighting> |<load light
# . | overlay | . | overlay
# . | and return to | . | and return to
# . | doLight> | . | doLight>
# . | | . |
# . | | . |
# doInit: | | . |
# doclip: | | . |
# . |<init code> | . |<do clipping>
# . |<load newt | . | .
# . | overlay> | . | .
# . |j MAINLOOP | . | .
# . |nop | . | .
# . |nop | . | .
# . |nop | . | .
# . | . |j return | .
# . | . |<end lighting> | .
# . | . | .
# . |nop | .
# . |nop |j return
# . |nop |<end clipping>
# . |<setup code>
# . | .
# . | .
# . | .
# . | .
# . | .
#
#
# HOW THE BUILD OF OVERLAYS WORKS:
#
# There are some intricacies the way we build overlays which I will describe
# here. One is how we align the <more gspFast3D code> section following the
# overlay section of IMEM. Another is how we split the main loop into 2
# parts so that half can be loaded by the gspFast3D load and the other half
# can be loaded with the newt overlay.
#
# To align the overlays a dummy build is done. This build is named
# gspFast3D_tmp. We also do a dummy build of the clip code called
# gclip.only_tmp. The gspFast3D_tmp build places the setup code (label
# clipAndSetup:) immediately after the end of the init code. The gclip.only_tmp
# build places the clip code where it would be if the clip overlay was loaded.
# We actually want the setup code to go in the gspFast3D build at the address
# following the end of the clipping code in the gclip.only overlay so that when
# the gclip.only overlay gets loaded it does not overwrite the setup code.
# To do this we place enough nops to fill the space between the end of the init
# code and the beginning of where the setup code should go. The file which
# contains these nops is called gfillnops.s and is automatically created by the
# fillnops program (compiled from fillnops.c). The fillnops program takes the
# gspFast3D_tmp build and the gclip.only_tmp build and finds the end of the init
# code in the gspFast3D_tmp build (which is where the setup code starts in that
# build, label clipAndSetup:) and the end of the clip code in the gclip.only_tmp
# build (label clipKill:). The number of nops to put in the gfillnops.s file is
# equal to (the end of the clip code) - (the start of the setup code).
# once the gfillnops.s file is created we can build the final gspFast3D build,
# including the gfillnops.s file (full of the correct number of nops) to fill
# the space between the end of the init code and the beginning of the setuo code.
# As I mentioned earlier, this is all so that the clip overlay does not clobber
# any of the setup code when it gets loaded. IMPORTANT NOTE: This assumes that the
# clip overlay is larger than the lighting overlay. If the lighting overlay were
# larger than the clip overlay then we would have to do a dummy build of the
# lighting code (instead of a dummy build of the clip code).
#
# We split the main loop into 2 sections, loading the second half in the initial
# load of the gspFast3D code (loaded by rspboot) and loading the first half as
# part of the newton overlay. We use the buildtask to create the various overlays
# (including the initial section which rspboot automatically loads at the address
# 0x80). The buildtask program takes a number of object files as arguments and
# creates an overlay out of each one. Each overlay has a descriptor in the
# beginning of DMEM which is used by the overlay loading routine (loadOverlay: in
# gmain.s). The arguments used in the makefile are:
# buildtask -f 1 -o gspFast3D -s 34 -p gboot.u gspFast3D.u \
# -l 34 gspFast3D.u gclip.only.u gflight.u gdone.u
# which make more sense when printed:
# buildtask -f 1 -o gspFast3D \
# -s 34 -p gboot.u gspFast3D.u \
# -l 34 gspFast3D.u \
# gclip.only.u \
# gflight.u \
# gdone.u
# I will explain the arguments one at a time:
# -f 1 == use only 1 DMEM file (overlays don't have
# their own DMEM files).
# -o gspFast3D == the result will be called gspFast3D.
# -s 34 -p gboot.u gspFast3D.u == The first overlay (The main code block which
# is loaded by rspboot) is created from
# gspFast3D.u. The -s 34 option removes the
# first 34 instructions from the beginning of
# the file. These 34 instructions include the
# newton raphson routine and the start of the
# main loop. The -p gboot.u option appends
# the file gboot.u at the beginning of the
# overlay (in place of the 34 instructions).
# The gboot.u file contains a jump to the start
# of the init routine and an instruction in the
# delay slot. Note that we removed the first
# 34 instructions, and added 2 more on.
# Therefore there are 32 fewer instructions at
# the start of the code. 32 instructions times
# 4 bytes per instruction = 0x80, and ox80 is
# the address at which the rspboot code loads
# this overlay.
# -l 34 gspFast3D.u == The second overlay (The newt overlay) is just
# the first 34 instructions from the
# gspFast3D.u file. This includes the newton
# raphson routine and the start of the main
# main loop.
# gclip.only.u == The thrid overlay is the clip overlay.
# gflight.u == The fourth overlay is the lighting overlay.
# gdone.u == The fifth overlay is the done overlay.
#
# So the result is an initial overlay which is loaded at address 0x80 (by rspboot)
# which begins with a jump to the init routine. The init routine loads the
# second overlay which overwrites the rspboot code and the first 2 instructions
# of the initial overlay (the first 2 instructions were the jump to the init
# code. When lighting or clipping is needed it is loaded over the init code. When
# the task is done the done code is loaded over the clipping, lighting, or init
# code.
#
# -Acorn 7/9/96
#
###########################################################################
#if defined(CLIP_ALONE)||defined(FLIGHT)
#include <rsp.h>
#include "mbi.h"
.text startClip
#include "gdmem.h"
#include "gfx_regs.h"
#endif /* CLIP_ALONE or FLIGHT */
.align 8
#if defined(FLIGHT) || defined(FASTLIGHT3D)
###########################################################################
#################### LOAD CLIPPING ########################################
###########################################################################
#
# Clip Routine (overlay load)
#
# This code is at the clip routine's entry point when the clipping overlay
# is not loaded. It loads the clip overlay and then jumps back to here
# again (where the clip routine will have been loaded)
#
###########################################################################
#
#
.unname return_save
.name overp, $30 # which overlay to load
.name overeturn, $21 # return address from loadOverlay
startClip:
ori overp, zero, OVERLAY_CLIP # load clipping
beq zero,zero,loadOverlay # jump to the overlay loading routine
taskDone: # taskDone here in DONE overlay
lh overeturn, DOCLIP(zero) # return to clip code
###BRANCH OCCURS to loadOverlay: which will return to doClip:
.unname overp
.unname overeturn
.name return_save, $30
#
#
###########################################################################
#endif /* FLIGHT or FASTLIGHT3D */
#ifdef FLIGHT
###########################################################################
#################### PERFORM LIGHTING #####################################
###########################################################################
#
# Lighting Routine (actual code)
#
# This code is at the lighting routine's entry point when the lighting
# overlay is loaded. It performs lighting.
#
## do lighting
#include "gflight.s"
#endif /* FLIGHT */
#
#
###########################################################################
#ifdef CLIP_ALONE
###########################################################################
#################### JUMP TO CLIPPING ROUTINE #############################
###########################################################################
#
# Clip Routine (actual code)
#
# This code is at the clip routine's entry point when the clipping overlay
# is loaded. It jumps to the clipping routine (just after the
# LOAD LIGHTING code which follows this code)
#
startClip:
beq zero, zero, doClip # jump into clipping code
sh return,RETURNJUMP2($0) # save return address from setup
nop # delay slot
nop #
#
#
###########################################################################
#endif /* CLIP_ALONE */
#if defined(CLIP_ALONE) || defined(FASTLIGHT3D)
###########################################################################
#################### LOAD LIGHTING ########################################
###########################################################################
#
# Lighting Routine (overlay load)
#
# This code is at the lighting routine's entry point when the lighting
# overlay is not loaded. It loads the lighting overlay and then jumps back
# to here again (where the lighting routine will have been loaded)
#
.unname return_save
.name overp, $30 # which overlay to load
.name overeturn, $21 # return address from loadOverlay
doLight:
ori overp, zero, OVERLAY_LIGHT # load lighting
beq zero, zero, loadOverlay # jump to the overlay loading routine
lh overeturn,DOLIGHT(zero) # return to clip code
###BRANCH OCCURS to loadOverlay: which will return to doLight:
.unname overp
.unname overeturn
.name return_save, $30
#
#
###########################################################################
#endif /* CLIP_ALONE or FASTLIGHT3D */
#if !defined(FASTLIGHT3D) && !defined(FLIGHT)
###########################################################################
#################### PERFORM CLIPPING #####################################
###########################################################################
#
# Clip Routine (actual code)
#
# This code follows the LOAD LIGHTING code when the clipping overlay
# is loaded. It performs clipping.
#
#include "gclip.s"
#
#
###########################################################################
#endif /* CLIP_ALONE */
#ifdef FASTLIGHT3D
###########################################################################
#################### PERFORM INITIALIZATION ###############################
###########################################################################
#
# Init Routine (actual code)
#
# This code is in the original load of the microcode. It sets up the
# RSP and loads the newt.s (newton raphson) overlay over the boot
# microcode. Then it loads the beginning of the first display list
# and jumps into the main loop.
#
#include "ginit.s"
j DMAWaitDL # return to main loop and begin
nop
#
#
###########################################################################
###########################################################################
#################### PERFORM YIELD RESTART ################################
###########################################################################
#
# Yield Restart Routine (actual code)
#
# This code is in the original load of the microcode. It gets called by the
# init code if this task is a restart of a yielded task.
#
#define YIELD_RESTART
#include "gyield.s"
#undef YIELD_RESTART
#
#
###########################################################################
# Align code following
.align 8
#ifdef NODATA
###########################################################################
#################### DETERMINE ALIGNMENT OF CODE FOLLOWING OVERLAY ########
###########################################################################
#
# These labels help the build process determine where the overlay ends
# and therefore where the code following the overlay should begin.
#
clipAndSetup:
nop
beginSetup:
nop
#
#
###########################################################################
#else /* NODATA */
###########################################################################
#################### ALIGN CODE FOLLOWING OVERLAY #########################
###########################################################################
#
# The code in the overlay to begin with (the init and yield code) is not as
# long as the overlays (specifically, the clipping code is the longest).
# Therefore we need a number of nop's to separate the end of the init code
# from the code which follows the overlays. The correct number of nop's
# are placed into the gfillnops.s files and included here. The gfillnops
# files are created during the build process by the fillnops program.
#
#ifdef OUTPUT_DRAM
#include "gfillnops.dram.s"
#else /* OUTPUT_DRAM */
#ifdef OUTPUT_FIFO
#include "gfillnops.fifo.s"
#else /* OUTPUT_FIFO */
#include "gfillnops.s"
#endif /* OUTPUT_FIFO */
#endif /* OUTPUT_DRAM */
#endif /* NODATA */
#
#
###########################################################################
#endif /* FASTLIGHT3D */