No$GBA Xboo Readme

Nocash Multiboot/Burstboot Uploader (c) 2001,2002 Martin Korth

This is the standalone DOS version of the multiboot upload program,
which is also being built-in into the no$gba debuggers utility menu.

Contents
--------

1) AUX Multiboot PC-to-GBA Cable
2) Extended Multiboot Header
3) Burst Boot Backdoor
4) Downloading the GBA BIOS

I hope this will be easy to use. I've spent about three weeks (fulltime)
into trying to get it as fast and comfortable as possible, and by using
as little hardware as possible...

http://www.work.de/nocash/

Many thanks to arundel for testing dozens of beta versions on 100MHz,
350MHz, and 700MHz computers until the code worked with fast CPUs, and
without external pull-up resistors.

1) AUX Multiboot PC-to-GBA Cable
--------------------------------

Below describes how to connect a PC parallel port to the GBA link port,
allowing to upload small programs (max 256 KBytes) from no$gba's Utility
menu (or by using the standalone DOS version) into real GBAs.

This is possible because the GBA BIOS includes a built-in function for
downloading & executing program code even when no cartridge is inserted.
The program is loaded to 2000000h and up in GBA memory, and must contain
cartridge header information (nintendo logo, checksum, etc) just as for
normal ROM cartridges.

Basic Cable Connection
The general connection is very simple (only needs four wires), the only
problem is that you need a special GBA plug or otherwise need to solder
wires directly to the GBA mainboard (see Examples below).
  GBA  Name  Color                SUBD CNTR Name
  2    SO    Red    ------------- 10   10   /ACK
  3    SI    Orange ------------- 14   14   /AUTOLF
  5    SC    Green  ------------- 1    1    /STROBE
  6    GND   Blue   ------------- 19   19   GND
Optionally, also connect the following signals (see notes below):
  4    SD    Brown  ------------- 17   36   /SELECT  (double speed burst)
  -    -     -       +----------- 2..9 2..9 D0..7    (pull-up)
  -    -     -       |---[===]--- 14   14   /AUTOLF  (pull-up)
  -    -     -       |---[===]--- 1    1    /STROBE  (pull-up)
  -    -     -       +---[===]--- 17   36   /SELECT  (pull-up)
  RESET (mainboard) ------|>|---- 16   31   /INIT    (automatic reset)
Notes: The GBA Pins are arranged from left to right as 2,4,6 in upper
row, and 1,3,5 in lower row; outside view of GBA socket; flat side of
socket upside. The above "Colors" are as used in most or all standard
Nintendo link cables, note that Red/Orange will be exchanged at one end
in cables with crossed SO/SI lines. At the PC side, use the SUBD pin
numbers when connecting to a 25-pin SUBD plug, or CNTR pin numbers for
36-pin Centronics plug.

Optional SD Connection (Double Speed Burst)
The SD line is used for Double Speed Burst transfers only, in case that
you are using a gameboy link plug for the connection, and if that plug
does not have a SD-pin (as such from older 8bit gameboy cables), then
you may leave out this connection. Burst Boot will then only work half
as fast though.

Optional Pull-Ups (Improves Low-to-High Transition Speed)
If your parallel port works only with medium or slow delay settings,
try to connect 570 Ohm resistors to each of the strobe/autolf/select
outputs, and the other resistor pin to any or all of the parallel port
pin 2..9 data lines (xboo outputs high to all data lines).

Optional Reset Connection
The Reset connection allows to reset & upload data even if a program in
the GBA has locked up (or if you've loaded a program that does not
support nocash burst boot). - Without reset connection you'd then
manually have to reset the GBA by switching it off and on.
The RESET signal is labeled as such on the GBA mainboard. The diode
(1N4148 or similiar) is required because otherwise strong INIT signals
would pull-up the RESET signal, preventing the GBA from automatically
resetting itself when switched on.

Optional Power Supply Connection
Also, you may want to connect the power supply to parallel port data
lines. Different parallel ports output different voltages/amperes
though, maybe using a large Z-diode could be used to get a stable
voltage with most ports. Even with strong ports, it'll probably not
work when inserting a very power-hungry cartridge into the GBA.

Transmission Speed
The first transfer will be very slow, and the GBA BIOS will display
the boot logo for at least 4 seconds, even if the transfer has
completed in less time. Once when you have uploaded a program with
burst boot backdoor, further transfers will be ways faster. The
table below shows transfer times for 0KByte - 256KByte files:
  Boot Mode_____Delay 0_______Delay 1_______Delay 2_____
  Double Burst  0.1s - 1.8s   0.1s - 3.7s   0.1s - 5.3s
  Single Burst  0.1s - 3.6s   0.1s - 7.1s   0.1s - 10.6s
  Normal Bios   4.0s - 9.0s   4.0s - 12.7s  4.0s - 16.3s
