sdccman.txt

很少见的源码公开的msc51和z80的c编译器。

Well you get the idea. 

For compatibility with the previous version of the compiler,
the following syntax for pointer declaration is still supported
but will disappear int the near future. 

unsigned char _xdata *ucxdp; /* pointer to data in external
ram */ 
unsigned char _data  *ucdp ; /* pointer
to data in internal ram */ 
unsigned char _code  *uccp ; /* pointer
to data in R/O code space */
unsigned char _idata *uccp;  /*
pointer to upper 128 bytes of ram */

All unqualified pointers are treated as 3-byte (4-byte for
the ds390) generic pointers. These type of pointers can
also to be explicitly declared.

unsigned char _generic *ucgp;

The highest order byte of the generic pointers contains the
data space information. Assembler support routines are called
whenever data is stored or retrieved using generic pointers.
These are useful for developing reusable library routines.
Explicitly specifying the pointer type will generate the
most efficient code. Pointers declared using a mixture of
OLD and NEW style could have unpredictable results.

 Parameters & Local Variables

Automatic (local) variables and parameters to functions can
either be placed on the stack or in data-space. The default
action of the compiler is to place these variables in the
internal RAM (for small model) or external RAM (for Large
model). This in fact makes them static so by default functions
are non-reentrant.

They can be placed on the stack either by using the --stack-auto
compiler option or by using the reentrant keyword in the
function declaration, e.g.:

unsigned char foo(char i) reentrant 
{ 
... 
}

Since stack space on 8051 is limited, the reentrant keyword
or the --stack-auto option should be used sparingly. Note
that the reentrant keyword just means that the parameters
& local variables will be allocated to the stack, it does
not mean that the function is register bank independent.

Local variables can be assigned storage classes and absolute
addresses, e.g.: 

unsigned char foo() {
    xdata unsigned char i;
    bit bvar;
    data at 0x31 unsiged char j;
    ... 
}

In the above example the variable i will be allocated in
the external ram, bvar in bit addressable space and j in
internal ram. When compiled with --stack-auto or when a
function is declared as reentrant this can only be done
for static variables.

Parameters however are not allowed any storage class, (storage
classes for parameters will be ignored), their allocation
is governed by the memory model in use, and the reentrancy
options.

 Overlaying

For non-reentrant functions SDCC will try to reduce internal
ram space usage by overlaying parameters and local variables
of a function (if possible). Parameters and local variables
of a function will be allocated to an overlayable segment
if the function has no other function calls and the function
is non-reentrant and the memory model is small. If an explicit
storage class is specified for a local variable, it will
NOT be overlayed.

Note that the compiler (not the linkage editor) makes the
decision for overlaying the data items. Functions that are
called from an interrupt service routine should be preceded
by a #pragma NOOVERLAY if they are not reentrant.

Also note that the compiler does not do any processing of
inline assembler code, so the compiler might incorrectly
assign local variables and parameters of a function into
the overlay segment if the inline assembler code calls other
c-functions that might use the overlay. In that case the
#pragma NOOVERLAY should be used.

Parameters and Local variables of functions that contain
16 or 32 bit multiplication or division will NOT be overlayed
since these are implemented using external functions, e.g.:

#pragma SAVE 
#pragma NOOVERLAY 
void set_error(unsigned char errcd) 
{
    P3 = errcd;
} 
#pragma RESTORE 

void some_isr () interrupt 2 using 1 
{
    ...
    set_error(10);
    ... 
}

In the above example the parameter errcd for the function
set_error would be assigned to the overlayable segment if
the #pragma NOOVERLAY was not present, this could
cause unpredictable runtime behavior when called from an
ISR. The #pragma NOOVERLAY ensures that
the parameters and local variables for the function are
NOT overlayed.

 Interrupt Service Routines

SDCC allows interrupt service routines to be coded in C,
with some extended keywords.

void timer_isr (void) interrupt 2 using 1 
{ 
.. 
}

