Editing SmartBox OS (section)

== Relocation ==

The relocation method used will not do a complete relocation, ie. 
from ANY address to ANY address.  The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie.  the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems.  What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to.  Because of this programs must be multiples of 256 bytes, ie. 
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code.  To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated.  The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap.  A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie.  &100
for the downloaded version)

 <nowiki>execcall
	LDA #>(execute-address)	; Final execution address offset (LSB)
	STA zero_gp1
	LDA #<(execute-address)	; Final execution address offset (MSB)
	STA zero_gp1+1

	LDA #>(BitMap-address)	; BitMap address offset (LSB)
	STA zero_gp2
	LDA #<(BitMap-address)	; BitMap address offset (MSB)
	STA zero_gp2+1

	LDA #>(execcall-address); Length of data to relocate (LSB)
	STA zero_gp3
	LDA #<(execcall-address); Length of data to relocate (MSB)
	STA zero_gp3+1

	TXA			; Execcall REAL address
	SEC
	SBC #>(execcall-address); Subrtract length
	TAX			; Put it back in X
	TYA			; Ditto for MSB
	SBC #<(execcall-address)
	TAY
	LDA #4			; CALLOS function for Relocate
	JMP OS_CALLOS		; Call CALLOS

BitMap				; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie.  setup internal_vec
and unknownjob_vec etc.).  "address" is the address the code is started to
assemble at, &100 for the version to be uploaded.  The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.