Subject: Compiling apps with SDCC

From: "Cyrano Jones" <cyranojones_lalp@...>
Date: Fri, 14 Dec 2007 21:56:46 -0000

; SDCC crt0.s for a mailstation app

	.module  crt0
	
	.globl	_eventhandler
	.globl	_graphics       
	.globl	_strings
	.globl	_dunno
	.globl	_install
	
	.area	_CODE
	jp		_eventhandler
	.dw		_graphics       
	.dw		_strings
	.dw		_dunno
	jp		_install

	.area	_HOME
	.area   _GSINIT
_gsinit::
	.area   _GSFINAL
	ret
	
	.area	_DATA 
	.area   _BSS
	.area   _HEAP

; Rather than disturb the simplicity of the above code, 
; I will put the comments down here.
;
; ".module crt0" simply defines a name for the linker to use 
; if it needs to report where an undefined symbol was used.
;
; ".globl somesymbol" tells the assembler that somesymbol 
; will not be resolved until link time.
;
; ".area SOMEAREA" lets the linker group similar types of 
; code or data from the various modules, into single 
; contiguous areas in memory.  
;
; This first code area will be the entrypoint to our code.  
; It is mandatory that crt0.o be the first module linked
; for this reason.  
;
; Here we just make a jump to "eventhandler", and
; leave a couple of pointers to resource data.  The 
; mailstation firmware expects these to be at the head of 
; any app.  I added a jump to an install routine, just so 
; it too can have a fixed address.
;
; We mention all the areas that our program will use to
; force the linker to place them in a particular order.  
; The _CODE & _DATA segments will be pegged to particular 
; addresses by the link command. _HOME, _GSINIT, & _GSFINAL 
; will be in ROM, after the code segment.  _BSS & _HEAP 
; will be in RAM, after the data segment
;
; The compiler will place any code for initializing globals 
; into the _GSINIT section.  Here, we place a label as the 
; first thing in _GSINIT, and a "ret" as the last thing, 
; allowing the globals defined in all modules to be run 
; with a single call to _gsinit.
;
; Just what is crt0?
;
; crt0.o is a module that is automatically linked by SDCC 
; when you link your code.  I imagine historically it 
; contained code to run a crt terminal.  Now SDCC uses it 
; to link any sort of startup code you may need for your 
; program.  Typically this would be:
;
;  1) init stack pointer.  
;  2) set up interrupts.
;  3) init the globals.  
;  4) call your "main" function.  
;  5) implement any exit code needed.
;
; We don't do any of that!  :-)
;
; Since we are going to run under the mailstations 
; existing OS, we can skip 1 & 2, 'coz they are done 
; for us by ms firmware.  
;
; We skip number 3 because our code is just an event 
; handler, and we do not want our globals re-init'ed on 
; every event.  We will let our code call gsinit itself, 
; when it receives a "sig_init" from the mailstation's OS.
;
; As for 4 & 5, we don't need any exit code, we just 
; return to the ms OS after each event we process.  
; Since we don't need to come back here, rather than 
; call the "main" func, we just jump to it.  This has 
; the added advantage of leaving the stack-frame as is, 
; so we can access the passed event directly.
;
; Voilà!