The number following the interrupt keyword is the interrupt
number this routine will service. The compiler will insert
a call to this routine in the interrupt vector table for
the interrupt number specified. The using keyword is used
to tell the compiler to use the specified register bank
(8051 specific) when generating code for this function.
Note that when some function is called from an interrupt
service routine it should be preceded by a #pragma NOOVERLAY
if it is not reentrant. A special note here, int (16 bit)
and long (32 bit) integer division, multiplication & modulus
operations are implemented using external support routines
developed in ANSI-C, if an interrupt service routine needs
to do any of these operations then the support routines
(as mentioned in a following section) will have to be recompiled
using the --stack-auto option and the source file will need
to be compiled using the --int-long-rent compiler option.

If you have multiple source files in your project, interrupt
service routines can be present in any of them, but a prototype
of the isr MUST be present or included in the file that
contains the function main.

Interrupt Numbers and the corresponding address & descriptions
for the Standard 8051 are listed below. SDCC will automatically
adjust the interrupt vector table to the maximum interrupt
number specified.


+--------------+--------------+----------------+
| Interrupt #  | Description  | Vector Address |
+--------------+--------------+----------------+
+--------------+--------------+----------------+
|      0       | External 0   |     0x0003     |
+--------------+--------------+----------------+
|      1       |   Timer 0    |     0x000B     |
+--------------+--------------+----------------+
|      2       | External 1   |     0x0013     |
+--------------+--------------+----------------+
|      3       |   Timer 1    |     0x001B     |
+--------------+--------------+----------------+
|      4       |   Serial     |     0x0023     |
+--------------+--------------+----------------+


If the interrupt service routine is defined without using
a register bank or with register bank 0 (using 0), the compiler
will save the registers used by itself on the stack upon
entry and restore them at exit, however if such an interrupt
service routine calls another function then the entire register
bank will be saved on the stack. This scheme may be advantageous
for small interrupt service routines which have low register
usage.

If the interrupt service routine is defined to be using a
specific register bank then only a, b & dptr are save and
restored, if such an interrupt service routine calls another
function (using another register bank) then the entire register
bank of the called function will be saved on the stack.
This scheme is recommended for larger interrupt service
routines.

Calling other functions from an interrupt service routine
is not recommended, avoid it if possible.

Also see the _naked modifier.

 Critical Functions

A special keyword may be associated with a function declaring
it as critical. SDCC will generate code to disable all interrupts
upon entry to a critical function and enable them back before
returning. Note that nesting critical functions may cause
unpredictable results.

int foo () critical 
{ 
... 
... 
}

The critical attribute maybe used with other attributes like
reentrant.

 Naked Functions

A special keyword may be associated with a function declaring
it as _naked. The _naked function modifier attribute prevents
the compiler from generating prologue and epilogue code
for that function. This means that the user is entirely
responsible for such things as saving any registers that
may need to be preserved, selecting the proper register
bank, generating the return instruction at the end, etc.
Practically, this means that the contents of the function
must be written in inline assembler. This is particularly
useful for interrupt functions, which can have a large (and
often unnecessary) prologue/epilogue. For example, compare
the code generated by these two functions:

data unsigned char counter;
void simpleInterrupt(void) interrupt 1
{
    counter++;
}

void nakedInterrupt(void) interrupt 2 _naked
{
    _asm
      inc     _counter
      reti    ;
MUST explicitly include ret in _naked function.
    _endasm;
}

For an 8051 target, the generated simpleInterrupt looks like:

_simpleIterrupt:
    push    acc
    push    b
    push    dpl
    push    dph
    push    psw
    mov     psw,#0x00
    inc     _counter
    pop     psw
    pop     dph
    pop     dpl
    pop     b
    pop     acc
    reti

whereas nakedInterrupt looks like:

_nakedInterrupt:
    inc    _counter
    reti   ; MUST explicitly
include ret(i) in _naked function.