All timings measured on a 66MHz computer, best possible transmission
speed should be 150KBytes/second. Timings might slightly vary
depending on the CPU speed and/or operating system. Synchronization
is done by I/O waitstates, that should work even on faster computers.
Non-zero delays are eventually required for cables without pull-ups.

Requirements
Beside for the cable and plugs, no special requirements.
The cable should work with all parallel ports, including old-fashined
uni-directional printer ports, as well as modern bi-directional EPP
ports. Transfer timings should work stable regardless of the PCs CPU
speed (see above though), and regardless of multitasking interruptions.
Both no$gba and the actual transmission procedure are using some 32bit
code, so that either one currently requires 80386SX CPUs or above.

Windows NT/2000/etc.
NT/2000/etc. prevent to access parallel ports directly, this problem can
be reportedly healed by using special drivers (such like giveio, totalio,
or userport), which would be possibly required to be called from inside
of no$gba. If anybody can supply information on where to download & how
to use these drivers, please let me know!
Note: Windows 95/98/etc. are working fine without such drivers, also,
the DOS version of the uploader might work okay even under NT/2000.

Connection Examples
As far as I can imagine, there are four possible methods how to connect
the cable to the GBA. The first two methods don't require to open the
GBA, and the other methods also allow to connect optional power supply
and reset signal.
  1) Connect it to the GBA link port. Advantage: No need to
     open/modify the GBA. Disadvantage: You need a special plug,
     (typically gained by removing it from a gameboy link cable).
  2) Solder the cable directly to the GBA link port pins. Advantages:
     No plug required & no need to open the GBA. Disadvantages:
     You can't remove the cable, and the link port becomes unusable.
  3) Solder the cable directly to the GBA mainboard. Advantage: No
     plug required at the GBA side. Disadvantage: You'll always
     have a cable leaping out of the GBA even when not using it,
     unless you put a small standard plug between GBA and cable.
  4) Install a Centronics socket in the GBA (between power switch
     and headphone socket). Advantage: You can use a standard
     printer cable. Disadvantages: You need to cut a big hole into
     the GBAs battery box (which cannot be used anymore), the big
     cable might be a bit uncomfortable when holding the GBA.
Personally, I've decided to use the lastmost method as I don't like
ending up with hundreds of special cables for different purposes, and
asides, it's been fun to damage the GAB as much as possible.

Note
The above used PC parallel port signals are typically using 5V=HIGH
while GBA link ports deal with 3V=HIGH. From my experiences, the
different voltages do not cause communication problems (and do not
damage the GBA and/or PC hardware), and after all real men don't care
about a handful of volts, however, use at own risk.

2) Extended Multiboot Header
----------------------------

Beside for the normal cartridge header at 2000000h-20000BFh, multiboot
uploaded programs must contain some additional entries: Multiboot
Entry Point(s), and two reserved bytes which will be overwritten by
the GBA BIOS download procedure.

20000C0h - Normal/Multiplay mode Entry Point
This entry is used only if the GBA has been booted by using Normal or
Multiplay transfer mode (but not by Joybus mode).
Typically deposit a ARM-32bit "B <start>" branch opcode at this
location, which is pointing to your actual initialization procedure.
(The normal ROM-entry point at 2000000h (aka 8000000h) is ignored.)

20000C4h (BYTE) - Boot mode
The slave GBA download procedure overwrites this byte by a value which
is indicating the used multiboot transfer mode.
  Value  Expl.
  01h    Joybus mode
  02h    Normal mode
  03h    Multiplay mode
Typically set this byte to zero by inserting DCB 00h in your source.
Be sure that your uploaded program does not contain important program
code or data at this location, or at the ID-byte location below.

20000C5h (BYTE) - Slave ID Number
If the GBA has been booted in Normal or Multiplay mode, this byte
becomes overwritten by the slave ID number of the local GBA (that'd be
always 01h for normal mode).
  Value  Expl.
  01h    Slave #1
  02h    Slave #2
  03h    Slave #3
Typically set this byte to zero by inserting DCB 00h in your source.
When booted in Joybus mode, the value is NOT changed and remains the
same as uploaded from the master GBA.

20000C6h..20000DFh - Not used
Appears to be unused.

20000E0h - Joybus mode Entry Point
If the GBA has been booted by using Joybus transfer mode, then the entry
point is loacted at this address rather than at 20000C0h. Either put
your initialization procedure directly at this address, or redirect to
the actual boot procedure by depositing a "B <start>" opcode here,
either one using 32bit ARM code. Or, if you are not intending to support
joybus mode (which is probably rarely used), ignore this entry.

