+
+\series bold
+---data-loc
+\series default
+<Value> The start location of the internal ram data segment.
+ The value entered can be in Hexadecimal or Decimal format, eg.
+ ---data-loc 0x20 or ---data-loc 32.
+ (By default, the start location of the internal ram data segment is set
+ as low as possible in memory, taking into account the used register banks
+ and the bit segment at address 0x20.
+ For example if register banks 0 and 1 are used without bit variables, the
+ data segment will be set, if ---data-loc is not used, to location 0x10.)
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---idata-loc
+\series default
+<Value> The start location of the indirectly addressable internal ram, default
+ value is 0x80.
+ The value entered can be in Hexadecimal or Decimal format, eg.
+ ---idata-loc 0x88 or ---idata-loc 136.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---out-fmt-ihx
+\bar under
+
+\series default
+\bar default
+The linker output (final object code) is in Intel Hex format.
+ (This is the default option).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---out-fmt-s19
+\bar under
+
+\series default
+\bar default
+The linker output (final object code) is in Motorola S19 format.
+\layout Subsubsection
+
+MCS51 Options
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---model-large
+\series default
+ Generate code for Large model programs see section Memory Models for more
+ details.
+ If this option is used all source files in the project should be compiled
+ with this option.
+ In addition the standard library routines are compiled with small model,
+ they will need to be recompiled.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---model-small
+\series default
+\size large
+\emph on
+
+\size default
+\emph default
+Generate code for Small Model programs see section Memory Models for more
+ details.
+ This is the default model.
+\layout Subsubsection
+
+DS390 Options
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---model-flat24
+\series default
+\size large
+\emph on
+
+\size default
+\emph default
+Generate 24-bit flat mode code.
+ This is the one and only that the ds390 code generator supports right now
+ and is default when using
+\emph on
+-mds390
+\emph default
+.
+ See section Memory Models for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---stack-10bit
+\series default
+ Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
+ This is the one and only that the ds390 code generator supports right now
+ and is default when using
+\emph on
+-mds390
+\emph default
+.
+ In this mode, the stack is located in the lower 1K of the internal RAM,
+ which is mapped to 0x400000.
+ Note that the support is incomplete, since it still uses a single byte
+ as the stack pointer.
+ This means that only the lower 256 bytes of the potential 1K stack space
+ will actually be used.
+ However, this does allow you to reclaim the precious 256 bytes of low RAM
+ for use for the DATA and IDATA segments.
+ The compiler will not generate any code to put the processor into 10 bit
+ stack mode.
+ It is important to ensure that the processor is in this mode before calling
+ any re-entrant functions compiled with this option.
+ In principle, this should work with the
+\emph on
+---stack-auto
+\emph default
+ option, but that has not been tested.
+ It is incompatible with the
+\emph on
+---xstack
+\emph default
+ option.
+ It also only makes sense if the processor is in 24 bit contiguous addressing
+ mode (see the
+\emph on
+---model-flat24 option
+\emph default
+).
+\layout Subsubsection
+
+Optimization Options
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---nogcse
+\series default
+ Will not do global subexpression elimination, this option may be used when
+ the compiler creates undesirably large stack/data spaces to store compiler
+ temporaries.
+ A warning message will be generated when this happens and the compiler
+ will indicate the number of extra bytes it allocated.
+ It recommended that this option NOT be used, #pragma\SpecialChar ~
+NOGCSE can be used
+ to turn off global subexpression elimination for a given function only.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---noinvariant
+\series default
+ Will not do loop invariant optimizations, this may be turned off for reasons
+ explained for the previous option.
+ For more details of loop optimizations performed see section Loop Invariants.It
+ recommended that this option NOT be used, #pragma\SpecialChar ~
+NOINVARIANT can be used
+ to turn off invariant optimizations for a given function only.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---noinduction
+\series default
+ Will not do loop induction optimizations, see section strength reduction
+ for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
+NOINDUCT
+ION can be used to turn off induction optimizations for a given function
+ only.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---nojtbound
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+ Will not generate boundary condition check when switch statements are implement
+ed using jump-tables.
+ See section Switch Statements for more details.
+ It is recommended that this option is NOT used, #pragma\SpecialChar ~
+NOJTBOUND can be
+ used to turn off boundary checking for jump tables for a given function
+ only.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---noloopreverse
+\series default
+\size large
+
+\size default
+Will not do loop reversal optimization.
+\layout List
+\labelwidthstring 00.00.0000
+
+---
+\series bold
+nolabelopt
+\series default
+ Will not optimize labels (makes the dumpfiles more readable).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---no-xinit-opt
+\series default
+ Will not memcpy initialized data in far space from code space.
+ This saves a few bytes in code space if you don't have initialized data.
+\layout Subsubsection
+
+Other Options
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-c\SpecialChar ~
+---compile-only
+\series default
+ will compile and assemble the source, but will not call the linkage editor.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+--c1mode
+\series default
+ reads the preprocessed source from standard input and compiles it.
+ The file name for the assembler output must be specified using the -o option.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-E
+\series default
+ Run only the C preprocessor.
+ Preprocess all the C source files specified and output the results to standard
+ output.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-o\SpecialChar ~
+<path/file>
+\series default
+The output path resp.
+ file where everything will be placed.
+ If the parameter is a path, it must have a trailing slash (or backslash
+ for the Windows binaries) to be recognized as a path.
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---stack-auto
+\series default
+\size large
+\emph on
+
+\size default
+\emph default
+All functions in the source file will be compiled as
+\emph on
+reentrant
+\emph default
+, i.e.
+ the parameters and local variables will be allocated on the stack.
+ see section Parameters and Local Variables for more details.
+ If this option is used all source files in the project should be compiled
+ with this option.
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---xstack
+\series default
+ Uses a pseudo stack in the first 256 bytes in the external ram for allocating
+ variables and passing parameters.
+ See section on external stack for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---callee-saves function1[,function2][,function3]....
+
+\series default
+ The compiler by default uses a caller saves convention for register saving
+ across function calls, however this can cause unneccessary register pushing
+ & popping when calling small functions from larger functions.
+ This option can be used to switch the register saving convention for the
+ function names specified.
+ The compiler will not save registers when calling these functions, no extra
+ code will be generated at the entry & exit for these functions to save
+ & restore the registers used by these functions, this can SUBSTANTIALLY
+ reduce code & improve run time performance of the generated code.
+ In the future the compiler (with interprocedural analysis) will be able
+ to determine the appropriate scheme to use for each function call.
+ DO NOT use this option for built-in functions such as _muluint..., if this
+ option is used for a library function the appropriate library function
+ needs to be recompiled with the same option.
+ If the project consists of multiple source files then all the source file
+ should be compiled with the same ---callee-saves option string.
+ Also see #pragma\SpecialChar ~
+CALLEE-SAVES.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---debug
+\bar under
+
+\series default
+\bar default
+When this option is used the compiler will generate debug information, that
+ can be used with the SDCDB.
+ The debug information is collected in a file with .cdb extension.
+ For more information see documentation for SDCDB.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---peep-file
+\series default
+<filename> This option can be used to use additional rules to be used by
+ the peep hole optimizer.
+ See section Peep Hole optimizations for details on how to write these rules.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-S
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+Stop after the stage of compilation proper; do not assemble.
+ The output is an assembler code file for the input file specified.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-Wa_asmOption[,asmOption]
+\series default
+...
+ Pass the asmOption to the assembler.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-Wl_linkOption[,linkOption]
+\series default
+...
+ Pass the linkOption to the linker.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---int-long-reent
+\series default
+\size large
+
+\size default
+ Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
+ Note by default these libraries are compiled as non-reentrant.
+ See section Installation for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---cyclomatic
+\bar under
+
+\series default
+\bar default
+This option will cause the compiler to generate an information message for
+ each function in the source file.
+ The message contains some
+\emph on
+important
+\emph default
+ information about the function.
+ The number of edges and nodes the compiler detected in the control flow
+ graph of the function, and most importantly the
+\emph on
+cyclomatic complexity
+\emph default
+ see section on Cyclomatic Complexity for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---float-reent
+\bar under
+
+\series default
+\bar default
+ Floating point library is compiled as reentrant.See section Installation
+ for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---nooverlay
+\series default
+ The compiler will not overlay parameters and local variables of any function,
+ see section Parameters and local variables for more details.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---main-return
+\series default
+ This option can be used when the code generated is called by a monitor
+ program.
+ The compiler will generate a 'ret' upon return from the 'main' function.
+ The default option is to lock up i.e.
+ generate a 'ljmp '.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---no-peep
+\series default
+ Disable peep-hole optimization.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---peep-asm
+\series default
+ Pass the inline assembler code through the peep hole optimizer.
+ This can cause unexpected changes to inline assembler code, please go through
+ the peephole optimizer rules defined in the source file tree '<target>/peeph.def
+' before using this option.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---iram-size
+\series default
+<Value> Causes the linker to check if the internal ram usage is within limits
+ of the given value.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---xram-size
+\series default
+<Value> Causes the linker to check if the external ram usage is within limits
+ of the given value.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---code-size
+\series default
+<Value> Causes the linker to check if the code usage is within limits of
+ the given value.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---nostdincl
+\series default
+ This will prevent the compiler from passing on the default include path
+ to the preprocessor.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---nostdlib
+\series default
+ This will prevent the compiler from passing on the default library path
+ to the linker.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---verbose
+\series default
+ Shows the various actions the compiler is performing.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+-V
+\series default
+ Shows the actual commands the compiler is executing.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---no-c-code-in-asm
+\series default
+ Hides your ugly and inefficient c-code from the asm file, so you can always
+ blame the compiler :).
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---i-code-in-asm
+\series default
+ Include i-codes in the asm file.
+ Sounds like noise but is most helpfull for debugging the compiler itself.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---less-pedantic
+\series default
+ Disable some of the more pedantic warnings (jwk burps: please be more specific
+ here, please!)
+\layout Subsubsection
+
+Intermediate Dump Options
+\layout Standard
+
+The following options are provided for the purpose of retargetting and debugging
+ the compiler.
+ These provided a means to dump the intermediate code (iCode) generated
+ by the compiler in human readable form at various stages of the compilation
+ process.
+
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumpraw
+\series default
+ This option will cause the compiler to dump the intermediate code into
+ a file of named
+\emph on
+<source filename>.dumpraw
+\emph default
+ just after the intermediate code has been generated for a function, i.e.
+ before any optimizations are done.
+ The basic blocks at this stage ordered in the depth first number, so they
+ may not be in sequence of execution.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumpgcse
+\series default
+ Will create a dump of iCode's, after global subexpression elimination,
+ into a file named
+\emph on
+<source filename>.dumpgcse.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumpdeadcode
+\series default
+ Will create a dump of iCode's, after deadcode elimination, into a file
+ named
+\emph on
+<source filename>.dumpdeadcode.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumploop
+\series default
+\size large
+
+\size default
+Will create a dump of iCode's, after loop optimizations, into a file named
+
+\emph on
+<source filename>.dumploop.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumprange
+\series default
+\size large
+
+\size default
+Will create a dump of iCode's, after live range analysis, into a file named
+
+\emph on
+<source filename>.dumprange.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumlrange
+\series default
+ Will dump the life ranges for all symbols.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumpregassign
+\bar under
+
+\series default
+\bar default
+Will create a dump of iCode's, after register assignment, into a file named
+
+\emph on
+<source filename>.dumprassgn.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumplrange
+\series default
+ Will create a dump of the live ranges of iTemp's
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+---dumpall
+\size large
+\bar under
+
+\series default
+\size default
+\bar default
+Will cause all the above mentioned dumps to be created.
+\layout Subsection
+
+Environment variables
+\layout Standard
+
+SDCC recognizes the following environment variables:
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCC_LEAVE_SIGNALS
+\series default
+ SDCC installs a signal handler to be able to delete temporary files after
+ an user break (^C) or an exception.
+ If this environment variable is set, SDCC won't install the signal handler
+ in order to be able to debug SDCC.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+TMP,\SpecialChar ~
+TEMP,\SpecialChar ~
+TMPDIR
+\series default
+ Path, where temporary files will be created.
+ The order of the variables is the search order.
+ In a standard *nix environment these variables are not set, and there's
+ no need to set them.
+ On Windows it's recommended to set one of them.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCC_HOME
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.3 Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCC_INCLUDE
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.3 Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\series bold
+SDCC_LIB
+\series default
+ Path, see
+\begin_inset Quotes sld
+\end_inset
+
+2.3 Install and search paths
+\begin_inset Quotes srd
+\end_inset
+
+.
+\layout Standard
+
+There are some more environment variables recognized by SDCC, but these
+ are solely used for debugging purposes.
+ They can change or disappear very quickly, and will never be documentated.
+\layout Subsection
+
+MCS51/DS390 Storage Class Language Extensions
+\layout Standard
+
+In addition to the ANSI storage classes SDCC allows the following MCS51
+ specific storage classes.
+\layout Subsubsection
+
+xdata
+\layout Standard
+
+Variables declared with this storage class will be placed in the extern
+ RAM.
+ This is the
+\series bold
+default
+\series default
+ storage class for Large Memory model, e.g.:
+\newline
+
+\newline
+
+\family typewriter
+xdata unsigned char xduc;
+\layout Subsubsection
+
+data
+\layout Standard
+
+This is the
+\series bold
+default
+\series default
+ storage class for Small Memory model.
+ Variables declared with this storage class will be allocated in the internal
+ RAM, e.g.:
+\newline
+
+\newline
+
+\family typewriter
+data int iramdata;
+\layout Subsubsection
+
+idata
+\layout Standard
+
+Variables declared with this storage class will be allocated into the indirectly
+ addressable portion of the internal ram of a 8051, e.g.:
+\newline
+
+\newline
+
+\family typewriter
+idata int idi;
+\layout Subsubsection
+
+bit
+\layout Standard
+
+This is a data-type and a storage class specifier.
+ When a variable is declared as a bit, it is allocated into the bit addressable
+ memory of 8051, e.g.:
+\newline
+
+\newline
+
+\family typewriter
+bit iFlag;
+\layout Subsubsection
+
+sfr / sbit
+\layout Standard
+
+Like the bit keyword,
+\emph on
+sfr / sbit
+\emph default
+signifies both a data-type and storage class, they are used to describe
+ the special function registers and special bit variables of a 8051, eg:
+\newline
+
+\newline
+
+\family typewriter
+sfr at 0x80 P0; /* special function register P0 at location 0x80 */
+\newline
+sbit at 0xd7 CY; /* CY (Carry Flag) */
+\layout Subsection
+
+Pointers
+\layout Standard
+
+SDCC allows (via language extensions) pointers to explicitly point to any
+ of the memory spaces of the 8051.
+ In addition to the explicit pointers, the compiler uses (by default) generic
+ pointers which can be used to point to any of the memory spaces.
+\newline
+
+\newline
+Pointer declaration examples:
+\newline
+
+\size small
+
+\newline
+
+\family typewriter
+\size default
+/* pointer physically in xternal ram pointing to object in internal ram
+ */
+\newline
+data unsigned char * xdata p;
+\newline
+
+\newline
+/* pointer physically in code rom pointing to data in xdata space */
+\newline
+xdata unsigned char * code p;
+\newline
+
+\newline
+/* pointer physically in code space pointing to data in code space */
+\newline
+code unsigned char * code p;
+\newline
+
+\newline
+/* the folowing is a generic pointer physically located in xdata space */
+\newline
+char * xdata p;
+\family default
+\size small
+
+\newline
+
+\newline
+
+\size default
+Well you get the idea.
+
+\newline
+
+\newline
+All unqualified pointers are treated as 3-byte (4-byte for the ds390)
+\emph on
+generic
+\emph default
+ pointers.
+
+\size small
+
+\newline
+
+\newline
+
+\size default
+The highest order byte of the
+\emph on
+generic
+\emph default
+ pointers contains the data space information.
+ Assembler support routines are called whenever data is stored or retrieved
+ using
+\emph on
+generic
+\emph default
+ pointers.
+ These are useful for developing reusable library routines.
+ Explicitly specifying the pointer type will generate the most efficient
+ code.
+\layout Subsection
+
+Parameters & Local Variables
+\layout Standard
+
+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
+\emph on
+static
+\emph default
+ so by default functions are non-reentrant.
+\newline
+
+\newline
+They can be placed on the stack either by using the
+\emph on
+ ---stack-auto
+\emph default
+ option or by using the
+\emph on
+reentrant
+\emph default
+ keyword in the function declaration, e.g.:
+\newline
+
+\size small
+
+\newline
+
+\family typewriter
+\size default
+unsigned char foo(char i) reentrant
+\newline
+{
+\newline
+...
+
+\newline
+}
+\newline
+
+\family default
+
+\newline
+Since stack space on 8051 is limited, the
+\emph on
+reentrant
+\emph default
+keyword or the
+\emph on
+ ---stack-auto
+\emph default
+ option should be used sparingly.
+ Note that the reentrant keyword just means that the parameters & local
+ variables will be allocated to the stack, it
+\emph on
+does not
+\emph default
+ mean that the function is register bank independent.
+\newline
+
+\newline
+Local variables can be assigned storage classes and absolute addresses,
+ e.g.:
+\newline
+
+\newline
+
+\family typewriter
+unsigned char foo() {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+xdata unsigned char i;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+bit bvar;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+data at 0x31 unsiged char j;
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\newline
+
+\newline
+
+\family default
+In the above example the variable
+\emph on
+i
+\emph default
+ will be allocated in the external ram,
+\emph on
+bvar
+\emph default
+ in bit addressable space and
+\emph on
+ j
+\emph default
+ in internal ram.
+ When compiled with
+\emph on
+---stack-auto
+\emph default
+ or when a function is declared as
+\emph on
+reentrant
+\emph default
+ this should only be done for static variables.
+\layout Standard
+
+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.
+\layout Subsection
+
+Overlaying
+\layout Standard
+
+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 overlayabl
+e segment if the function has
+\emph on
+no other function calls and the function is non-reentrant and the memory
+ model is small.
+
+\emph default
+ If an explicit storage class is specified for a local variable, it will
+ NOT be overlayed.
+\layout Standard
+
+Note that the compiler (not the linkage editor) makes the decision for overlayin
+g the data items.
+ Functions that are called from an interrupt service routine should be preceded
+ by a #pragma\SpecialChar ~
+NOOVERLAY if they are not reentrant.
+\layout Standard
+
+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\SpecialChar ~
+NOOVERLAY should be used.
+\layout Standard
+
+Parameters and Local variables of functions that contain 16 or 32 bit multiplica
+tion or division will NOT be overlayed since these are implemented using
+ external functions, e.g.:
+\newline
+
+\newline
+
+\family typewriter
+#pragma SAVE
+\newline
+#pragma NOOVERLAY
+\newline
+void set_error(unsigned char errcd)
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+P3 = errcd;
+\newline
+}
+\newline
+#pragma RESTORE
+\newline
+
+\newline
+void some_isr () interrupt 2 using 1
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+set_error(10);
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+...
+
+\newline
+}
+\newline
+
+\newline
+
+\family default
+In the above example the parameter
+\emph on
+errcd
+\emph default
+ for the function
+\emph on
+set_error
+\emph default
+ would be assigned to the overlayable segment if the #pragma\SpecialChar ~
+NOOVERLAY was
+ not present, this could cause unpredictable runtime behavior when called
+ from an ISR.
+ The #pragma\SpecialChar ~
+NOOVERLAY ensures that the parameters and local variables for
+ the function are NOT overlayed.
+\layout Subsection
+
+Interrupt Service Routines
+\layout Standard
+
+SDCC allows interrupt service routines to be coded in C, with some extended
+ keywords.
+\newline
+
+\newline
+
+\family typewriter
+void timer_isr (void) interrupt 2 using 1
+\newline
+{
+\newline
+..
+
+\newline
+}
+\newline
+
+\newline
+
+\family default
+The number following the
+\emph on
+interrupt
+\emph default
+ 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
+\emph on
+using
+\emph default
+ 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\SpecialChar ~
+NOOVERLAY if it is not reentrant.
+ A special note here, int (16 bit) and long (32 bit) integer division, multiplic
+ation & 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
+\emph on
+ ---stack-auto
+\emph default
+ option and the source file will need to be compiled using the
+\emph on
+---int-long-ren
+\emph default
+t compiler option.
+\layout Standard
+
+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
+\emph on
+main
+\emph default
+.
+\layout Standard
+
+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.
+\newline
+
+\layout Standard
+
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" width="0in">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Interrupt #
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Vector Address
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+External 0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0003
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Timer 0
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x000B
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+External 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0013
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+3
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Timer 1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x001B
+\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+4
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Serial
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+0x0023
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\newline
+
+\newline
+If the interrupt service routine is defined without
+\emph on
+using
+\emph default
+ 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.
+\layout Standard
+
+If the interrupt service routine is defined to be using a specific register
+ bank then only
+\emph on
+a, b & dptr
+\emph default
+ 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.
+\layout Standard
+
+Calling other functions from an interrupt service routine is not recommended,
+ avoid it if possible.
+\newline
+
+\newline
+Also see the _naked modifier.
+\layout Subsection
+
+Critical Functions
+\layout Standard
+
+
+\shape italic
+<TODO: this isn't implemented at all!>
+\shape default
+
+\newline
+
+\newline
+A special keyword may be associated with a function declaring it as
+\emph on
+critical
+\emph default
+.
+ 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.
+\newline
+
+\size small
+
+\newline
+
+\family typewriter
+\size default
+int foo () critical
+\newline
+{
+\newline
+...
+
+\newline
+...
+
+\newline
+}
+\newline
+
+\family default
+
+\newline
+The critical attribute maybe used with other attributes like
+\emph on
+reentrant.
+\layout Subsection
+
+Naked Functions
+\layout Standard
+
+A special keyword may be associated with a function declaring it as
+\emph on
+_naked.
+
+\emph default
+The
+\emph on
+_naked
+\emph default
+ 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
+\emph on
+return
+\emph default
+ 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:
+\newline
+
+\newline
+
+\family typewriter
+data unsigned char counter;
+\newline
+void simpleInterrupt(void) interrupt 1
+\newline
+{
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+counter++;
+\newline
+}
+\newline
+
+\newline
+void nakedInterrupt(void) interrupt 2 _naked