While there is nothing preventing you from writing C code
inside a _naked function, there are many ways to shoot yourself
in the foot doing this, and is is recommended that you stick
to inline assembler.

 Functions using private banks

The using attribute (which tells the compiler to use a register
bank other than the default bank zero) should only be applied
to interrupt functions (see note 1 below). This will in
most circumstances make the generated ISR code more efficient
since it will not have to save registers on the stack.

The using attribute will have no effect on the generated
code for a non-interrupt function (but may occasionally
be useful anyway([footnote] possible exception: if a function is called ONLY
from 'interrupt' functions using a particular bank, it can
be declared with the same 'using' attribute as the calling
'interrupt' functions. For instance, if you have several
ISRs using bank one, and all of them call memcpy(), it might
make sense to create a specialized version of memcpy() 'using
1', since this would prevent the ISR from having to save
bank zero to the stack on entry and switch to bank zero
before calling the function) ).
(pending: I don't think this has been done yet)

An interrupt function using a non-zero bank will assume that
it can trash that register bank, and will not save it. Since
high-priority interrupts can interrupt low-priority ones
on the 8051 and friends, this means that if a high-priority
ISR using a particular bank occurs while processing a low-priority
ISR using the same bank, terrible and bad things can happen.
To prevent this, no single register bank should be used
by both a high priority and a low priority ISR. This is
probably most easily done by having all high priority ISRs
use one bank and all low priority ISRs use another. If you
have an ISR which can change priority at runtime, you're
on your own: I suggest using the default bank zero and taking
the small performance hit.

It is most efficient if your ISR calls no other functions.
If your ISR must call other functions, it is most efficient
if those functions use the same bank as the ISR (see note
1 below); the next best is if the called functions use bank
zero. It is very inefficient to call a function using a
different, non-zero bank from an ISR. 

 Absolute Addressing

Data items can be assigned an absolute address with the at
<address> keyword, in addition to a storage class, e.g.:

xdata at 0x8000 unsigned char PORTA_8255 ;

In the above example the PORTA_8255 will be allocated to
the location 0x8000 of the external ram. Note that this
feature is provided to give the programmer access to memory
mapped devices attached to the controller. The compiler
does not actually reserve any space for variables declared
in this way (they are implemented with an equate in the
assembler). Thus it is left to the programmer to make sure
there are no overlaps with other variables that are declared
without the absolute address. The assembler listing file
(.lst) and the linker output files (.rst) and (.map) are
a good places to look for such overlaps.

Absolute address can be specified for variables in all storage
classes, e.g.:

bit at 0x02 bvar;

The above example will allocate the variable at offset 0x02
in the bit-addressable space. There is no real advantage
to assigning absolute addresses to variables in this manner,
unless you want strict control over all the variables allocated.

 Startup Code

The compiler inserts a call to the C routine _sdcc__external__startup()
at the start of the CODE area. This routine is in the runtime
library. By default this routine returns 0, if this routine
returns a non-zero value, the static & global variable initialization
will be skipped and the function main will be invoked Other
wise static & global variables will be initialized before
the function main is invoked. You could add a _sdcc__external__startup()
routine to your program to override the default if you need
to setup hardware or perform some other critical operation
prior to static & global variable initialization.

 Inline Assembler Code

SDCC allows the use of in-line assembler with a few restriction
as regards labels. All labels defined within inline assembler
code has to be of the form nnnnn$ where nnnn is a number
less than 100 (which implies a limit of utmost 100 inline
assembler labels per function). It is strongly recommended
that each assembly instruction (including labels) be placed
in a separate line (as the example shows). When the --peep-asm
command line option is used, the inline assembler code will
be passed through the peephole optimizer. This might cause
some unexpected changes in the inline assembler code. Please
go throught the peephole optimizer rules defined in file
SDCCpeeph.def carefully before using this option.

_asm 
    mov     b,#10

00001$: 
    djnz    b,00001$

_endasm ;