Preferably point the ROM-Entry Point at 2000000h/8000000h to a separate
procedure that copies your program from ROM (8000000h) to RAM (2000000h),
and then jump to the RAM entry point at 20000C0h. By this method your
program will work both as ROM cartridge and as multiboot program.
Aye, this should be obvious, but apparently not to everybody out there ;-/

3) Burst Boot Backdoor
----------------------

When writing multiboot compatible programs, always include a burst boot
"backdoor", this will allow yourself (and other people) to upload programs
much faster as when using the normal GBA BIOS multiboot function.
Aside from the improved transmission speed, there's no need to reset the
GBA each time (eventually manually if you do not have reset connect), and,
most important, the time-consuming nintendo-logo intro is bypassed.

The Burst Boot Protocol
In your programs IRQ handler, add some code that watches out for burst
boot IRQ requests. When sensing a burst boot request, download the actual
boot procedure, and pass control to that procedure.
  Send (PC)    Reply (GBA)
  "BRST"       "BOOT"        ;request burst, and reply <prepared> for boot
  <wait 1/16s> <process IRQ> ;long delay, allow slave to enter IRQ handler
  llllllll     "OKAY"        ;send length in bytes, reply <ready> to boot
  dddddddd     --------      ;send data in 32bit units, reply don't care
  cccccccc     cccccccc      ;exchange crc (all data units added together)
Use normal mode, 32bit, external clock for all transfers. The received
highspeed loader (currently approx. 180h bytes) is to be loaded to and
started at 3000000h, which will then handle the actual download
operation.

Below is an example program which works with multiboot, burstboot, and as
normal rom/flashcard. The source can be assembled with a22i (the no$gba
built-in assembler, see no$gba utility menu). When using other/mainstream
assemblers, you'll eventually have to change some directives, convert
numbers from NNNh into 0xNNN format, and define the origin somewhere in
linker/makefile instead of in source code.

.arm            ;select 32bit ARM instruction set
.gba            ;indicate that it's a gameboy advance program
.fix            ;automatically fix the cartridge header checksum
org 2000000h    ;origin in RAM for multiboot-cable/no$gba-cutdown compatibility
;------------------
;cartridge header/multiboot header
 b     rom_start                ;-rom entry point
 dcb   ...insert logo here...   ;-nintento logo (156 bytes)
 dcb   'XBOO SAMPLE '           ;-title (12 bytes)
 dcb   0,0,0,0,  0,0            ;-game code (4 bytes), maker code (2 bytes)
 dcb   96h,0,0                  ;-fixed value 96h, main unit code, device type
 dcb   0,0,0,0,0,0,0            ;-reserved (7 bytes)
 dcb   0                        ;-software version number
 dcb   0                        ;-header checksum (set by .fix)
 dcb   0,0                      ;-reserved (2 bytes)
 b     ram_start                ;-multiboot ram entry point
 dcb   0,0                      ;-multiboot reserved bytes (destroyed by BIOS)
 dcb   0,0                      ;-blank padded (32bit alignment)
;------------------
irq_handler:  ;interrupt handler (note: r0-r3 are pushed by BIOS)
 mov    r1,4000000h             ;\get I/O base address,
 ldr    r0,[r1,200h] ;IE/IF     ; read IE and IF,
 and    r0,r0,r0,lsr 16         ; isolate occurred AND enabled irqs,
 add    r3,r1,200h   ;IF        ; and acknowledge these in IF
 strh   r0,[r3,2]               ;/
 ldrh   r3,[r1,-8]              ;\mix up with BIOS irq flags at 3007FF8h,
 orr    r3,r3,r0                ; aka mirrored at 3FFFFF8h, this is required
 strh   r3,[r1,-8]              ;/when using the (VBlank-)IntrWait functions
 and    r3,r0,80h ;IE/IF.7 SIO  ;\
 cmp    r3,80h                  ; check if it's a burst boot interrupt
 ldreq  r2,[r1,120h] ;SIODATA32 ; (if interrupt caused by serial transfer,
 ldreq  r3,[msg_brst]           ; and if received data is "BRST",
 cmpeq  r2,r3                   ; then jump to burst boot)
 beq    burst_boot              ;/
 ;... insert your own interrupt handler code here ...
 bx     lr                      ;-return to the BIOS interrupt handler
;------------------
burst_boot:     ;requires incoming r1=4000000h
 ;... if your program uses DMA, disable any active DMA transfers here ...
 ldr   r4,[msg_okay]            ;\
 bl    sio_transfer             ; receive transfer length/bytes & reply "OKAY"
 mov   r2,r0 ;len               ;/
 mov   r3,3000000h   ;dst       ;\
 mov   r4,0  ;crc               ;
