\begin_inset Tabular
<lyxtabular version="3" rows="5" columns="4">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" width="0(null)">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\end_inset
-\newline
-
\layout Chapter
-Debugging with SDCDB
-\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
+Notes on supported Processors
+\layout Section
+
+MCS51 variants
+\begin_inset LatexCommand \label{sub:MCS51-variants}
\end_inset
-\begin_inset LatexCommand \index{sdcdb (debugger)}
+\begin_inset LatexCommand \index{MCS51 variants}
\end_inset
-
+
\layout Standard
-SDCC is distributed with a source level debugger
-\begin_inset LatexCommand \index{Debugger}
+MCS51 processors are available from many vendors and come in many different
+ flavours.
+ While they might differ considerably in respect to Special Function Registers
+ the core MCS51 is usually not modified or is kept compatible.
+
+\layout Subsection
-\end_inset
+pdata access by SFR
+\layout Standard
-.
- The debugger uses a command line interface, the command repertoire of the
- debugger has been kept as close to gdb
-\begin_inset LatexCommand \index{gdb}
+With the upcome of devices with internal xdata and flash memory devices
+ using port P2
+\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
\end_inset
- (the GNU debugger) as possible.
- The configuration and build process is part of the standard compiler installati
-on, which also builds and installs the debugger in the target directory
- specified during configuration.
- The debugger allows you debug BOTH at the C source and at the ASM source
- level.
- Sdcdb is available on Unix platforms only.
-\layout Section
+ as dedicated I/O port is becoming more popular.
+ Switching the high byte for pdata
+\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
-Compiling for Debugging
-\layout Standard
+\end_inset
-The \SpecialChar \-
-\SpecialChar \-
-debug option must be specified for all files for which debug information
- is to be generated.
- The complier generates a .adb file for each of these files.
- The linker creates the .cdb
-\begin_inset LatexCommand \index{<file>.cdb}
+ access which was formerly done by port P2 is then achieved by a Special
+ Function Register
+\begin_inset LatexCommand \index{sfr}
\end_inset
- file from the .adb
-\begin_inset LatexCommand \index{<file>.adb}
+.
+ In well-established MCS51 tradition the address of this
+\emph on
+sfr
+\emph default
+ is where the chip designers decided to put it.
+ Needless to say that they didn't agree on a common name either.
+ As pdata addressing is used in the startup code for the initialization
+ of xdata variables a separate startup code should be used as described
+ in section
+\begin_inset LatexCommand \ref{sub:Startup-Code}
\end_inset
- files and the address information.
- This .cdb is used by the debugger.
-\layout Section
+.
+\layout Subsection
-How the Debugger Works
+Other Features available by SFR
\layout Standard
-When the -
-\begin_inset ERT
-status Collapsed
-
-\layout Standard
+Some MCS51 variants offer features like Double DPTR
+\begin_inset LatexCommand \index{DPTR}
-\backslash
-/
\end_inset
--debug option is specified the compiler generates extra symbol information
- some of which are put into the assembler source and some are put into the
- .adb file.
- Then the linker creates the .cdb file from the individual .adb files with
- the address information for the symbols.
- The debugger reads the symbolic information generated by the compiler &
- the address information generated by the linker.
- It uses the SIMULATOR (Daniel's S51) to execute the program, the program
- execution is controlled by the debugger.
- When a command is issued for the debugger, it translates it into appropriate
- commands for the simulator.
+, multiple DPTR, decrementing DPTR, 16x16 Multiply.
+ These are currently not used for the MCS51 port.
+ If you absolutely need them you can fall back to inline assembly or submit
+ a patch to SDCC.
\layout Section
-Starting the Debugger
+The Z80 and gbz80 port
\layout Standard
-The debugger can be started using the following command line.
- (Assume the file you are debugging has the file name foo).
-\newline
-
-\newline
-
-\family sans
-\series bold
-sdcdb foo
-\newline
-
-\family default
-\series default
-
-\newline
-The debugger will look for the following files.
-\layout Itemize
-
-foo.c - the source file.
-\layout Itemize
+SDCC can target both the Zilog
+\begin_inset LatexCommand \index{Z80}
-foo.cdb - the debugger symbol information file.
-\layout Itemize
+\end_inset
-foo.ihx - the Intel hex format
-\begin_inset LatexCommand \index{Intel hex format}
+ and the Nintendo Gameboy's Z80-like gbz80
+\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
\end_inset
- object file.
-\layout Section
+.
+ The Z80 port is passed through the same
+\emph on
+regressions tests
+\begin_inset LatexCommand \index{Regression test}
-Command Line Options.
-\layout Itemize
+\end_inset
--
-\begin_inset ERT
-status Collapsed
+\emph default
+ as the MCS51 and DS390 ports, so floating point support, support for long
+ variables and bitfield support is fine.
+ See mailing lists and forums about interrupt routines.
\layout Standard
-\backslash
-/
-\end_inset
+As always, the code is the authoritative reference - see z80/ralloc.c and
+ z80/gen.c.
+ The stack
+\begin_inset LatexCommand \index{stack}
--directory=<source file directory> this option can used to specify the directory
- search list.
- The debugger will look into the directory list specified for source, cdb
- & ihx files.
- The items in the directory list must be separated by ':', e.g.
- if the source files can be in the directories /home/src1 and /home/src2,
- the -
-\begin_inset ERT
-status Collapsed
+\end_inset
-\layout Standard
+ frame is similar to that generated by the IAR Z80 compiler.
+ IX is used as the base pointer, HL is used as a temporary register, and
+ BC and DE are available for holding variables.
+ IY is currently unused.
+ Return values
+\begin_inset LatexCommand \index{return value}
-\backslash
-/
\end_inset
--directory option should be -
-\begin_inset ERT
-status Collapsed
+ are stored in HL.
+ One bad side effect of using IX as the base pointer is that a functions
+ stack frame is limited to 127 bytes - this will be fixed in a later version.
+\layout Section
+The HC08 port
\layout Standard
-\backslash
-/
+The port to the Motorola HC08
+\begin_inset LatexCommand \index{HC08}
+
\end_inset
--directory=/home/src1:/home/src2.
- Note there can be no spaces in the option.
-
-\layout Itemize
+ family has been added in October 2003, thank you Erik!
+\layout Section
--cd <directory> - change to the <directory>.
-\layout Itemize
+The PIC14 port
+\layout Standard
--fullname - used by GUI front ends.
-\layout Itemize
+The 14bit PIC
+\begin_inset LatexCommand \index{PIC14}
--cpu <cpu-type> - this argument is passed to the simulator please see the
- simulator docs for details.
-\layout Itemize
+\end_inset
--X <Clock frequency > this options is passed to the simulator please see
- the simulator docs for details.
-\layout Itemize
+ port still requires a major effort from the development community.
+ However it can work for very simple code.
+\layout Subsection
--s <serial port file> passed to simulator see the simulator docs for details.
-\layout Itemize
+C code and 14bit PIC code page
+\begin_inset LatexCommand \index{code page (pic14)}
--S <serial in,out> passed to simulator see the simulator docs for details.
-\layout Itemize
+\end_inset
--k <port number> passed to simulator see the simulator docs for details.
-\layout Section
+ and RAM banks
+\begin_inset LatexCommand \index{RAM bank (pic14)}
-Debugger Commands.
-\layout Standard
+\end_inset
-As mentioned earlier the command interface for the debugger has been deliberatel
-y kept as close the GNU debugger gdb, as possible.
- This will help the integration with existing graphical user interfaces
- (like ddd, xxgdb or xemacs) existing for the GNU debugger.
- If you use a graphical user interface for the debugger you can skip the
- next sections.
-\layout Subsubsection*
-break [line | file:line | function | file:function]
\layout Standard
-Set breakpoint at specified line or function:
+The linker organizes allocation for the code page and RAM banks.
+ It does not have intimate knowledge of the code flow.
+ It will put all the code section of a single asm file into a single code
+ page.
+ In order to make use of multiple code pages, separate asm files must be
+ used.
+ The compiler treats all functions of a single C file as being in the same
+ code page unless it is non static.
+ The compiler treats all local variables of a single C file as being in
+ the same RAM bank unless it is an extern.
\newline
\newline
+To get the best follow these guide lines:
+\layout Enumerate
-\family sans
-\series bold
-sdcdb>break 100
-\newline
-sdcdb>break foo.c:100
-\newline
-sdcdb>break funcfoo
-\newline
-sdcdb>break foo.c:funcfoo
-\layout Subsubsection*
-
-clear [line | file:line | function | file:function ]
-\layout Standard
-
-Clear breakpoint at specified line or function:
-\newline
-
-\newline
-
-\family sans
-\series bold
-sdcdb>clear 100
-\newline
-sdcdb>clear foo.c:100
-\newline
-sdcdb>clear funcfoo
-\newline
-sdcdb>clear foo.c:funcfoo
-\layout Subsubsection*
-
-continue
-\layout Standard
-
-Continue program being debugged, after breakpoint.
-\layout Subsubsection*
-
-finish
-\layout Standard
-
-Execute till the end of the current function.
-\layout Subsubsection*
-
-delete [n]
-\layout Standard
-
-Delete breakpoint number 'n'.
- If used without any option clear ALL user defined break points.
-\layout Subsubsection*
-
-info [break | stack | frame | registers ]
-\layout Itemize
-
-info break - list all breakpoints
-\layout Itemize
-
-info stack - show the function call stack.
-\layout Itemize
-
-info frame - show information about the current execution frame.
-\layout Itemize
-
-info registers - show content of all registers.
-\layout Subsubsection*
-
-step
-\layout Standard
-
-Step program until it reaches a different source line.
- Note: pressing <return> repeats the last command.
-\layout Subsubsection*
-
-next
-\layout Standard
-
-Step program, proceeding through subroutine calls.
-\layout Subsubsection*
-
-run
-\layout Standard
-
-Start debugged program.
-\layout Subsubsection*
-
-ptype variable
-\layout Standard
-
-Print type information of the variable.
-\layout Subsubsection*
-
-print variable
-\layout Standard
-
-print value of variable.
-\layout Subsubsection*
-
-file filename
-\layout Standard
-
-load the given file name.
- Note this is an alternate method of loading file for debugging.
-\layout Subsubsection*
-
-frame
-\layout Standard
-
-print information about current frame.
-\layout Subsubsection*
+make local functions static, as non static functions require code page selection
+ overhead.
+\layout Enumerate
-set srcmode
-\layout Standard
+Make local variables static as extern variables require RAM bank selection
+ overhead.
+\layout Enumerate
-Toggle between C source & assembly source.
-\layout Subsubsection*
+For devices that have multiple code pages it is more efficient to use the
+ same number of files as pages, i.e.
+ for the 16F877 use 4 separate files and i.e.
+ for the 16F874 use 2 separate files.
+ This way the linker can put the code for each file into different code
+ pages and the compiler can allocate reusable variables more efficiently
+ and there's less page selection overhead.
+ And as for any 8 bit micro (especially for PIC 14 as they have a very simple
+ instruction set) use 'unsigned char' whereever possible instead of 'int'.
+\layout Subsection
-! simulator command
+Creating a device include file
\layout Standard
-Send the string following '!' to the simulator, the simulator response is
- displayed.
- Note the debugger does not interpret the command being sent to the simulator,
- so if a command like 'go' is sent the debugger can loose its execution
- context and may display incorrect values.
-\layout Subsubsection*
+For generating a device include file use the support perl script inc2h.pl
+ kept in directory support/script.
+\layout Subsection
-quit
+Interrupt code
\layout Standard
-"Watch me now.
- Iam going Down.
- My name is Bobby Brown"
-\layout Section
-
-Interfacing with XEmacs
-\begin_inset LatexCommand \index{XEmacs}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{Emacs}
+For the interrupt function, use the keyword 'interrupt'
+\begin_inset LatexCommand \index{interrupt}
\end_inset
-.
-\layout Standard
-
-Two files (in emacs lisp) are provided for the interfacing with XEmacs,
- sdcdb.el and sdcdbsrc.el.
- These two files can be found in the $(prefix)/bin directory after the installat
-ion is complete.
- These files need to be loaded into XEmacs for the interface to work.
- This can be done at XEmacs startup time by inserting the following into
- your '.xemacs' file (which can be found in your HOME directory):
-\newline
+ with level number of 0 (PIC14 only has 1 interrupt so this number is only
+ there to avoid a syntax error - it ought to be fixed).
+ E.g.:
+\layout Verse
-\newline
\family typewriter
-(load-file sdcdbsrc.el)
-\family default
-
+void Intr(void) interrupt 0
\newline
-
+{
\newline
-.xemacs is a lisp file so the () around the command is REQUIRED.
- The files can also be loaded dynamically while XEmacs is running, set the
- environment variable 'EMACSLOADPATH' to the installation bin directory
- (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
- To start the interface enter the following command:
+\SpecialChar ~
+\SpecialChar ~
+T0IF = 0; /* Clear timer interrupt */
\newline
+}
+\layout Standard
+Linking and assembling
\newline
+For assembling you can use either GPUTILS'
+\begin_inset LatexCommand \index{gputils (pic tools)}
-\family sans
-\series bold
-ESC-x sdcdbsrc
-\family default
-\series default
-
-\newline
+\end_inset
-\newline
-You will prompted to enter the file name to be debugged.
-
+ gpasm.exe or MPLAB's mpasmwin.exe.
+ For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
+ If you use MPLAB and an interrupt function then the linker script file
+ vectors section will need to be enlarged to link with mplink.
\newline
\newline
-The command line options that are passed to the simulator directly are bound
- to default values in the file sdcdbsrc.el.
- The variables are listed below, these values maybe changed as required.
-\layout Itemize
-
-sdcdbsrc-cpu-type '51
-\layout Itemize
-
-sdcdbsrc-frequency '11059200
-\layout Itemize
-
-sdcdbsrc-serial nil
-\layout Standard
-
-The following is a list of key mapping for the debugger interface.
-\layout Standard
+Here is a
+\family typewriter
+Makefile
+\family default
+ using GPUTILS:
+\layout Verse
-\SpecialChar ~
\family typewriter
-
-\newline
-;; Current Listing ::
+.c.o:
\newline
-;;key\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+sdcc -S -V -mpic14 -p16F877 $<
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-binding\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+gpasm -c $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
+\layout Standard
+
+Here is a
+\family typewriter
+Makefile
+\family default
+ using MPLAB:
+\layout Verse
+
+
+\family typewriter
+.c.o:
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-Comment
+sdcc -S -V -mpic14 -p16F877 $<
\newline
-;;---\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mpasmwin /q /o $*.asm
+\newline
+
+\newline
+$(PRJ).hex: $(OBJS)
+\newline
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
+\layout Section
+
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port
+\layout Standard
+
+The PIC16
+\begin_inset LatexCommand \index{PIC16}
+
+\end_inset
+
+ port (refered from now on as pic16) is the portion of SDCC that is responsible
+ to produce code for the Microchip
+\begin_inset LatexCommand \index{Microchip}
+
+\end_inset
+
+(TM) microcontrollers with 16 bit core.
+ Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
+\layout Subsection
+
+Global Options
+\layout Standard
+
+The pic16 port supports the standard command line arguments as supposed,
+ with the exception of certain cases that will be mentioned in the following
+ list:
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-auto Auto variables that are function parameters, will be saved on
+ stack by default.
+
+\emph on
+There is no need to specify this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-float-reent All floating point functions are reentrant by default.
+
+\emph on
+There is no need to specifiy this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-callee-saves See -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-all-callee-saves
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-all-callee-saves All function arguments are passed on stack by default.
+
+\emph on
+There is no need to specify this in the command line.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-fommit-frame-pointer Frame pointer will be omitted when the function uses
+ no local variables.
+\layout Subsection
+
+PIC16 Port Specific Options
+\layout Standard
+
+The port specific options appear after the global options in the sdcc --help
+ output.
+\layout Subsubsection
+
+General Options
+\layout Standard
+
+General options enable certain port features and optimizations.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pgen-bank Instructs the port to insert BANKSEL directives before instructions
+ that use the Bank Select Register (BSR).
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pomit-config-words Instructs the port to omit the generation of the configurati
+on words.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pomit-ivt Instructs the port to omit the generation of the interrupt vectors
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pleave-reset-vector Used in conjuction with the previous command, instructs
+ the port NOT to omit the reset vector.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-penable-stack Enables stack usage.
+ All new development is done with stack enabled.
+ This command line soon will be deprecated and stack will be enabled by
+ default.
+ For the time being it must be entered if one wants to have stack.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-stack-model=[model] Used in conjuction with the command above.
+ Defines the stack model to be used, valid stack models are :
+\begin_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\emph on
+small
+\emph default
+ Selects small stack model.
+ 8 bit stack and frame pointers.
+ Supports 256 bytes stack size.
+\layout List
+\labelwidthstring 00.00.0000
+
+
+\emph on
+large
+\emph default
+ Selects large stack model.
+ 16 bit stack and frame pointers.
+ Supports 65536 bytes stack size.
+\end_deeper
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-preplace-udata-with=[kword] Replaces the default udata keyword for allocating
+ unitialized data variables with [kword].
+ Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
+\layout Subsubsection
+
+Debugging Options
+\layout Standard
+
+Debugging options enable extra debugging information in the output files.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-xtra Similar to --debug, but dumps more information.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug-ralloc Force register allocator to dump <source>.d file with debugging
+ information.
+ <source> is the name of the file compiled.
+\layout List
+\labelwidthstring 00.00.0000
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-pcode-verbose Enable pcode debugging information in translation.
+\layout Subsection
+
+Preprocessor Macros
+\layout Standard
+
+PIC16 port defines the following preprocessor macros while translating a
+ source.
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="2" columns="2">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Macro
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Description
+\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
+
+pic18fxxxx
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+MCU Identification.
+
+\emph on
+xxxx
+\emph default
+ is the microcontrol identification number, i.e.
+ 452, 6620, etc
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Directories
+\layout Standard
+
+PIC16 port uses the following directories for searching header files and
+ libraries.
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="4">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Directory
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="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
+
+Target
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Command prefix
+\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
+
+PREFIX/sdcc/include/pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC16 specific headers
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Compiler
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-I
+\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
+
+PREFIX/sdcc/lib/pic16
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+PIC16 specific libraries
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Linker
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+-L
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Header Files
+\layout Standard
+
+There is one main header file that can be included to the source files using
+ the pic16 port.
+ That file is the
+\series bold
+pic18fregs.h
+\series default
+.
+ This header file contains the definitions for the processor special registers,
+ so it is necessery if the soruce accesses them.
+ It can be included by adding the following line in the beginning of the
+ file:
+\layout LyX-Code
+
+#include <pic18fregs.h>
+\layout Standard
+
+The specific microcontroller is selected within the pic18fregs.h automatically,
+ so the same source can be used with a variety of devices.
+\layout Subsection
+
+Libraries
+\layout Standard
+
+The libraries that pic16 port depends on are the microcontroller device
+ libraries which contain the symbol definitions for the microcontroller
+ special function registers.
+ These libraries have the format pic18fxxxx.lib, where
+\emph on
+xxxx
+\emph default
+ is the microcontroller identification number.
+ The specific library is selected automatically by the compiler at link
+ stage according to the selected device.
+\layout Standard
+
+Libraries are created with gplib which is part of the gputils package
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net}
+
+\end_inset
+
+.
+\layout Subsection
+
+Memory Models
+\layout Standard
+
+The following memory models are supported by PIC16 port:
+\layout Itemize
+
+small model
+\layout Itemize
+
+large model
+\layout Subsection
+
+Stack
+\layout Standard
+
+The stack implementation for the PIC16 port uses two indirect registers,
+ FSR1 and FSR2.
+\layout List
+\labelwidthstring 00.00.0000
+
+FSR1 is assigned as stack pointer
+\layout List
+\labelwidthstring 00.00.0000
+
+FSR2 is assigned as frame pointer
+\layout Standard
+
+The following stack models are supported by PIC16 port
+\layout Itemize
+
+small model
+\layout Itemize
+
+large model
+\layout Standard
+
+
+\noun on
+Small
+\noun default
+ model means that only the FSRxL byte is used to access stack and frame,
+ while
+\emph on
+\noun on
+large
+\emph default
+\noun default
+ uses both FSRxL and FSRxH registers.
+ The following table shows the stack/frame pointers sizes according to stack
+ model and the maximum space they can address:
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Stack & Frame pointer sizes according to stack model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+small
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+large
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Stack pointer FSR1
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\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
+
+Frame pointer FSR2
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+8-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Subsection
+
+Pointers
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="3" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" width="0">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+Pointer sizes according to memory model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+small model
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+large model
+\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
+
+code pointers
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+24-bits
+\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
+
+data pointers
+\end_inset
+</cell>
+<cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+16-bits
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+
+24-bits
+\end_inset
+</cell>
+</row>
+</lyxtabular>
+
+\end_inset
+
+
+\layout Chapter
+
+Debugging with SDCDB
+\begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{sdcdb (debugger)}
+
+\end_inset
+
+
+\layout Standard
+
+SDCC is distributed with a source level debugger
+\begin_inset LatexCommand \index{Debugger}
+
+\end_inset
+
+.
+ The debugger uses a command line interface, the command repertoire of the
+ debugger has been kept as close to gdb
+\begin_inset LatexCommand \index{gdb}
+
+\end_inset
+
+ (the GNU debugger) as possible.
+ The configuration and build process is part of the standard compiler installati
+on, which also builds and installs the debugger in the target directory
+ specified during configuration.
+ The debugger allows you debug BOTH at the C source and at the ASM source
+ level.
+ Sdcdb is available on Unix platforms only.
+\layout Section
+
+Compiling for Debugging
+\layout Standard
+
+The \SpecialChar \-
+\SpecialChar \-
+debug option must be specified for all files for which debug information
+ is to be generated.
+ The complier generates a .adb file for each of these files.
+ The linker creates the .cdb
+\begin_inset LatexCommand \index{<file>.cdb}
+
+\end_inset
+
+ file from the .adb
+\begin_inset LatexCommand \index{<file>.adb}
+
+\end_inset
+
+ files and the address information.
+ This .cdb is used by the debugger.
+\layout Section
+
+How the Debugger Works
+\layout Standard
+
+When the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-debug option is specified the compiler generates extra symbol information
+ some of which are put into the assembler source and some are put into the
+ .adb file.
+ Then the linker creates the .cdb file from the individual .adb files with
+ the address information for the symbols.
+ The debugger reads the symbolic information generated by the compiler &
+ the address information generated by the linker.
+ It uses the SIMULATOR (Daniel's S51) to execute the program, the program
+ execution is controlled by the debugger.
+ When a command is issued for the debugger, it translates it into appropriate
+ commands for the simulator.
+\layout Section
+
+Starting the Debugger
+\layout Standard
+
+The debugger can be started using the following command line.
+ (Assume the file you are debugging has the file name foo).
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb foo
+\newline
+
+\family default
+\series default
+
+\newline
+The debugger will look for the following files.
+\layout Itemize
+
+foo.c - the source file.
+\layout Itemize
+
+foo.cdb - the debugger symbol information file.
+\layout Itemize
+
+foo.ihx - the Intel hex format
+\begin_inset LatexCommand \index{Intel hex format}
+
+\end_inset
+
+ object file.
+\layout Section
+
+Command Line Options.
+\layout Itemize
+
+-
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-directory=<source file directory> this option can used to specify the directory
+ search list.
+ The debugger will look into the directory list specified for source, cdb
+ & ihx files.
+ The items in the directory list must be separated by ':', e.g.
+ if the source files can be in the directories /home/src1 and /home/src2,
+ the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-directory option should be -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+
+\backslash
+/
+\end_inset
+
+-directory=/home/src1:/home/src2.
+ Note there can be no spaces in the option.
+
+\layout Itemize
+
+-cd <directory> - change to the <directory>.
+\layout Itemize
+
+-fullname - used by GUI front ends.
+\layout Itemize
+
+-cpu <cpu-type> - this argument is passed to the simulator please see the
+ simulator docs for details.
+\layout Itemize
+
+-X <Clock frequency > this options is passed to the simulator please see
+ the simulator docs for details.
+\layout Itemize
+
+-s <serial port file> passed to simulator see the simulator docs for details.
+\layout Itemize
+
+-S <serial in,out> passed to simulator see the simulator docs for details.
+\layout Itemize
+
+-k <port number> passed to simulator see the simulator docs for details.
+\layout Section
+
+Debugger Commands.
+\layout Standard
+
+As mentioned earlier the command interface for the debugger has been deliberatel
+y kept as close the GNU debugger gdb, as possible.
+ This will help the integration with existing graphical user interfaces
+ (like ddd, xxgdb or xemacs) existing for the GNU debugger.
+ If you use a graphical user interface for the debugger you can skip the
+ next sections.
+\layout Subsubsection*
+
+break [line | file:line | function | file:function]
+\layout Standard
+
+Set breakpoint at specified line or function:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb>break 100
+\newline
+sdcdb>break foo.c:100
+\newline
+sdcdb>break funcfoo
+\newline
+sdcdb>break foo.c:funcfoo
+\layout Subsubsection*
+
+clear [line | file:line | function | file:function ]
+\layout Standard
+
+Clear breakpoint at specified line or function:
+\newline
+
+\newline
+
+\family sans
+\series bold
+sdcdb>clear 100
+\newline
+sdcdb>clear foo.c:100
+\newline
+sdcdb>clear funcfoo
+\newline
+sdcdb>clear foo.c:funcfoo
+\layout Subsubsection*
+
+continue
+\layout Standard
+
+Continue program being debugged, after breakpoint.
+\layout Subsubsection*
+
+finish
+\layout Standard
+
+Execute till the end of the current function.
+\layout Subsubsection*
+
+delete [n]
+\layout Standard
+
+Delete breakpoint number 'n'.
+ If used without any option clear ALL user defined break points.
+\layout Subsubsection*
+
+info [break | stack | frame | registers ]
+\layout Itemize
+
+info break - list all breakpoints
+\layout Itemize
+
+info stack - show the function call stack.
+\layout Itemize
+
+info frame - show information about the current execution frame.
+\layout Itemize
+
+info registers - show content of all registers.
+\layout Subsubsection*
+
+step
+\layout Standard
+
+Step program until it reaches a different source line.
+ Note: pressing <return> repeats the last command.
+\layout Subsubsection*
+
+next
+\layout Standard
+
+Step program, proceeding through subroutine calls.
+\layout Subsubsection*
+
+run
+\layout Standard
+
+Start debugged program.
+\layout Subsubsection*
+
+ptype variable
+\layout Standard
+
+Print type information of the variable.
+\layout Subsubsection*
+
+print variable
+\layout Standard
+
+print value of variable.
+\layout Subsubsection*
+
+file filename
+\layout Standard
+
+load the given file name.
+ Note this is an alternate method of loading file for debugging.
+\layout Subsubsection*
+
+frame
+\layout Standard
+
+print information about current frame.
+\layout Subsubsection*
+
+set srcmode
+\layout Standard
+
+Toggle between C source & assembly source.
+\layout Subsubsection*
+
+! simulator command
+\layout Standard
+
+Send the string following '!' to the simulator, the simulator response is
+ displayed.
+ Note the debugger does not interpret the command being sent to the simulator,
+ so if a command like 'go' is sent the debugger can loose its execution
+ context and may display incorrect values.
+\layout Subsubsection*
+
+quit
+\layout Standard
+
+"Watch me now.
+ Iam going Down.
+ My name is Bobby Brown"
+\layout Section
+
+Interfacing with XEmacs
+\begin_inset LatexCommand \index{XEmacs}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{Emacs}
+
+\end_inset
+
+.
+\layout Standard
+
+Two files (in emacs lisp) are provided for the interfacing with XEmacs,
+ sdcdb.el and sdcdbsrc.el.
+ These two files can be found in the $(prefix)/bin directory after the installat
+ion is complete.
+ These files need to be loaded into XEmacs for the interface to work.
+ This can be done at XEmacs startup time by inserting the following into
+ your '.xemacs' file (which can be found in your HOME directory):
+\newline
+
+\newline
+
+\family typewriter
+(load-file sdcdbsrc.el)
+\family default
+
+\newline
+
+\newline
+.xemacs is a lisp file so the () around the command is REQUIRED.
+ The files can also be loaded dynamically while XEmacs is running, set the
+ environment variable 'EMACSLOADPATH' to the installation bin directory
+ (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
+ To start the interface enter the following command:
+\newline
+
+\newline
+
+\family sans
+\series bold
+ESC-x sdcdbsrc
+\family default
+\series default
+
+\newline
+
+\newline
+You will prompted to enter the file name to be debugged.
+
+\newline
+
+\newline
+The command line options that are passed to the simulator directly are bound
+ to default values in the file sdcdbsrc.el.
+ The variables are listed below, these values maybe changed as required.
+\layout Itemize
+
+sdcdbsrc-cpu-type '51
+\layout Itemize
+
+sdcdbsrc-frequency '11059200
+\layout Itemize
+
+sdcdbsrc-serial nil
+\layout Standard
+
+The following is a list of key mapping for the debugger interface.
+\layout Standard
+
+\SpecialChar ~
+
+\family typewriter
+
+\newline
+;; Current Listing ::
+\newline
+;;key\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+binding\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+Comment
+\newline
+;;---\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\bar no
\noun off
\color none
-sdcc/bin
-\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
-
-packihx
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-ihx packer
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/bin
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\newline
-
-\layout Section
-
-Documentation
-\begin_inset LatexCommand \index{Documentation}
-
-\end_inset
-
- included in the distribution
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="10" columns="2">
-<features>
-<column alignment="left" valignment="top" leftline="true" width="0">
-<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Subject / Title
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Where to get / filename
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-SDCC Compiler User Guide
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-You're reading it right now
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Changelog of SDCC
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/Changelog
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-ASXXXX Assemblers and ASLINK Relocating Linker
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/as/doc/asxhtm.html
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-SDCC regression test
-\begin_inset LatexCommand \index{Regression test}
-
-\end_inset
-
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/doc/test_suite_spec.pdf
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Various notes
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/doc/*
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Notes on debugging with sdcdb
-\begin_inset LatexCommand \index{sdcdb (debugger)}
-
-\end_inset
-
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/debugger/README
-\end_inset
-</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Software simulator for microcontrollers
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-sdcc/sim/ucsim/doc
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-/index.html
+sdcc/bin
\end_inset
</cell>
</row>
-<row topline="true">
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Temporary notes on the pic16
-\begin_inset LatexCommand \index{PIC16}
-
-\end_inset
-
- port
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-sdcc/src/pic16/NOTES
+packihx
\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
-SDCC internal documentation (debugging file format)
+ihx packer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-sdcc/doc/
+
\family roman
\series medium
\shape up
\bar no
\noun off
\color none
-cdbfileformat.pd
-\family default
-\series default
-\shape default
-\size default
-\emph default
-\bar default
-\noun default
-\color default
-f
+sdcc/bin
\end_inset
</cell>
</row>
\layout Section
-Related open source tools
-\begin_inset LatexCommand \index{Related tools}
+Documentation
+\begin_inset LatexCommand \index{Documentation}
\end_inset
-
+ included in the distribution
\layout Standard
\align center
\begin_inset Tabular
-<lyxtabular version="3" rows="11" columns="3">
+<lyxtabular version="3" rows="10" columns="2">
<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<column alignment="left" valignment="top" leftline="true" width="0">
+<column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Purpose
+Subject / Title
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Where to get
+Where to get / filename
\end_inset
</cell>
</row>
\layout Standard
-gpsim
-\begin_inset LatexCommand \index{gpsim (pic simulator)}
-
+SDCC Compiler User Guide
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
+You're reading it right now
\end_inset
</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-PIC simulator
+Changelog of SDCC
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
-
-\end_inset
-
-
+sdcc/Changelog
\end_inset
</cell>
</row>
\layout Standard
-gputils
-\begin_inset LatexCommand \index{gputils (pic tools)}
-
-\end_inset
-
-
+ASXXXX Assemblers and ASLINK Relocating Linker
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-GNU PIC utilities
+sdcc/as/doc/asxhtm.html
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-
-\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
+SDCC regression test
+\begin_inset LatexCommand \index{Regression test}
\end_inset
\end_inset
</cell>
-</row>
-<row topline="true">
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-flP5
+sdcc/doc/test_suite_spec.pdf
\end_inset
</cell>
+</row>
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-PIC programmer
+Various notes
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
-
-\end_inset
-
-
+sdcc/doc/*
\end_inset
</cell>
</row>
\layout Standard
-indent
-\begin_inset LatexCommand \index{indent (source formatting tool)}
-
-\end_inset
-
+Notes on debugging with sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-\layout Standard
-Formats C source - Master of the white spaces
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
-
-\end_inset
-
-
+sdcc/debugger/README
\end_inset
</cell>
</row>
\layout Standard
-srecord
-\begin_inset LatexCommand \index{srecord (tool)}
-
-\end_inset
-
-
-\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-
-Object file conversion, checksumming, ...
+Software simulator for microcontrollers
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
-
-\end_inset
-
-
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+sdcc/sim/ucsim/doc
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+/index.html
\end_inset
</cell>
</row>
\layout Standard
-objdump
-\begin_inset LatexCommand \index{objdump (tool)}
-
-\end_inset
-
+Temporary notes on the pic16
+\begin_inset LatexCommand \index{PIC16}
\end_inset
-</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
-\begin_inset Text
-
-\layout Standard
-Object file conversion, ...
+ port
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Part of binutils (should be there anyway)
+sdcc/src/pic16/NOTES
\end_inset
</cell>
</row>
-<row topline="true">
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-doxygen
-\begin_inset LatexCommand \index{doxygen (source documentation tool)}
-
-\end_inset
-
-
+SDCC internal documentation (debugging file format)
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\begin_inset Text
\layout Standard
-Source code documentation system
+sdcc/doc/
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+cdbfileformat.pd
+\family default
+\series default
+\shape default
+\size default
+\emph default
+\bar default
+\noun default
+\color default
+f
\end_inset
</cell>
-<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
-\begin_inset Text
+</row>
+</lyxtabular>
-\layout Standard
+\end_inset
-\begin_inset LatexCommand \url{http://www.doxygen.org}
+\newline
-\end_inset
+\layout Section
+Related open source tools
+\begin_inset LatexCommand \index{Related tools}
\end_inset
-</cell>
-</row>
-<row topline="true">
+
+
+\layout Standard
+\align center
+
+\begin_inset Tabular
+<lyxtabular version="3" rows="11" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="block" valignment="top" leftline="true" width="30line%">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-kdevelop
+Name
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
+Purpose
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-
-\begin_inset LatexCommand \url{http://www.kdevelop.org}
-
-\end_inset
-
-
+Where to get
\end_inset
</cell>
</row>
\layout Standard
-splint
-\begin_inset LatexCommand \index{splint (syntax checking tool)}
+gpsim
+\begin_inset LatexCommand \index{gpsim (pic simulator)}
\end_inset
\layout Standard
-Statically checks c sources
+PIC simulator
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.splint.org}
+\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
\end_inset
\end_inset
</cell>
</row>
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-ddd
-\begin_inset LatexCommand \index{ddd (debugger)}
+gputils
+\begin_inset LatexCommand \index{gputils (pic tools)}
\end_inset
\layout Standard
-Debugger, serves nicely as GUI to sdcdb
-\begin_inset LatexCommand \index{sdcdb (debugger)}
-
-\end_inset
-
- (Unix only)
+GNU PIC utilities
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
+\begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
\end_inset
\end_inset
</cell>
</row>
-</lyxtabular>
-
-\end_inset
-
-
-\newline
-
-\layout Section
-
-Related documentation / recommended reading
-\layout Standard
-\align center
-
-\begin_inset Tabular
-<lyxtabular version="3" rows="6" columns="3">
-<features>
-<column alignment="center" valignment="top" leftline="true" width="0pt">
-<column alignment="block" valignment="top" leftline="true" width="30line%">
-<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-Name
+flP5
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Subject / Title
+PIC programmer
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-Where to get
+
+\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
\layout Standard
+indent
+\begin_inset LatexCommand \index{indent (source formatting tool)}
+
+\end_inset
+
-\family roman
-\series medium
-\shape up
-\size normal
-\emph off
-\bar no
-\noun off
-\color none
-c-refcard.pdf
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-C Reference Card
-\begin_inset LatexCommand \index{C Reference card}
-
-\end_inset
-
-, 2 pages
+Formats C source - Master of the white spaces
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
+\begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
\end_inset
\layout Standard
-c-faq
+srecord
+\begin_inset LatexCommand \index{srecord (tool)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-C-FAQ-list
+Object file conversion, checksumming, ...
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
+\begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
\end_inset
\layout Standard
+objdump
+\begin_inset LatexCommand \index{objdump (tool)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Latest datasheet of the target CPU
+Object file conversion, ...
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-vendor
+Part of binutils (should be there anyway)
\end_inset
</cell>
</row>
\layout Standard
+doxygen
+\begin_inset LatexCommand \index{doxygen (source documentation tool)}
+
+\end_inset
+
+
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Revision history of datasheet
+Source code documentation system
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-vendor
+
+\begin_inset LatexCommand \url{http://www.doxygen.org}
+
+\end_inset
+
+
\end_inset
</cell>
</row>
-<row topline="true" bottomline="true">
+<row topline="true">
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\begin_inset Text
\layout Standard
-S.
- S.
- Muchnick
+kdevelop
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
\layout Standard
-Advanced Compiler Design and Implementation
+IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
\end_inset
</cell>
<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
\layout Standard
-bookstore (very dedicated, probably read other books first)
-\end_inset
-</cell>
-</row>
-</lyxtabular>
-
-\end_inset
-
-
-\newline
-
-\layout Section
-
-Some Questions
-\layout Standard
-
-Some questions answered, some pointers given - it might be time to in turn
- ask
-\emph on
-you
-\emph default
- some questions:
-\layout Itemize
-
-can you solve your project with the selected microcontroller? Would you
- find out early or rather late that your target is too small/slow/whatever?
- Can you switch to a slightly better device if it doesn't fit?
-\layout Itemize
-
-should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
- and/or another programming language be more adequate? Would an operating
- system on the target device help?
-\layout Itemize
-if you solved the problem, will the marketing department be happy?
-\layout Itemize
+\begin_inset LatexCommand \url{http://www.kdevelop.org}
-if the marketing department is happy, will customers be happy?
-\layout Itemize
+\end_inset
-if you're the project manager, marketing department and maybe even the customer
- in one person, have you tried to see the project from the outside?
-\layout Itemize
-is the project done if you think it is done? Or is just that other interface/pro
-tocol/feature/configuration/option missing? How about website, manual(s),
- internationali(z|s)ation, packaging, labels, 2nd source for components,
- electromagnetic compatability/interference, documentation for production,
- production test software, update mechanism, patent issues?
-\layout Itemize
+\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-is your project adequately positioned in that magic triangle: fame, fortune,
- fun?
\layout Standard
-Maybe not all answers to these questions are known and some answers may
- even be
-\emph on
-no
-\emph default
-, nevertheless knowing these questions may help you to avoid burnout
-\begin_inset Foot
-collapsed false
-
-\layout Standard
+splint
+\begin_inset LatexCommand \index{splint (syntax checking tool)}
-burnout is bad for electronic devices, programmers and motorcycle tyres
\end_inset
-.
- Chances are you didn't want to hear some of them...
-\layout Chapter
-
-Support
-\begin_inset LatexCommand \index{Support}
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-
-\layout Standard
-
-SDCC has grown to be a large project.
- The compiler alone (without the preprocessor, assembler and linker) is
- well over 100,000 lines of code (blank stripped).
- The open source nature of this project is a key to its continued growth
- and support.
- You gain the benefit and support of many active software developers and
- end users.
- Is SDCC perfect? No, that's why we need your help.
- The developers take pride in fixing reported bugs.
- You can help by reporting the bugs and helping other SDCC users.
- There are lots of ways to contribute, and we encourage you to take part
- in making SDCC a great software package.
-
\layout Standard
-The SDCC project is hosted on the SDCC sourceforge site at
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
-
+Statically checks c sources
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-.
- You'll find the complete set of mailing lists
-\begin_inset LatexCommand \index{Mailing list}
+\layout Standard
-\end_inset
-, forums, bug reporting system, patch submission
-\begin_inset LatexCommand \index{Patch submission}
+\begin_inset LatexCommand \url{http://www.splint.org}
\end_inset
- system, download
-\begin_inset LatexCommand \index{download}
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
- area and cvs code repository
-\begin_inset LatexCommand \index{cvs code repository}
+\layout Standard
+
+ddd
+\begin_inset LatexCommand \index{ddd (debugger)}
\end_inset
- there.
-\layout Section
-
-Reporting Bugs
-\begin_inset LatexCommand \index{Bug reporting}
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{Reporting bugs}
+Debugger, serves nicely as GUI to sdcdb
+\begin_inset LatexCommand \index{sdcdb (debugger)}
\end_inset
+ (Unix only)
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
\layout Standard
-The recommended way of reporting bugs is using the infrastructure of the
- sourceforge site.
- You can follow the status of bug reports there and have an overview about
- the known bugs.
-\layout Standard
-
-Bug reports are automatically forwarded to the developer mailing list and
- will be fixed ASAP.
- When reporting a bug, it is very useful to include a small test program
- (the smaller the better) which reproduces the problem.
- If you can isolate the problem by looking at the generated assembly code,
- this can be very helpful.
- Compiling your program with the -
-\begin_inset ERT
-status Collapsed
-\layout Standard
+\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
-\backslash
-/
\end_inset
--dumpall
-\begin_inset LatexCommand \index{-\/-dumpall}
\end_inset
+</cell>
+</row>
+</lyxtabular>
- option can sometimes be useful in locating optimization problems.
- When reporting a bug please maker sure you:
-\layout Enumerate
-
-Attach the code you are compiling with SDCC.
-
-\layout Enumerate
+\end_inset
-Specify the exact command you use to run SDCC, or attach your Makefile.
-
-\layout Enumerate
-Specify the SDCC version (type "
-\family sans
-\series bold
-sdcc -v
-\family default
-\series default
-"), your platform, and operating system.
-
-\layout Enumerate
+\newline
-Provide an exact copy of any error message or incorrect output.
-
-\layout Enumerate
+\layout Section
-Put something meaningful in the subject of your message.
+Related documentation / recommended reading
\layout Standard
+\align center
-Please attempt to include these 5 important parts, as applicable, in all
- requests for support or when reporting any problems or bugs with SDCC.
- Though this will make your message lengthy, it will greatly improve your
- chance that SDCC users and developers will be able to help you.
- Some SDCC developers are frustrated by bug reports without code provided
- that they can use to reproduce and ultimately fix the problem, so please
- be sure to provide sample code if you are reporting a bug!
-\layout Standard
+\begin_inset Tabular
+<lyxtabular version="3" rows="6" columns="3">
+<features>
+<column alignment="center" valignment="top" leftline="true" width="0pt">
+<column alignment="block" valignment="top" leftline="true" width="30line%">
+<column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Please have a short check that you are using a recent version of SDCC and
- the bug is not yet known.
- This is the link for reporting bugs:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
+\layout Standard
+Name
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
-\layout Section
-
-Requesting Features
-\begin_inset LatexCommand \label{sub:Requesting-Features}
+\layout Standard
+Subject / Title
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{Feature request}
-
+Where to get
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset LatexCommand \index{Requesting features}
+\family roman
+\series medium
+\shape up
+\size normal
+\emph off
+\bar no
+\noun off
+\color none
+c-refcard.pdf
\end_inset
-
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-Like bug reports feature requests are forwarded to the developer mailing
- list.
- This is the link for requesting features:
-\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+C Reference Card
+\begin_inset LatexCommand \index{C Reference card}
\end_inset
-.
-\layout Section
+, 2 pages
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
-Submitting patches
\layout Standard
-Like bug reports contributed patches are forwarded to the developer mailing
- list.
- This is the link for submitting patches
-\begin_inset LatexCommand \index{Patch submission}
+
+\begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
\end_inset
-:
-\begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-.
\layout Standard
-You need to specify some parameters to the
-\family typewriter
-diff
-\family default
- command for the patches to be useful.
- If you modified more than one file a patch created f.e.
- with
-\family sans
-\series bold
-
-\begin_inset Quotes sld
+c-faq
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-diff -Naur unmodified_directory modified_directory >my_changes.patch
-\begin_inset Quotes srd
+\layout Standard
+
+C-FAQ-list
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\family default
-\series default
- will be fine, otherwise
-\family sans
-\series bold
-\begin_inset Quotes sld
+\begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
+
\end_inset
-diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
-\begin_inset Quotes srd
+
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\series default
-
-\family default
-will do.
-\layout Section
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-Getting Help
\layout Standard
-These links should take you directly to the
-\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
+Latest datasheet of the target CPU
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
+
+\layout Standard
+vendor
\end_inset
+</cell>
+</row>
+<row topline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
+\layout Standard
-\begin_inset Foot
-collapsed false
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
\layout Standard
-Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
- automated messages (mid 2003)
+Revision history of datasheet
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- and the
-\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
+\layout Standard
+vendor
\end_inset
+</cell>
+</row>
+<row topline="true" bottomline="true">
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-, lists and forums are archived and searchable so if you are lucky someone
- already had a similar problem.
-\layout Section
+\layout Standard
+
+S.
+ S.
+ Muchnick
+\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
+\begin_inset Text
-ChangeLog
\layout Standard
-You can follow the status of the cvs version
-\begin_inset LatexCommand \index{version}
-
+Advanced Compiler Design and Implementation
\end_inset
+</cell>
+<cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
+\begin_inset Text
- of SDCC by watching the Changelog
-\begin_inset LatexCommand \index{Changelog}
+\layout Standard
+bookstore (very dedicated, probably read other books first)
\end_inset
-
- in the cvs-repository
-\newline
-
-\size footnotesize
-
-\begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
+</cell>
+</row>
+</lyxtabular>
\end_inset
-.
-\layout Section
-
-Release policy
-\begin_inset LatexCommand \index{Release policy}
-\end_inset
+\newline
+\layout Section
+Some Questions
\layout Standard
-Historically there often were long delays between official releases and
- the sourceforge download area tends to get not updated at all.
- Excuses in the past might have referred to problems with live range analysis,
- but as this was fixed a while ago, the current problem is that another
- excuse has to be found.
- Kidding aside, we have to get better there! On the other hand there are
- daily snapshots available at
-\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
-
-\end_inset
+Some questions answered, some pointers given - it might be time to in turn
+ ask
+\emph on
+you
+\emph default
+ some questions:
+\layout Itemize
-, and you can always build the very last version (hopefully with many bugs
- fixed, and features added) from the source code available at
-\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
+can you solve your project with the selected microcontroller? Would you
+ find out early or rather late that your target is too small/slow/whatever?
+ Can you switch to a slightly better device if it doesn't fit?
+\layout Itemize
-\end_inset
+should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
+ and/or another programming language be more adequate? Would an operating
+ system on the target device help?
+\layout Itemize
-.
-\layout Section
+if you solved the problem, will the marketing department be happy?
+\layout Itemize
-Examples
-\begin_inset LatexCommand \index{Examples}
+if the marketing department is happy, will customers be happy?
+\layout Itemize
-\end_inset
+if you're the project manager, marketing department and maybe even the customer
+ in one person, have you tried to see the project from the outside?
+\layout Itemize
+is the project done if you think it is done? Or is just that other interface/pro
+tocol/feature/configuration/option missing? How about website, manual(s),
+ internationali(z|s)ation, packaging, labels, 2nd source for components,
+ electromagnetic compatability/interference, documentation for production,
+ production test software, update mechanism, patent issues?
+\layout Itemize
+is your project adequately positioned in that magic triangle: fame, fortune,
+ fun?
\layout Standard
-You'll find some small examples in the directory
+Maybe not all answers to these questions are known and some answers may
+ even be
\emph on
-sdcc/device/examples/.
-
+no
\emph default
-More examples and libraries are available at
-\emph on
- The SDCC Open Knowledge Resource
-\begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
-
-\end_inset
+, nevertheless knowing these questions may help you to avoid burnout
+\begin_inset Foot
+collapsed false
-
-\emph default
-web site or at
-\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
+\layout Standard
+burnout is bad for electronic devices, programmers and motorcycle tyres
\end_inset
.
-\layout Comment
-
-I did insert a reference to Paul's web site here although it seems rather
- dedicated to a specific 8032 board (I think it's okay because it f.e.
- shows LCD/Harddisc interface and has a free 8051 monitor.
- Independent 8032 board vendors face hard competition of heavily subsidized
- development boards anyway).
-\layout Comment
-
-Maybe we should include some links to real world applications.
- Preferably pointer to pointers (one for each architecture) so this stays
- manageable here?
-\layout Section
+ Chances are you didn't want to hear some of them...
+\layout Chapter
-Quality control
-\begin_inset LatexCommand \index{Quality control}
+Support
+\begin_inset LatexCommand \index{Support}
\end_inset
\layout Standard
-The compiler is passed through nightly compile and build checks.
- The so called
-\shape italic
-regression tests
-\shape default
+SDCC has grown to be a large project.
+ The compiler alone (without the preprocessor, assembler and linker) is
+ well over 100,000 lines of code (blank stripped).
+ The open source nature of this project is a key to its continued growth
+ and support.
+ You gain the benefit and support of many active software developers and
+ end users.
+ Is SDCC perfect? No, that's why we need your help.
+ The developers take pride in fixing reported bugs.
+ You can help by reporting the bugs and helping other SDCC users.
+ There are lots of ways to contribute, and we encourage you to take part
+ in making SDCC a great software package.
+
+\layout Standard
-\begin_inset LatexCommand \index{Regression test}
+The SDCC project is hosted on the SDCC sourceforge site at
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
\end_inset
- check that SDCC itself compiles flawlessly on several platforms and checks
- the quality of the code generated by SDCC by running the code through simulator
-s.
- There is a separate document
-\shape italic
-test_suite.pdf
-\begin_inset LatexCommand \index{Test suite}
+.
+ You'll find the complete set of mailing lists
+\begin_inset LatexCommand \index{Mailing list}
\end_inset
+, forums, bug reporting system, patch submission
+\begin_inset LatexCommand \index{Patch submission}
-\shape default
- about this.
-\layout Standard
-
-You'll find the test code in the directory
-\shape italic
-sdcc/support/regression
-\shape default
-.
- You can run these tests manually by running
-\family sans
-make
-\family default
- in this directory (or f.e.
-
-\family sans
-\series bold
-
-\begin_inset Quotes sld
\end_inset
-make test-mcs51
-\begin_inset Quotes srd
-\end_inset
+ system, download
+\begin_inset LatexCommand \index{download}
+\end_inset
-\family default
-\series default
- if you don't want to run the complete tests).
- The test code might also be interesting if you want to look for examples
-\begin_inset LatexCommand \index{Examples}
+ area and cvs code repository
+\begin_inset LatexCommand \index{cvs code repository}
\end_inset
- checking corner cases of SDCC or if you plan to submit patches
-\begin_inset LatexCommand \index{Patch submission}
+ there.
+\layout Section
-\end_inset
+Reporting Bugs
+\begin_inset LatexCommand \index{Bug reporting}
-.
-\layout Standard
+\end_inset
-The pic port uses a different set of regression tests, you'll find them
- in the directory
-\shape italic
-sdcc/src/regression
-\shape default
-.
-\layout Chapter
-\pagebreak_top
-SDCC Technical Data
-\layout Section
-Optimizations
-\begin_inset LatexCommand \index{Optimizations}
+\begin_inset LatexCommand \index{Reporting bugs}
\end_inset
\layout Standard
-SDCC performs a host of standard optimizations in addition to some MCU specific
- optimizations.
-
-\layout Subsection
+The recommended way of reporting bugs is using the infrastructure of the
+ sourceforge site.
+ You can follow the status of bug reports there and have an overview about
+ the known bugs.
+\layout Standard
-Sub-expression Elimination
-\begin_inset LatexCommand \index{Subexpression elimination}
+Bug reports are automatically forwarded to the developer mailing list and
+ will be fixed ASAP.
+ When reporting a bug, it is very useful to include a small test program
+ (the smaller the better) which reproduces the problem.
+ If you can isolate the problem by looking at the generated assembly code,
+ this can be very helpful.
+ Compiling your program with the -
+\begin_inset ERT
+status Collapsed
+
+\layout Standard
+\backslash
+/
\end_inset
+-dumpall
+\begin_inset LatexCommand \index{-\/-dumpall}
-\layout Standard
+\end_inset
-The compiler does local and
-\emph on
-g
-\emph default
-lobal
-\emph on
-c
-\emph default
-ommon
-\emph on
-s
-\emph default
-ubexpression
-\emph on
-e
-\emph default
-limination, e.g.:
-\layout Verse
+ option can sometimes be useful in locating optimization problems.
+ When reporting a bug please maker sure you:
+\layout Enumerate
+Attach the code you are compiling with SDCC.
+
+\layout Enumerate
-\family typewriter
-i = x + y + 1;
-\newline
-j = x + y;
-\layout Standard
+Specify the exact command you use to run SDCC, or attach your Makefile.
+
+\layout Enumerate
-will be translated to
-\layout Verse
+Specify the SDCC version (type "
+\family sans
+\series bold
+sdcc -v
+\family default
+\series default
+"), your platform, and operating system.
+
+\layout Enumerate
+Provide an exact copy of any error message or incorrect output.
+
+\layout Enumerate
-\family typewriter
-iTemp = x + y;
-\newline
-i = iTemp + 1;
-\newline
-j = iTemp;
+Put something meaningful in the subject of your message.
\layout Standard
-Some subexpressions are not as obvious as the above example, e.g.:
-\layout Verse
+Please attempt to include these 5 important parts, as applicable, in all
+ requests for support or when reporting any problems or bugs with SDCC.
+ Though this will make your message lengthy, it will greatly improve your
+ chance that SDCC users and developers will be able to help you.
+ Some SDCC developers are frustrated by bug reports without code provided
+ that they can use to reproduce and ultimately fix the problem, so please
+ be sure to provide sample code if you are reporting a bug!
+\layout Standard
+Please have a short check that you are using a recent version of SDCC and
+ the bug is not yet known.
+ This is the link for reporting bugs:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
-\family typewriter
-a->b[i].c = 10;
-\newline
-a->b[i].d = 11;
-\layout Standard
+\end_inset
-In this case the address arithmetic a->b[i] will be computed only once;
- the equivalent code in C would be.
-\layout Verse
+.
+\layout Section
+Requesting Features
+\begin_inset LatexCommand \label{sub:Requesting-Features}
-\family typewriter
-iTemp = a->b[i];
-\newline
-iTemp.c = 10;
-\newline
-iTemp.d = 11;
-\layout Standard
+\end_inset
-The compiler will try to keep these temporary variables in registers.
-\layout Subsection
-Dead-Code Elimination
-\begin_inset LatexCommand \index{Dead-code elimination}
+\begin_inset LatexCommand \index{Feature request}
\end_inset
-\layout Verse
+\begin_inset LatexCommand \index{Requesting features}
+\end_inset
-\family typewriter
-int global;
-\newline
-\newline
-void f () {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 1; \SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-/* dead store */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 1;\SpecialChar ~
-/* dead store */
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 3;\SpecialChar ~
-/* unreachable */
-\newline
-}
\layout Standard
-will be changed to
-\layout Verse
+Like bug reports feature requests are forwarded to the developer mailing
+ list.
+ This is the link for requesting features:
+\begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
+\end_inset
-\family typewriter
-int global;
-\newline
+.
+\layout Section
-\newline
-void f () {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-global = 2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return;
-\newline
-}
-\layout Subsection
+Submitting patches
+\layout Standard
-Copy-Propagation
-\begin_inset LatexCommand \index{Copy propagation}
+Like bug reports contributed patches are forwarded to the developer mailing
+ list.
+ This is the link for submitting patches
+\begin_inset LatexCommand \index{Patch submission}
\end_inset
+:
+\begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
-\layout Verse
-
+\end_inset
-\family typewriter
-int f() {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i, j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 10;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-j = i;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return j;
-\newline
-}
+.
\layout Standard
-will be changed to
-\layout Verse
-
-
+You need to specify some parameters to the
\family typewriter
-int f() {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-int i, j;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-i = 10;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-j = 10;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-return 10;
-\newline
-}
-\layout Standard
-
-Note: the dead stores created by this copy propagation will be eliminated
- by dead-code elimination.
-\layout Subsection
+diff
+\family default
+ command for the patches to be useful.
+ If you modified more than one file a patch created f.e.
+ with
+\family sans
+\series bold
-Loop Optimizations
-\begin_inset LatexCommand \index{Loop optimization}
+\begin_inset Quotes sld
+\end_inset
+diff -Naur unmodified_directory modified_directory >my_changes.patch
+\begin_inset Quotes srd
\end_inset
-\layout Standard
+\family default
+\series default
+ will be fine, otherwise
+\family sans
+\series bold
-Two types of loop optimizations are done by SDCC loop invariant lifting
- and strength reduction of loop induction variables.
- In addition to the strength reduction the optimizer marks the induction
- variables and the register allocator tries to keep the induction variables
- in registers for the duration of the loop.
- Because of this preference of the register allocator
-\begin_inset LatexCommand \index{Register allocation}
+\begin_inset Quotes sld
+\end_inset
+diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
+\begin_inset Quotes srd
\end_inset
-, loop induction optimization causes an increase in register pressure, which
- may cause unwanted spilling of other temporary variables into the stack
-\begin_inset LatexCommand \index{stack}
-\end_inset
+\series default
+
+\family default
+will do.
+\layout Section
- / data space.
- The compiler will generate a warning message when it is forced to allocate
- extra space either on the stack or data space.
- If this extra space allocation is undesirable then induction optimization
- can be eliminated either for the entire source file (with -
-\begin_inset ERT
-status Collapsed
+Getting Help
+\layout Standard
+
+These links should take you directly to the
+\begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
+
+\end_inset
+
+
+\begin_inset Foot
+collapsed false
\layout Standard
-\backslash
-/
+Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
+ automated messages (mid 2003)
\end_inset
--noinduction option) or for a given function only using #pragma\SpecialChar ~
-noinduction
-\begin_inset LatexCommand \index{\#pragma noinduction}
+ and the
+\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
\end_inset
-.
-\newline
+, lists and forums are archived and searchable so if you are lucky someone
+ already had a similar problem.
+\layout Section
-\newline
-Loop Invariant:
-\layout Verse
+ChangeLog
+\layout Standard
+You can follow the status of the cvs version
+\begin_inset LatexCommand \index{version}
-\family typewriter
-for (i = 0 ; i < 100 ; i ++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-f += k + l;
-\layout Standard
+\end_inset
-changed to
-\layout Verse
+ of SDCC by watching the Changelog
+\begin_inset LatexCommand \index{Changelog}
+\end_inset
-\family typewriter
-itemp = k + l;
-\newline
-for (i = 0; i < 100; i++)
+ in the cvs-repository
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-f += itemp;
-\layout Standard
-As mentioned previously some loop invariants are not as apparent, all static
- address computations are also moved out of the loop.
-\newline
+\size footnotesize
-\newline
-Strength Reduction
-\begin_inset LatexCommand \index{Strength reduction}
+\begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
\end_inset
-, this optimization substitutes an expression by a cheaper expression:
-\layout Verse
-
+.
+\layout Section
-\family typewriter
-for (i=0;i < 100; i++)
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ar[i*5] = i*3;
-\layout Standard
+Release policy
+\begin_inset LatexCommand \index{Release policy}
-changed to
-\layout Verse
+\end_inset
-\family typewriter
-itemp1 = 0;
-\newline
-itemp2 = 0;
-\newline
-for (i=0;i< 100;i++) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-ar[itemp1] = itemp2;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-itemp1 += 5;
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-itemp2 += 3;
-\newline
-}
\layout Standard
-The more expensive multiplication
-\begin_inset LatexCommand \index{Multiplication}
+Historically there often were long delays between official releases and
+ the sourceforge download area tends to get not updated at all.
+ Excuses in the past might have referred to problems with live range analysis,
+ but as this was fixed a while ago, the current problem is that another
+ excuse has to be found.
+ Kidding aside, we have to get better there! On the other hand there are
+ daily snapshots available at
+\begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
\end_inset
- is changed to a less expensive addition.
-\layout Subsection
-
-Loop Reversing
-\begin_inset LatexCommand \index{Loop reversing}
+, and you can always build the very last version (hopefully with many bugs
+ fixed, and features added) from the source code available at
+\begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
\end_inset
+.
+\layout Section
-\layout Standard
-
-This optimization is done to reduce the overhead of checking loop boundaries
- for every iteration.
- Some simple loops can be reversed and implemented using a
-\begin_inset Quotes eld
-\end_inset
+Examples
+\begin_inset LatexCommand \index{Examples}
-decrement and jump if not zero
-\begin_inset Quotes erd
\end_inset
- instruction.
- SDCC checks for the following criterion to determine if a loop is reversible
- (note: more sophisticated compilers use data-dependency analysis to make
- this determination, SDCC uses a more simple minded analysis).
-\layout Itemize
-
-The 'for' loop is of the form
-\newline
-\newline
+\layout Standard
-\family typewriter
-for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
- += 1])
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-<for body>
-\layout Itemize
+You'll find some small examples in the directory
+\emph on
+sdcc/device/examples/.
+
+\emph default
+More examples and libraries are available at
+\emph on
+ The SDCC Open Knowledge Resource
+\begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
-The <for body> does not contain
-\begin_inset Quotes eld
\end_inset
-continue
-\begin_inset Quotes erd
-\end_inset
+
+\emph default
+web site or at
+\begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
- or 'break
-\begin_inset Quotes erd
\end_inset
.
-\layout Itemize
+\layout Comment
-All goto's are contained within the loop.
-\layout Itemize
+I did insert a reference to Paul's web site here although it seems rather
+ dedicated to a specific 8032 board (I think it's okay because it f.e.
+ shows LCD/Harddisc interface and has a free 8051 monitor.
+ Independent 8032 board vendors face hard competition of heavily subsidized
+ development boards anyway).
+\layout Comment
-No function calls within the loop.
-\layout Itemize
+Maybe we should include some links to real world applications.
+ Preferably pointer to pointers (one for each architecture) so this stays
+ manageable here?
+\layout Section
-The loop control variable <sym> is not assigned any value within the loop
-\layout Itemize
+Quality control
+\begin_inset LatexCommand \index{Quality control}
-The loop control variable does NOT participate in any arithmetic operation
- within the loop.
-\layout Itemize
+\end_inset
-There are NO switch statements in the loop.
-\layout Subsection
-Algebraic Simplifications
\layout Standard
-SDCC does numerous algebraic simplifications, the following is a small sub-set
- of these optimizations.
-\layout Verse
+The compiler is passed through nightly compile and build checks.
+ The so called
+\shape italic
+regression tests
+\shape default
+\begin_inset LatexCommand \index{Regression test}
-\family typewriter
-i = j + 0;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- /* changed to: */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- i = j;
-\newline
-i /= 2;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- /* changed to: */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- i >>= 1;
-\newline
-i = j - j;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- /* changed to: */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- i = 0;
-\newline
-i = j / 1;\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- /* changed to: */\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
- i = j;
-\layout Standard
+\end_inset
-Note the subexpressions
-\begin_inset LatexCommand \index{Subexpression}
+ check that SDCC itself compiles flawlessly on several platforms and checks
+ the quality of the code generated by SDCC by running the code through simulator
+s.
+ There is a separate document
+\shape italic
+test_suite.pdf
+\begin_inset LatexCommand \index{Test suite}
\end_inset
- given above are generally introduced by macro expansions or as a result
- of copy/constant propagation.
-\layout Subsection
-'switch' Statements
-\begin_inset LatexCommand \label{sub:'switch'-Statements}
+\shape default
+ about this.
+\layout Standard
+
+You'll find the test code in the directory
+\shape italic
+sdcc/support/regression
+\shape default
+.
+ You can run these tests manually by running
+\family sans
+make
+\family default
+ in this directory (or f.e.
+
+\family sans
+\series bold
+\begin_inset Quotes sld
+\end_inset
+
+make test-mcs51
+\begin_inset Quotes srd
\end_inset
-\begin_inset LatexCommand \index{switch statement}
+\family default
+\series default
+ if you don't want to run the complete tests).
+ The test code might also be interesting if you want to look for examples
+\begin_inset LatexCommand \index{Examples}
\end_inset
+ checking corner cases of SDCC or if you plan to submit patches
+\begin_inset LatexCommand \index{Patch submission}
+
+\end_inset
+.
\layout Standard
-SDCC changes switch statements to jump tables
-\begin_inset LatexCommand \index{jump tables}
+The pic port uses a different set of regression tests, you'll find them
+ in the directory
+\shape italic
+sdcc/src/regression
+\shape default
+.
+\layout Chapter
+\pagebreak_top
+SDCC Technical Data
+\layout Section
+
+Optimizations
+\begin_inset LatexCommand \index{Optimizations}
\end_inset
- when the following conditions are true.
+
+\layout Standard
+
+SDCC performs a host of standard optimizations in addition to some MCU specific
+ optimizations.
-\layout Itemize
+\layout Subsection
-The case labels are in numerical sequence, the labels need not be in order,
- and the starting number need not be one or zero.
-\begin_deeper
-\layout Verse
+Sub-expression Elimination
+\begin_inset LatexCommand \index{Subexpression elimination}
+\end_inset
-\family typewriter
-switch(i) {\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-switch (i) {
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 4: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 0: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 5: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 1: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 3: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 2: ...
-
-\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 6: ...\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-case 3: ...
-
+
+\layout Standard
+
+The compiler does local and
+\emph on
+g
+\emph default
+lobal
+\emph on
+c
+\emph default
+ommon
+\emph on
+s
+\emph default
+ubexpression
+\emph on
+e
+\emph default
+limination, e.g.:
+\layout Verse
+
+
+\family typewriter
+i = x + y + 1;
\newline
-}\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-}
+j = x + y;
\layout Standard
-Both the above switch statements will be implemented using a jump-table.
- The example to the right side is slightly more efficient as the check for
- the lower boundary of the jump-table is not needed.
-\end_deeper
-\layout Itemize
+will be translated to
+\layout Verse
-The number of case labels is at least three, since it takes two conditional
- statements to handle the boundary conditions.
-\layout Itemize
-The number of case labels is less than 84, since each label takes 3 bytes
- and a jump-table can be utmost 256 bytes long.
+\family typewriter
+iTemp = x + y;
+\newline
+i = iTemp + 1;
+\newline
+j = iTemp;
\layout Standard
-Switch statements which have gaps in the numeric sequence or those that
- have more that 84 case labels can be split into more than one switch statement
- for efficient code generation, e.g.:
+Some subexpressions are not as obvious as the above example, e.g.:
\layout Verse
\family typewriter
-switch (i) {
+a->b[i].c = 10;
+\newline
+a->b[i].d = 11;
+\layout Standard
+
+In this case the address arithmetic a->b[i] will be computed only once;
+ the equivalent code in C would be.
+\layout Verse
+
+
+\family typewriter
+iTemp = a->b[i];
+\newline
+iTemp.c = 10;
+\newline
+iTemp.d = 11;
+\layout Standard
+
+The compiler will try to keep these temporary variables in registers.
+\layout Subsection
+
+Dead-Code Elimination
+\begin_inset LatexCommand \index{Dead-code elimination}
+
+\end_inset
+
+
+\layout Verse
+
+
+\family typewriter
+int global;
+\newline
+
+\newline
+void f () {
\newline
\SpecialChar ~
\SpecialChar ~
-case 1: ...
-
+int i;
\newline
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
+i = 1; \SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* dead store */
\newline
\SpecialChar ~
\SpecialChar ~
-case 3: ...
-
+global = 1;\SpecialChar ~
+/* dead store */
\newline
\SpecialChar ~
\SpecialChar ~
-case 4: ...
-
+global = 2;
\newline
\SpecialChar ~
\SpecialChar ~
-case 9: ...
-
+return;
\newline
\SpecialChar ~
\SpecialChar ~
-case 10: ...
-
+global = 3;\SpecialChar ~
+/* unreachable */
+\newline
+}
+\layout Standard
+
+will be changed to
+\layout Verse
+
+
+\family typewriter
+int global;
+\newline
+
+\newline
+void f () {
\newline
\SpecialChar ~
\SpecialChar ~
-case 11: ...
-
+global = 2;
\newline
\SpecialChar ~
\SpecialChar ~
-case 12: ...
-
+return;
\newline
}
-\layout Standard
+\layout Subsection
+
+Copy-Propagation
+\begin_inset LatexCommand \index{Copy propagation}
+
+\end_inset
+
-If the above switch statement is broken down into two switch statements
\layout Verse
\family typewriter
-switch (i) {
+int f() {
\newline
\SpecialChar ~
\SpecialChar ~
-case 1: ...
-
+int i, j;
\newline
\SpecialChar ~
\SpecialChar ~
-case 2: ...
-
+i = 10;
\newline
\SpecialChar ~
\SpecialChar ~
-case 3: ...
-
+j = i;
\newline
\SpecialChar ~
\SpecialChar ~
-case 4: ...
-
+return j;
\newline
}
\layout Standard
-and
+will be changed to
\layout Verse
\family typewriter
-switch (i) {
+int f() {
\newline
\SpecialChar ~
\SpecialChar ~
-case 9:\SpecialChar ~
-\SpecialChar ~
-...
-
+int i, j;
\newline
\SpecialChar ~
\SpecialChar ~
-case 10:\SpecialChar ~
-...
-
+i = 10;
\newline
\SpecialChar ~
\SpecialChar ~
-case 11:\SpecialChar ~
-...
-
+j = 10;
\newline
\SpecialChar ~
\SpecialChar ~
-case 12:\SpecialChar ~
-...
-
+return 10;
\newline
}
\layout Standard
-then both the switch statements will be implemented using jump-tables whereas
- the unmodified switch statement will not be.
- You might also consider inserting dummy cases 0 and 5 to 8 in this example.
-
-\newline
-The pragma nojtbound
-\begin_inset LatexCommand \index{\#pragma nojtbound}
+Note: the dead stores created by this copy propagation will be eliminated
+ by dead-code elimination.
+\layout Subsection
+
+Loop Optimizations
+\begin_inset LatexCommand \index{Loop optimization}
\end_inset
- can be used to turn off checking the
-\emph on
-j
-\emph default
-ump
-\emph on
-t
-\emph default
-able
-\emph on
-bound
-\emph default
-aries.
- It has no effect if a default label is supplied.
- Use of this pragma is dangerous: if the switch argument is not matched
- by a case statement the processor will happily jump into Nirvana.
-\layout Subsection
-Bit-shifting Operations
-\begin_inset LatexCommand \index{Bit shifting}
+\layout Standard
+
+Two types of loop optimizations are done by SDCC loop invariant lifting
+ and strength reduction of loop induction variables.
+ In addition to the strength reduction the optimizer marks the induction
+ variables and the register allocator tries to keep the induction variables
+ in registers for the duration of the loop.
+ Because of this preference of the register allocator
+\begin_inset LatexCommand \index{Register allocation}
\end_inset
-.
+, loop induction optimization causes an increase in register pressure, which
+ may cause unwanted spilling of other temporary variables into the stack
+\begin_inset LatexCommand \index{stack}
+
+\end_inset
+
+ / data space.
+ The compiler will generate a warning message when it is forced to allocate
+ extra space either on the stack or data space.
+ If this extra space allocation is undesirable then induction optimization
+ can be eliminated either for the entire source file (with -
+\begin_inset ERT
+status Collapsed
+
\layout Standard
-Bit shifting is one of the most frequently used operation in embedded programmin
-g.
- SDCC tries to implement bit-shift operations in the most efficient way
- possible, e.g.:
-\layout Verse
+\backslash
+/
+\end_inset
+
+-noinduction option) or for a given function only using #pragma\SpecialChar ~
+noinduction
+\begin_inset LatexCommand \index{\#pragma noinduction}
+\end_inset
-\family typewriter
-unsigned char i;
-\newline
-...
-
-\newline
-i >>= 4;
+.
\newline
-...
-\layout Standard
-generates the following code:
+\newline
+Loop Invariant:
\layout Verse
\family typewriter
-mov\SpecialChar ~
- a,_i
-\newline
-swap a
-\newline
-anl\SpecialChar ~
- a,#0x0f
+for (i = 0 ; i < 100 ; i ++)
\newline
-mov\SpecialChar ~
- _i,a
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+f += k + l;
\layout Standard
-In general SDCC will never setup a loop if the shift count is known.
- Another example:
+changed to
\layout Verse
\family typewriter
-unsigned int i;
-\newline
-...
-
+itemp = k + l;
\newline
-i >>= 9;
+for (i = 0; i < 100; i++)
\newline
-...
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+f += itemp;
\layout Standard
-will generate:
+As mentioned previously some loop invariants are not as apparent, all static
+ address computations are also moved out of the loop.
+\newline
+
+\newline
+Strength Reduction
+\begin_inset LatexCommand \index{Strength reduction}
+
+\end_inset
+
+, this optimization substitutes an expression by a cheaper expression:
\layout Verse
\family typewriter
-mov\SpecialChar ~
-\SpecialChar ~
-a,(_i + 1)
+for (i=0;i < 100; i++)
\newline
-mov\SpecialChar ~
\SpecialChar ~
-(_i + 1),#0x00
-\newline
-clr\SpecialChar ~
\SpecialChar ~
-c
-\newline
-rrc\SpecialChar ~
\SpecialChar ~
-a
-\newline
-mov\SpecialChar ~
\SpecialChar ~
-_i,a
-\layout Subsection
-
-Bit-rotation
-\begin_inset LatexCommand \index{Bit rotation}
-
-\end_inset
-
-
+ar[i*5] = i*3;
\layout Standard
-A special case of the bit-shift operation is bit rotation
-\begin_inset LatexCommand \index{rotating bits}
-
-\end_inset
-
-, SDCC recognizes the following expression to be a left bit-rotation:
+changed to
\layout Verse
\family typewriter
-\series bold
-unsigned
-\series default
+itemp1 = 0;
+\newline
+itemp2 = 0;
+\newline
+for (i=0;i< 100;i++) {
+\newline
\SpecialChar ~
\SpecialChar ~
-char i;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+ar[itemp1] = itemp2;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+itemp1 += 5;
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-/* unsigned is needed for rotation */
-\newline
-...
-
+itemp2 += 3;
\newline
-i = ((i << 1) | (i >> 7));
-\family default
+}
+\layout Standard
+
+The more expensive multiplication
+\begin_inset LatexCommand \index{Multiplication}
+
+\end_inset
+
+ is changed to a less expensive addition.
+\layout Subsection
+
+Loop Reversing
+\begin_inset LatexCommand \index{Loop reversing}
+
+\end_inset
-\newline
-\family typewriter
-...
\layout Standard
-will generate the following code:
-\layout Verse
+This optimization is done to reduce the overhead of checking loop boundaries
+ for every iteration.
+ Some simple loops can be reversed and implemented using a
+\begin_inset Quotes eld
+\end_inset
+
+decrement and jump if not zero
+\begin_inset Quotes erd
+\end_inset
+
+ instruction.
+ SDCC checks for the following criterion to determine if a loop is reversible
+ (note: more sophisticated compilers use data-dependency analysis to make
+ this determination, SDCC uses a more simple minded analysis).
+\layout Itemize
+
+The 'for' loop is of the form
+\newline
+\newline
\family typewriter
-mov\SpecialChar ~
-\SpecialChar ~
-a,_i
+for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
+ += 1])
\newline
-rl\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-a
-\newline
-mov\SpecialChar ~
\SpecialChar ~
-_i,a
-\layout Standard
+\SpecialChar ~
+<for body>
+\layout Itemize
-SDCC uses pattern matching on the parse tree to determine this operation.Variatio
-ns of this case will also be recognized as bit-rotation, i.e.:
-\layout Verse
+The <for body> does not contain
+\begin_inset Quotes eld
+\end_inset
+continue
+\begin_inset Quotes erd
+\end_inset
-\family typewriter
-i = ((i >> 7) | (i << 1)); /* left-bit rotation */
-\layout Subsection
+ or 'break
+\begin_inset Quotes erd
+\end_inset
-Nibble and Byte Swapping
-\layout Standard
+.
+\layout Itemize
-Other special cases of the bit-shift operations are nibble or byte swapping
-\begin_inset LatexCommand \index{swapping nibbles/bytes}
+All goto's are contained within the loop.
+\layout Itemize
-\end_inset
+No function calls within the loop.
+\layout Itemize
-, SDCC recognizes the following expressions:
+The loop control variable <sym> is not assigned any value within the loop
+\layout Itemize
+
+The loop control variable does NOT participate in any arithmetic operation
+ within the loop.
+\layout Itemize
+
+There are NO switch statements in the loop.
+\layout Subsection
+
+Algebraic Simplifications
+\layout Standard
+
+SDCC does numerous algebraic simplifications, the following is a small sub-set
+ of these optimizations.
\layout Verse
\family typewriter
-\series bold
-unsigned
-\series default
+i = j + 0;\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-char i;
-\newline
-
-\series bold
-unsigned
-\series default
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-int j;
+\SpecialChar ~
+ i = j;
\newline
-...
-
+i /= 2;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i >>= 1;
\newline
-i = ((i << 4) | (i >> 4));
-\family default
-
+i = j - j;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = 0;
\newline
-
-\family typewriter
-j = ((j << 8) | (j >> 8));
+i = j / 1;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ /* changed to: */\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ i = j;
\layout Standard
-and generates a swap instruction for the nibble swapping
-\begin_inset LatexCommand \index{Nibble swapping}
-
-\end_inset
-
- or move instructions for the byte swapping
-\begin_inset LatexCommand \index{Byte swapping}
-
-\end_inset
-
-.
- The
-\begin_inset Quotes sld
-\end_inset
+Note the subexpressions
+\begin_inset LatexCommand \index{Subexpression}
-j
-\begin_inset Quotes srd
\end_inset
- example can be used to convert from little to big-endian or vice versa.
- If you want to change the endianness of a
-\emph on
-signed
-\emph default
- integer you have to cast to
-\family typewriter
-(unsigned int)
-\family default
- first.
-\layout Standard
-
-Note that SDCC stores numbers in little-endian
-\begin_inset Foot
-collapsed false
-
-\layout Standard
-
-Usually 8-bit processors don't care much about endianness.
- This is not the case for the standard 8051 which only has an instruction
- to increment its
-\emph on
-dptr
-\emph default
-
-\begin_inset LatexCommand \index{DPTR}
+ given above are generally introduced by macro expansions or as a result
+ of copy/constant propagation.
+\layout Subsection
-\end_inset
+'switch' Statements
+\begin_inset LatexCommand \label{sub:'switch'-Statements}
--datapointer
-\emph on
-
-\emph default
-so little-endian is the more efficient byte order.
\end_inset
-\begin_inset LatexCommand \index{little-endian}
+\begin_inset LatexCommand \index{switch statement}
\end_inset
-\begin_inset LatexCommand \index{Endianness}
-
-\end_inset
-
- format (i.e.
- lowest order first).
-\layout Subsection
+\layout Standard
-Highest Order Bit
-\begin_inset LatexCommand \index{Highest Order Bit}
+SDCC changes switch statements to jump tables
+\begin_inset LatexCommand \index{jump tables}
\end_inset
+ when the following conditions are true.
+
+\layout Itemize
-\layout Standard
-
-It is frequently required to obtain the highest order bit of an integral
- type (long, int, short or char types).
- SDCC recognizes the following expression to yield the highest order bit
- and generates optimized code for it, e.g.:
+The case labels are in numerical sequence, the labels need not be in order,
+ and the starting number need not be one or zero.
+\begin_deeper
\layout Verse
\family typewriter
-unsigned int gint;
-\newline
-
-\newline
-foo () {
-\newline
+switch(i) {\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-unsigned char hob;
-\newline
\SpecialChar ~
\SpecialChar ~
-...
-
-\newline
\SpecialChar ~
\SpecialChar ~
-hob = (gint >> 15) & 1;
-\newline
\SpecialChar ~
\SpecialChar ~
-..
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+switch (i) {
\newline
-}
-\layout Standard
-
-will generate the following code:
-\layout Verse
-
-
-\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 4: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 61 ;\SpecialChar ~
- hob.c 7
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 0: ...
+
\newline
-000A E5*01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 5: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 62\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- mov\SpecialChar ~
\SpecialChar ~
- a,(_gint + 1)
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
\newline
-000C 23\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 3: ...\SpecialChar ~
+\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 63\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- rl\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- a
+\SpecialChar ~
+case 2: ...
+
\newline
-000D 54 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+case 6: ...\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 64\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- anl\SpecialChar ~
\SpecialChar ~
- a,#0x01
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
\newline
-000F F5*02\SpecialChar ~
+}\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- 65\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
- mov\SpecialChar ~
\SpecialChar ~
- _foo_hob_1_1,a
-\layout Standard
-
-Variations of this case however will
-\emph on
-not
-\emph default
- be recognized.
- It is a standard C expression, so I heartily recommend this be the only
- way to get the highest order bit, (it is portable).
- Of course it will be recognized even if it is embedded in other expressions,
- e.g.:
-\layout Verse
-
-
-\family typewriter
-xyz = gint + ((gint >> 15) & 1);
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+}
\layout Standard
-will still be recognized.
-\layout Subsection
-
-Peephole Optimizer
-\begin_inset LatexCommand \label{sub:Peephole-Optimizer}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{Peephole optimizer}
-
-\end_inset
-
-
-\layout Standard
+Both the above switch statements will be implemented using a jump-table.
+ The example to the right side is slightly more efficient as the check for
+ the lower boundary of the jump-table is not needed.
+\end_deeper
+\layout Itemize
-The compiler uses a rule based, pattern matching and re-writing mechanism
- for peep-hole optimization.
- It is inspired by
-\emph on
-copt
-\emph default
- a peep-hole optimizer by Christopher W.
- Fraser (cwfraser@microsoft.com).
- A default set of rules are compiled into the compiler, additional rules
- may be added with the
-\emph on
--
-\begin_inset ERT
-status Collapsed
+The number of case labels is at least three, since it takes two conditional
+ statements to handle the boundary conditions.
+\layout Itemize
+The number of case labels is less than 84, since each label takes 3 bytes
+ and a jump-table can be utmost 256 bytes long.
\layout Standard
-\backslash
-/
-\end_inset
-
--peep-file
-\begin_inset LatexCommand \index{-\/-peep-file}
-
-\end_inset
-
- <filename>
-\emph default
- option.
- The rule language is best illustrated with examples.
+Switch statements which have gaps in the numeric sequence or those that
+ have more that 84 case labels can be split into more than one switch statement
+ for efficient code generation, e.g.:
\layout Verse
\family typewriter
-replace {
+switch (i) {
\newline
\SpecialChar ~
\SpecialChar ~
-mov %1,a
+case 1: ...
+
\newline
\SpecialChar ~
\SpecialChar ~
-mov a,%1
+case 2: ...
+
\newline
-} by {
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
\newline
\SpecialChar ~
\SpecialChar ~
-mov %1,a
+case 4: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 9: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 10: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 11: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 12: ...
+
\newline
}
\layout Standard
-The above rule will change the following assembly
-\begin_inset LatexCommand \index{Assembler routines}
-
-\end_inset
-
- sequence:
+If the above switch statement is broken down into two switch statements
\layout Verse
\family typewriter
-mov r1,a
+switch (i) {
\newline
-mov a,r1
-\layout Standard
-
-to
-\layout Verse
-
-
-\family typewriter
-mov r1,a
+\SpecialChar ~
+\SpecialChar ~
+case 1: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 2: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 3: ...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 4: ...
+
+\newline
+}
\layout Standard
-Note: All occurrences of a
-\emph on
-%n
-\emph default
- (pattern variable) must denote the same string.
- With the above rule, the assembly sequence:
+and
\layout Verse
\family typewriter
-mov r1,a
+switch (i) {
\newline
-mov a,r2
-\layout Standard
-
-will remain unmodified.
+\SpecialChar ~
+\SpecialChar ~
+case 9:\SpecialChar ~
+\SpecialChar ~
+...
+
\newline
-
+\SpecialChar ~
+\SpecialChar ~
+case 10:\SpecialChar ~
+...
+
\newline
-Other special case optimizations may be added by the user (via
-\emph on
--
-\begin_inset ERT
-status Collapsed
-
+\SpecialChar ~
+\SpecialChar ~
+case 11:\SpecialChar ~
+...
+
+\newline
+\SpecialChar ~
+\SpecialChar ~
+case 12:\SpecialChar ~
+...
+
+\newline
+}
\layout Standard
-\backslash
-/
+then both the switch statements will be implemented using jump-tables whereas
+ the unmodified switch statement will not be.
+ You might also consider inserting dummy cases 0 and 5 to 8 in this example.
+
+\newline
+The pragma nojtbound
+\begin_inset LatexCommand \index{\#pragma nojtbound}
+
\end_inset
--peep-file option
+ can be used to turn off checking the
+\emph on
+j
\emph default
-).
- E.g.
- some variants of the 8051 MCU allow only
-\family typewriter
-ajmp
-\family default
- and
-\family typewriter
-acall
-\family default
-.
- The following two rules will change all
-\family typewriter
-ljmp
-\family default
- and
-\family typewriter
-lcall
-\family default
- to
-\family typewriter
-ajmp
-\family default
- and
-\family typewriter
-acall
-\layout Verse
-
-
-\family typewriter
-replace { lcall %1 } by { acall %1 }
-\newline
-replace { ljmp %1 } by { ajmp %1 }
-\layout Standard
-
-The
+ump
\emph on
-inline-assembler code
+t
\emph default
- is also passed through the peep hole optimizer, thus the peephole optimizer
- can also be used as an assembly level macro expander.
- The rules themselves are MCU dependent whereas the rule language infra-structur
-e is MCU independent.
- Peephole optimization rules for other MCU can be easily programmed using
- the rule language.
-\newline
-
-\newline
-The syntax for a rule is as follows:
-\layout Verse
-
+able
+\emph on
+bound
+\emph default
+aries.
+ It has no effect if a default label is supplied.
+ Use of this pragma is dangerous: if the switch argument is not matched
+ by a case statement the processor will happily jump into Nirvana.
+\layout Subsection
-\family typewriter
-rule := replace [ restart ] '{' <assembly sequence> '
-\backslash
-n'
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' by '{' '
-\backslash
-n'
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- <assembly sequence> '
-\backslash
-n'
-\newline
-\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
- '}' [if <functionName> ] '
-\backslash
-n'
+Bit-shifting Operations
+\begin_inset LatexCommand \index{Bit shifting}
+
+\end_inset
+
+.
\layout Standard
-<assembly sequence> := assembly instruction (each instruction including
- labels must be on a separate line).
+Bit shifting is one of the most frequently used operation in embedded programmin
+g.
+ SDCC tries to implement bit-shift operations in the most efficient way
+ possible, e.g.:
+\layout Verse
+
+
+\family typewriter
+unsigned char i;
\newline
+...
+
+\newline
+i >>= 4;
+\newline
+...
+\layout Standard
+
+generates the following code:
+\layout Verse
+
+\family typewriter
+mov\SpecialChar ~
+ a,_i
\newline
-The optimizer will apply to the rules one by one from the top in the sequence
- of their appearance, it will terminate when all rules are exhausted.
- If the 'restart' option is specified, then the optimizer will start matching
- the rules again from the top, this option for a rule is expensive (performance)
-, it is intended to be used in situations where a transformation will trigger
- the same rule again.
- An example of this (not a good one, it has side effects) is the following
- rule:
+swap a
+\newline
+anl\SpecialChar ~
+ a,#0x0f
+\newline
+mov\SpecialChar ~
+ _i,a
+\layout Standard
+
+In general SDCC will never setup a loop if the shift count is known.
+ Another example:
\layout Verse
\family typewriter
-replace restart {
+unsigned int i;
\newline
-\SpecialChar ~
-\SpecialChar ~
-pop %1
+...
+
\newline
+i >>= 9;
+\newline
+...
+\layout Standard
+
+will generate:
+\layout Verse
+
+
+\family typewriter
+mov\SpecialChar ~
\SpecialChar ~
+a,(_i + 1)
+\newline
+mov\SpecialChar ~
\SpecialChar ~
-push %1 } by {
+(_i + 1),#0x00
\newline
+clr\SpecialChar ~
\SpecialChar ~
+c
+\newline
+rrc\SpecialChar ~
\SpecialChar ~
-; nop
+a
\newline
-}
+mov\SpecialChar ~
+\SpecialChar ~
+_i,a
+\layout Subsection
+
+Bit-rotation
+\begin_inset LatexCommand \index{Bit rotation}
+
+\end_inset
+
+
\layout Standard
-Note that the replace pattern cannot be a blank, but can be a comment line.
- Without the 'restart' option only the innermost 'pop' 'push' pair would
- be eliminated, i.e.:
+A special case of the bit-shift operation is bit rotation
+\begin_inset LatexCommand \index{rotating bits}
+
+\end_inset
+
+, SDCC recognizes the following expression to be a left bit-rotation:
\layout Verse
\family typewriter
-pop ar1
+\series bold
+unsigned
+\series default
+\SpecialChar ~
+\SpecialChar ~
+char i;\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+/* unsigned is needed for rotation */
\newline
-pop ar2
+...
+
\newline
-push ar2
+i = ((i << 1) | (i >> 7));
+\family default
+
\newline
-push ar1
+
+\family typewriter
+...
\layout Standard
-would result in:
+will generate the following code:
\layout Verse
\family typewriter
-pop ar1
+mov\SpecialChar ~
+\SpecialChar ~
+a,_i
\newline
-; nop
+rl\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+a
\newline
-push ar1
+mov\SpecialChar ~
+\SpecialChar ~
+_i,a
\layout Standard
-
-\emph on
-with
-\emph default
- the restart option the rule will be applied again to the resulting code
- and then all the pop-push pairs will be eliminated to yield:
+SDCC uses pattern matching on the parse tree to determine this operation.Variatio
+ns of this case will also be recognized as bit-rotation, i.e.:
\layout Verse
\family typewriter
-; nop
-\newline
-; nop
+i = ((i >> 7) | (i << 1)); /* left-bit rotation */
+\layout Subsection
+
+Nibble and Byte Swapping
\layout Standard
-A conditional function can be attached to a rule.
- Attaching rules are somewhat more involved, let me illustrate this with
- an example.
+Other special cases of the bit-shift operations are nibble or byte swapping
+\begin_inset LatexCommand \index{swapping nibbles/bytes}
+
+\end_inset
+
+, SDCC recognizes the following expressions:
\layout Verse
\family typewriter
-replace {
-\newline
+\series bold
+unsigned
+\series default
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-ljmp %5
-\newline
-%2:
-\newline
-} by {
+\SpecialChar ~
+char i;
\newline
+
+\series bold
+unsigned
+\series default
\SpecialChar ~
- \SpecialChar ~
- \SpecialChar ~
-sjmp %5
+\SpecialChar ~
+int j;
\newline
-%2:
+...
+
\newline
-} if labelInRange
+i = ((i << 4) | (i >> 4));
+\family default
+
+\newline
+
+\family typewriter
+j = ((j << 8) | (j >> 8));
\layout Standard
-The optimizer does a look-up of a function name table defined in function
-
-\emph on
-callFuncByName
-\emph default
- in the source file SDCCpeeph.c, with the name
-\emph on
-labelInRange
-\emph default
+and generates a swap instruction for the nibble swapping
+\begin_inset LatexCommand \index{Nibble swapping}
+
+\end_inset
+
+ or move instructions for the byte swapping
+\begin_inset LatexCommand \index{Byte swapping}
+
+\end_inset
+
.
- If it finds a corresponding entry the function is called.
- Note there can be no parameters specified for these functions, in this
- case the use of
-\emph on
-%5
-\emph default
- is crucial, since the function
-\emph on
-labelInRange
-\emph default
- expects to find the label in that particular variable (the hash table containin
-g the variable bindings is passed as a parameter).
- If you want to code more such functions, take a close look at the function
- labelInRange and the calling mechanism in source file SDCCpeeph.c.
- Currently implemented are
-\emph on
-labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
- 24bitMode, portIsDS390, 24bitModeAndPortDS390
-\emph default
-and
+ The
+\begin_inset Quotes sld
+\end_inset
+
+j
+\begin_inset Quotes srd
+\end_inset
+
+ example can be used to convert from little to big-endian or vice versa.
+ If you want to change the endianness of a
\emph on
- notVolatile
+signed
\emph default
-.
+ integer you have to cast to
+\family typewriter
+(unsigned int)
+\family default
+ first.
\layout Standard
-I know this whole thing is a little kludgey, but maybe some day we will
- have some better means.
- If you are looking at this file, you will see the default rules that are
- compiled into the compiler, you can add your own rules in the default set
- there if you get tired of specifying the -
-\begin_inset ERT
-status Collapsed
+Note that SDCC stores numbers in little-endian
+\begin_inset Foot
+collapsed false
\layout Standard
-\backslash
-/
-\end_inset
+Usually 8-bit processors don't care much about endianness.
+ This is not the case for the standard 8051 which only has an instruction
+ to increment its
+\emph on
+dptr
+\emph default
--peep-file option.
-\layout Section
+\begin_inset LatexCommand \index{DPTR}
-ANSI-Compliance
-\begin_inset LatexCommand \index{ANSI-compliance}
+\end_inset
+-datapointer
+\emph on
+
+\emph default
+so little-endian is the more efficient byte order.
\end_inset
-\begin_inset LatexCommand \label{sub:ANSI-Compliance}
+\begin_inset LatexCommand \index{little-endian}
\end_inset
-\layout Standard
+\begin_inset LatexCommand \index{Endianness}
-Deviations from the compliance:
-\layout Itemize
+\end_inset
-functions are not always reentrant
-\begin_inset LatexCommand \index{reentrant}
+ format (i.e.
+ lowest order first).
+\layout Subsection
+
+Highest Order Bit
+\begin_inset LatexCommand \index{Highest Order Bit}
\end_inset
-.
-\layout Itemize
-structures cannot be assigned values directly, cannot be passed as function
- parameters or assigned to each other and cannot be a return value from
- a function, e.g.:
-\begin_deeper
+\layout Standard
+
+It is frequently required to obtain the highest order bit of an integral
+ type (long, int, short or char types).
+ SDCC recognizes the following expression to yield the highest order bit
+ and generates optimized code for it, e.g.:
\layout Verse
\family typewriter
-struct s { ...
- };
-\newline
-struct s s1, s2;
+unsigned int gint;
\newline
-foo()
+
\newline
-{
+foo () {
\newline
\SpecialChar ~
\SpecialChar ~
+unsigned char hob;
+\newline
\SpecialChar ~
\SpecialChar ~
...
\newline
\SpecialChar ~
\SpecialChar ~
+hob = (gint >> 15) & 1;
+\newline
\SpecialChar ~
\SpecialChar ~
-s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
+..
+
\newline
+}
+\layout Standard
+
+will generate the following code:
+\layout Verse
+
+
+\family typewriter
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
-\newline
-}
-\newline
-struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
- */
-\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 61 ;\SpecialChar ~
+ hob.c 7
\newline
+000A E5*01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-struct s rets;
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 62\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ a,(_gint + 1)
\newline
+000C 23\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-...
-
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 63\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ rl\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ a
\newline
+000D 54 01\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-return rets;/* is invalid in SDCC although allowed in ANSI */
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 64\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ anl\SpecialChar ~
+\SpecialChar ~
+ a,#0x01
\newline
-}
-\end_deeper
-\layout Itemize
-
-'long long
-\begin_inset LatexCommand \index{long long (not supported)}
+000F F5*02\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ 65\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+\SpecialChar ~
+ mov\SpecialChar ~
+\SpecialChar ~
+ _foo_hob_1_1,a
+\layout Standard
-\end_inset
+Variations of this case however will
+\emph on
+not
+\emph default
+ be recognized.
+ It is a standard C expression, so I heartily recommend this be the only
+ way to get the highest order bit, (it is portable).
+ Of course it will be recognized even if it is embedded in other expressions,
+ e.g.:
+\layout Verse
-' (64 bit integers
-\begin_inset LatexCommand \index{int (64 bit) (not supported)}
-\end_inset
+\family typewriter
+xyz = gint + ((gint >> 15) & 1);
+\layout Standard
-) not supported.
-\layout Itemize
+will still be recognized.
+\layout Subsection
-'double
-\begin_inset LatexCommand \index{double (not supported)}
+Peephole Optimizer
+\begin_inset LatexCommand \label{sub:Peephole-Optimizer}
\end_inset
-' precision floating point
-\begin_inset LatexCommand \index{Floating point support}
+
+\begin_inset LatexCommand \index{Peephole optimizer}
\end_inset
-not supported.
-\layout Itemize
-No support for setjmp
-\begin_inset LatexCommand \index{setjmp (not supported)}
+\layout Standard
-\end_inset
+The compiler uses a rule based, pattern matching and re-writing mechanism
+ for peep-hole optimization.
+ It is inspired by
+\emph on
+copt
+\emph default
+ a peep-hole optimizer by Christopher W.
+ Fraser (cwfraser@microsoft.com).
+ A default set of rules are compiled into the compiler, additional rules
+ may be added with the
+\emph on
+-
+\begin_inset ERT
+status Collapsed
- and longjmp
-\begin_inset LatexCommand \index{longjmp (not supported)}
+\layout Standard
+\backslash
+/
\end_inset
- (for now).
-\layout Itemize
-
-Old K&R style
-\begin_inset LatexCommand \index{K\&R style}
+-peep-file
+\begin_inset LatexCommand \index{-\/-peep-file}
\end_inset
- function declarations are NOT allowed.
-\begin_deeper
+ <filename>
+\emph default
+ option.
+ The rule language is best illustrated with examples.
\layout Verse
\family typewriter
-foo(i,j) /* this old style of function declarations */
-\newline
-int i,j; /* are valid in ANSI but not valid in SDCC */
+replace {
\newline
-{
+\SpecialChar ~
+\SpecialChar ~
+mov %1,a
\newline
\SpecialChar ~
\SpecialChar ~
+mov a,%1
+\newline
+} by {
+\newline
\SpecialChar ~
\SpecialChar ~
-...
-
+mov %1,a
\newline
}
-\end_deeper
-\layout Itemize
-
-functions declared as pointers
-\begin_inset LatexCommand \index{Pointer (to function)}
-
-\end_inset
-
+\layout Standard
-\begin_inset LatexCommand \index{function pointers}
+The above rule will change the following assembly
+\begin_inset LatexCommand \index{Assembler routines}
\end_inset
- must be dereferenced during the call.
-\begin_deeper
+ sequence:
\layout Verse
\family typewriter
-int (*foo)();
-\newline
-...
-
-\newline
-/* has to be called like this */
+mov r1,a
\newline
-(*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
-\end_deeper
-\layout Section
-
-Cyclomatic Complexity
-\begin_inset LatexCommand \index{Cyclomatic complexity}
+mov a,r1
+\layout Standard
-\end_inset
+to
+\layout Verse
+\family typewriter
+mov r1,a
\layout Standard
-Cyclomatic complexity of a function is defined as the number of independent
- paths the program can take during execution of the function.
- This is an important number since it defines the number test cases you
- have to generate to validate the function.
- The accepted industry standard for complexity number is 10, if the cyclomatic
- complexity reported by SDCC exceeds 10 you should think about simplification
- of the function logic.
- Note that the complexity level is not related to the number of lines of
- code in a function.
- Large functions can have low complexity, and small functions can have large
- complexity levels.
-
-\newline
+Note: All occurrences of a
+\emph on
+%n
+\emph default
+ (pattern variable) must denote the same string.
+ With the above rule, the assembly sequence:
+\layout Verse
-\newline
-SDCC uses the following formula to compute the complexity:
-\newline
+\family typewriter
+mov r1,a
+\newline
+mov a,r2
\layout Standard
-complexity = (number of edges in control flow graph) - (number of nodes
- in control flow graph) + 2;
+will remain unmodified.
\newline
\newline
-Having said that the industry standard is 10, you should be aware that in
- some cases it be may unavoidable to have a complexity level of less than
- 10.
- For example if you have switch statement with more than 10 case labels,
- each case label adds one to the complexity level.
- The complexity level is by no means an absolute measure of the algorithmic
- complexity of the function, it does however provide a good starting point
- for which functions you might look at for further optimization.
-\layout Section
-
-Notes on supported Processors
-\layout Subsection
-
-MCS51 variants
-\begin_inset LatexCommand \label{sub:MCS51-variants}
-
-\end_inset
-
-
-\begin_inset LatexCommand \index{MCS51 variants}
-
-\end_inset
-
-
-\layout Standard
-
-MCS51 processors are available from many vendors and come in many different
- flavours.
- While they might differ considerably in respect to Special Function Registers
- the core MCS51 is usually not modified or is kept compatible.
-
-\layout Subsubsection*
+Other special case optimizations may be added by the user (via
+\emph on
+-
+\begin_inset ERT
+status Collapsed
-pdata access by SFR
\layout Standard
-With the upcome of devices with internal xdata and flash memory devices
- using port P2
-\begin_inset LatexCommand \index{P2 (mcs51 sfr)}
-
-\end_inset
-
- as dedicated I/O port is becoming more popular.
- Switching the high byte for pdata
-\begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
-
-\end_inset
-
- access which was formerly done by port P2 is then achieved by a Special
- Function Register
-\begin_inset LatexCommand \index{sfr}
-
+\backslash
+/
\end_inset
-.
- In well-established MCS51 tradition the address of this
-\emph on
-sfr
+-peep-file option
\emph default
- is where the chip designers decided to put it.
- Needless to say that they didn't agree on a common name either.
- As pdata addressing is used in the startup code for the initialization
- of xdata variables a separate startup code should be used as described
- in section
-\begin_inset LatexCommand \ref{sub:Startup-Code}
-
-\end_inset
-
+).
+ E.g.
+ some variants of the 8051 MCU allow only
+\family typewriter
+ajmp
+\family default
+ and
+\family typewriter
+acall
+\family default
.
-\layout Subsubsection*
-
-Other Features available by SFR
-\layout Standard
-
-Some MCS51 variants offer features like Double DPTR
-\begin_inset LatexCommand \index{DPTR}
-
-\end_inset
+ The following two rules will change all
+\family typewriter
+ljmp
+\family default
+ and
+\family typewriter
+lcall
+\family default
+ to
+\family typewriter
+ajmp
+\family default
+ and
+\family typewriter
+acall
+\layout Verse
-, multiple DPTR, decrementing DPTR, 16x16 Multiply.
- These are currently not used for the MCS51 port.
- If you absolutely need them you can fall back to inline assembly or submit
- a patch to SDCC.
-\layout Subsection
-The Z80 and gbz80 port
+\family typewriter
+replace { lcall %1 } by { acall %1 }
+\newline
+replace { ljmp %1 } by { ajmp %1 }
\layout Standard
-SDCC can target both the Zilog
-\begin_inset LatexCommand \index{Z80}
-
-\end_inset
-
- and the Nintendo Gameboy's Z80-like gbz80
-\begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
-
-\end_inset
-
-.
- The Z80 port is passed through the same
+The
\emph on
-regressions tests
-\begin_inset LatexCommand \index{Regression test}
+inline-assembler code
+\emph default
+ is also passed through the peep hole optimizer, thus the peephole optimizer
+ can also be used as an assembly level macro expander.
+ The rules themselves are MCU dependent whereas the rule language infra-structur
+e is MCU independent.
+ Peephole optimization rules for other MCU can be easily programmed using
+ the rule language.
+\newline
-\end_inset
+\newline
+The syntax for a rule is as follows:
+\layout Verse
-\emph default
- as the MCS51 and DS390 ports, so floating point support, support for long
- variables and bitfield support is fine.
- See mailing lists and forums about interrupt routines.
+\family typewriter
+rule := replace [ restart ] '{' <assembly sequence> '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' by '{' '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ <assembly sequence> '
+\backslash
+n'
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ '}' [if <functionName> ] '
+\backslash
+n'
\layout Standard
-As always, the code is the authoritative reference - see z80/ralloc.c and
- z80/gen.c.
- The stack
-\begin_inset LatexCommand \index{stack}
-
-\end_inset
-
- frame is similar to that generated by the IAR Z80 compiler.
- IX is used as the base pointer, HL is used as a temporary register, and
- BC and DE are available for holding variables.
- IY is currently unused.
- Return values
-\begin_inset LatexCommand \index{return value}
+<assembly sequence> := assembly instruction (each instruction including
+ labels must be on a separate line).
+\newline
-\end_inset
+\newline
+The optimizer will apply to the rules one by one from the top in the sequence
+ of their appearance, it will terminate when all rules are exhausted.
+ If the 'restart' option is specified, then the optimizer will start matching
+ the rules again from the top, this option for a rule is expensive (performance)
+, it is intended to be used in situations where a transformation will trigger
+ the same rule again.
+ An example of this (not a good one, it has side effects) is the following
+ rule:
+\layout Verse
- are stored in HL.
- One bad side effect of using IX as the base pointer is that a functions
- stack frame is limited to 127 bytes - this will be fixed in a later version.
-\layout Subsection
-The HC08 port
+\family typewriter
+replace restart {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+pop %1
+\newline
+\SpecialChar ~
+\SpecialChar ~
+push %1 } by {
+\newline
+\SpecialChar ~
+\SpecialChar ~
+; nop
+\newline
+}
\layout Standard
-The port to the Motorola HC08
-\begin_inset LatexCommand \index{HC08}
-
-\end_inset
+Note that the replace pattern cannot be a blank, but can be a comment line.
+ Without the 'restart' option only the innermost 'pop' 'push' pair would
+ be eliminated, i.e.:
+\layout Verse
- family has been added in October 2003, thank you Erik!
-\layout Subsection
-The PIC14 port
+\family typewriter
+pop ar1
+\newline
+pop ar2
+\newline
+push ar2
+\newline
+push ar1
\layout Standard
-The 14bit PIC
-\begin_inset LatexCommand \index{PIC14}
+would result in:
+\layout Verse
-\end_inset
- port still requires a major effort from the development community.
- However it can work for very simple code.
+\family typewriter
+pop ar1
\newline
-
+; nop
\newline
+push ar1
+\layout Standard
-\bar under
-C code and 14bit PIC code page
-\begin_inset LatexCommand \index{code page (pic14)}
-\end_inset
+\emph on
+with
+\emph default
+ the restart option the rule will be applied again to the resulting code
+ and then all the pop-push pairs will be eliminated to yield:
+\layout Verse
- and RAM banks
-\bar default
-\begin_inset LatexCommand \index{RAM bank (pic14)}
+\family typewriter
+; nop
+\newline
+; nop
+\layout Standard
-\end_inset
+A conditional function can be attached to a rule.
+ Attaching rules are somewhat more involved, let me illustrate this with
+ an example.
+\layout Verse
+\family typewriter
+replace {
\newline
-The linker organizes allocation for the code page and RAM banks.
- It does not have intimate knowledge of the code flow.
- It will put all the code section of a single asm file into a single code
- page.
- In order to make use of multiple code pages, separate asm files must be
- used.
- The compiler treats all functions of a single C file as being in the same
- code page unless it is non static.
- The compiler treats all local variables of a single C file as being in
- the same RAM bank unless it is an extern.
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+ljmp %5
\newline
-
+%2:
\newline
-To get the best follow these guide lines:
-\layout Enumerate
-
-make local functions static, as non static functions require code page selection
- overhead.
-\layout Enumerate
+} by {
+\newline
+\SpecialChar ~
+ \SpecialChar ~
+ \SpecialChar ~
+sjmp %5
+\newline
+%2:
+\newline
+} if labelInRange
+\layout Standard
-Make local variables static as extern variables require RAM bank selection
- overhead.
-\layout Enumerate
+The optimizer does a look-up of a function name table defined in function
+
+\emph on
+callFuncByName
+\emph default
+ in the source file SDCCpeeph.c, with the name
+\emph on
+labelInRange
+\emph default
+.
+ If it finds a corresponding entry the function is called.
+ Note there can be no parameters specified for these functions, in this
+ case the use of
+\emph on
+%5
+\emph default
+ is crucial, since the function
+\emph on
+labelInRange
+\emph default
+ expects to find the label in that particular variable (the hash table containin
+g the variable bindings is passed as a parameter).
+ If you want to code more such functions, take a close look at the function
+ labelInRange and the calling mechanism in source file SDCCpeeph.c.
+ Currently implemented are
+\emph on
+labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
+ 24bitMode, portIsDS390, 24bitModeAndPortDS390
+\emph default
+and
+\emph on
+ notVolatile
+\emph default
+.
+\layout Standard
+
+I know this whole thing is a little kludgey, but maybe some day we will
+ have some better means.
+ If you are looking at this file, you will see the default rules that are
+ compiled into the compiler, you can add your own rules in the default set
+ there if you get tired of specifying the -
+\begin_inset ERT
+status Collapsed
-For devices that have multiple code pages it is more efficient to use the
- same number of files as pages, i.e.
- for the 16F877 use 4 separate files and i.e.
- for the 16F874 use 2 separate files.
- This way the linker can put the code for each file into different code
- pages and the compiler can allocate reusable variables more efficiently
- and there's less page selection overhead.
- And as for any 8 bit micro (especially for PIC 14 as they have a very simple
- instruction set) use 'unsigned char' whereever possible instead of 'int'.
\layout Standard
+\backslash
+/
+\end_inset
-\bar under
-Creating a device include file
-\bar default
+-peep-file option.
+\layout Section
-\newline
-For generating a device include file use the support perl script inc2h.pl
- kept in directory support/script.
-\newline
+ANSI-Compliance
+\begin_inset LatexCommand \index{ANSI-compliance}
-\newline
+\end_inset
-\bar under
-Interrupt code
-\bar default
-\newline
-For the interrupt function, use the keyword 'interrupt'
-\begin_inset LatexCommand \index{interrupt}
+\begin_inset LatexCommand \label{sub:ANSI-Compliance}
\end_inset
- with level number of 0 (PIC14 only has 1 interrupt so this number is only
- there to avoid a syntax error - it ought to be fixed).
- E.g.:
-\layout Verse
-
-\family typewriter
-void Intr(void) interrupt 0
-\newline
-{
-\newline
-\SpecialChar ~
-\SpecialChar ~
-T0IF = 0; /* Clear timer interrupt */
-\newline
-}
\layout Standard
+Deviations from the compliance:
+\layout Itemize
-\bar under
-Linking and assembling
-\bar default
-
-\newline
-For assembling you can use either GPUTILS'
-\begin_inset LatexCommand \index{gputils (pic tools)}
+functions are not always reentrant
+\begin_inset LatexCommand \index{reentrant}
\end_inset
- gpasm.exe or MPLAB's mpasmwin.exe.
- For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
- If you use MPLAB and an interrupt function then the linker script file
- vectors section will need to be enlarged to link with mplink.
-\newline
+.
+\layout Itemize
-\newline
-Here is a
-\family typewriter
-Makefile
-\family default
- using GPUTILS:
+structures cannot be assigned values directly, cannot be passed as function
+ parameters or assigned to each other and cannot be a return value from
+ a function, e.g.:
+\begin_deeper
\layout Verse
\family typewriter
-.c.o:
+struct s { ...
+ };
+\newline
+struct s s1, s2;
+\newline
+foo()
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-sdcc -S -V -mpic14 -p16F877 $<
+s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
+}
+\newline
+struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
+ */
+\newline
+{
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-gpasm -c $*.asm
-\newline
-
-\newline
-$(PRJ).hex: $(OBJS)
+struct s rets;
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
+...
+
+\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
-\layout Standard
+return rets;/* is invalid in SDCC although allowed in ANSI */
+\newline
+}
+\end_deeper
+\layout Itemize
-Here is a
-\family typewriter
-Makefile
-\family default
- using MPLAB:
+'long long
+\begin_inset LatexCommand \index{long long (not supported)}
+
+\end_inset
+
+' (64 bit integers
+\begin_inset LatexCommand \index{int (64 bit) (not supported)}
+
+\end_inset
+
+) not supported.
+\layout Itemize
+
+'double
+\begin_inset LatexCommand \index{double (not supported)}
+
+\end_inset
+
+' precision floating point
+\begin_inset LatexCommand \index{Floating point support}
+
+\end_inset
+
+not supported.
+\layout Itemize
+
+No support for setjmp
+\begin_inset LatexCommand \index{setjmp (not supported)}
+
+\end_inset
+
+ and longjmp
+\begin_inset LatexCommand \index{longjmp (not supported)}
+
+\end_inset
+
+ (for now).
+\layout Itemize
+
+Old K&R style
+\begin_inset LatexCommand \index{K\&R style}
+
+\end_inset
+
+ function declarations are NOT allowed.
+\begin_deeper
\layout Verse
\family typewriter
-.c.o:
+foo(i,j) /* this old style of function declarations */
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-sdcc -S -V -mpic14 -p16F877 $<
+int i,j; /* are valid in ANSI but not valid in SDCC */
+\newline
+{
\newline
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mpasmwin /q /o $*.asm
+...
+
\newline
+}
+\end_deeper
+\layout Itemize
+
+functions declared as pointers
+\begin_inset LatexCommand \index{Pointer (to function)}
+
+\end_inset
+
+
+\begin_inset LatexCommand \index{function pointers}
+
+\end_inset
+ must be dereferenced during the call.
+\begin_deeper
+\layout Verse
+
+
+\family typewriter
+int (*foo)();
\newline
-$(PRJ).hex: $(OBJS)
+...
+
\newline
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-\SpecialChar ~
-mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
-\layout Subsection
+/* has to be called like this */
+\newline
+(*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
+\end_deeper
+\layout Section
-The PIC16
-\begin_inset LatexCommand \index{PIC16}
+Cyclomatic Complexity
+\begin_inset LatexCommand \index{Cyclomatic complexity}
\end_inset
- port
+
+\layout Standard
+
+Cyclomatic complexity of a function is defined as the number of independent
+ paths the program can take during execution of the function.
+ This is an important number since it defines the number test cases you
+ have to generate to validate the function.
+ The accepted industry standard for complexity number is 10, if the cyclomatic
+ complexity reported by SDCC exceeds 10 you should think about simplification
+ of the function logic.
+ Note that the complexity level is not related to the number of lines of
+ code in a function.
+ Large functions can have low complexity, and small functions can have large
+ complexity levels.
+
+\newline
+
+\newline
+SDCC uses the following formula to compute the complexity:
+\newline
+
\layout Standard
-You'll find some additional notes about this port in the file src/pic16/NOTES.
+complexity = (number of edges in control flow graph) - (number of nodes
+ in control flow graph) + 2;
+\newline
+
+\newline
+Having said that the industry standard is 10, you should be aware that in
+ some cases it be may unavoidable to have a complexity level of less than
+ 10.
+ For example if you have switch statement with more than 10 case labels,
+ each case label adds one to the complexity level.
+ The complexity level is by no means an absolute measure of the algorithmic
+ complexity of the function, it does however provide a good starting point
+ for which functions you might look at for further optimization.
\layout Section
Retargetting for other Processors
projects / fw / sdcc / commitdiff