@@lop:                          ;
 bl    sio_transfer             ; download burst loader to 3000000h and up
 stmia [r3]!,r0      ;dst       ;
 add   r4,r4,r0      ;crc       ;
 subs  r2,r2,4       ;len       ;
 bhi   @@lop                    ;/
 bl    sio_transfer             ;-send crc value to master
 b     3000000h  ;ARM state!    ;-launch actual transfer by starting the loader
;------------------
sio_transfer:  ;serial transfer subroutine, 32bit normal mode, external clock
 str   r4,[r1,120h]  ;siodata32 ;-set reply/send data
 ldr   r0,[r1,128h]  ;siocnt    ;\
 orr   r0,r0,80h                ; activate slave transfer
 str   r0,[r1,128h]  ;siocnt    ;/
@@wait:                         ;\
 ldr   r0,[r1,128h]  ;siocnt    ; wait until transfer completed
 tst   r0,80h                   ;
 bne   @@wait                   ;/
 ldr   r0,[r1,120h]  ;siodata32 ;-get received data
 bx    lr
;---
msg_boot dcb 'BOOT'     ;\
msg_okay dcb "OKAY"     ; ID codes for the burstboot protocol
msg_brst dcb "BRST"     ;/
;------------------
download_rom_to_ram:
 mov  r0,8000000h  ;src/rom     ;\
 mov  r1,2000000h  ;dst/ram     ;
 mov  r2,40000h/16 ;length      ; transfer the ROM content
@@lop:                          ; into RAM (done in units of 4 words/16 bytes)
 ldmia [r0]!,r4,r5,r6,r7        ; currently fills whole 256K of RAM,
 stmia [r1]!,r4,r5,r6,r7        ; even though the proggy is smaller
 subs  r2,r2,1                  ;
 bne   @@lop                    ;/
 sub   r15,lr,8000000h-2000000h ;-return (retadr rom/8000XXXh -> ram/2000XXXh)
;------------------
init_interrupts:
 mov  r4,4000000h               ;-base address for below I/O registers
 ldr  r0,=irq_handler           ;\install IRQ handler address
 str  r0,[r4,-4]   ;IRQ HANDLER ;/at 3FFFFFC aka 3007FFC
 mov  r0,0008h                  ;\enable generating vblank irqs
 strh r0,[r4,4h]   ;DISPSTAT    ;/
 mrs  r0,cpsr                   ;\
 bic  r0,r0,80h                 ; cpu interrupt enable (clear i-flag)
 msr  cpsr,r0                   ;/
 mov  r0,0                      ;\
 str  r0,[r4,134h] ;RCNT        ; init SIO normal mode, external clock,
 ldr  r0,=5080h                 ; 32bit, IRQ enable, transfer started
 str  r0,[r4,128h] ;SIOCNT      ; output "BOOT" (indicate burst boot prepared)
 ldr  r0,[msg_boot]             ;
 str  r0,[r4,120h] ;SIODATA32   ;/
 mov  r0,1                      ;\interrupt master enable
 str  r0,[r4,208h] ;IME=1       ;/
 mov  r0,81h                    ;\enable execution of vblank IRQs,
 str  r0,[r4,200h] ;IE=81h      ;/and of SIO IRQs (burst boot)
 bx   lr
;------------------
rom_start:   ;entry point when booted from flashcart/rom
 bl   download_rom_to_ram       ;-download ROM to RAM (returns to ram_start)
ram_start:   ;entry point for multiboot/burstboot
 mov  r0,0feh                   ;\reset all registers, and clear all memory
 swi  10000h ;RegisterRamReset  ;/(except program code in wram at 2000000h)
 bl   init_interrupts           ;-install burst boot irq handler
 mov  r4,4000000h               ;\enable video,
 strh r4,[r4,000h] ;DISPCNT     ;/by clearing the forced blank bit
@@mainloop:
 swi  50000h ;VBlankIntrWait    ;-wait one frame (cpu in low power mode)
 mov  r5,5000000h               ;\increment the backdrop palette color
 str  r8,[r5]                   ; (ie. display a blinking screen)
 add  r8,r8,1                   ;/
 b    @@mainloop
;------------------
.pool
end

Downloading the GBA BIOS
------------------------

The new Xboo version can be used to download the BIOS from the GBA.
Specify "/b <file>" in commandline, <file> may be any GBA program with
valid header. With the /b switch, Xboo will upload that header, followed
by a small download procedure, which will then send the BIOS data to PC,
being saved in file "Xboo.tmp". When using that file with emulators,
rename it to the desired filename (no$gba would accept either Gba.rom, or
No$gba.rom, however, please use only ONE of that filenames, not both!)