From: bernhardheld Date: Mon, 16 Feb 2004 21:16:36 +0000 (+0000) Subject: doc/sdccman.lyx: added Vangelis' contribution X-Git-Url: https://git.gag.com/?a=commitdiff_plain;h=3b792e25990c9e62061484dac0ba369c00923b6a;p=fw%2Fsdcc doc/sdccman.lyx: added Vangelis' contribution git-svn-id: https://sdcc.svn.sourceforge.net/svnroot/sdcc/trunk/sdcc@3201 4a8a32a2-be11-0410-ad9d-d568d2c75423 --- diff --git a/ChangeLog b/ChangeLog index 642e41de..5f905362 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +2004-02-16 Bernhard Held + + * doc/sdccman.lyx: added Vangelis' contribution + 2004-02-16 Erik Petrich * src/SDCClrange.c (rlivePoint): live range of SEND operand should diff --git a/doc/sdccman.lyx b/doc/sdccman.lyx index 27bff0f0..bbd5d414 100644 --- a/doc/sdccman.lyx +++ b/doc/sdccman.lyx @@ -1718,10 +1718,10 @@ Install paths \begin_inset Tabular - - - - + + + + \begin_inset Text @@ -14137,427 +14137,261 @@ when \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{.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{.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= 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 - change to the . -\layout Itemize +The PIC14 port +\layout Standard --fullname - used by GUI front ends. -\layout Itemize +The 14bit PIC +\begin_inset LatexCommand \index{PIC14} --cpu - this argument is passed to the simulator please see the - simulator docs for details. -\layout Itemize +\end_inset --X 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 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 passed to simulator see the simulator docs for details. -\layout Itemize +\end_inset --k 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 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 - (/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 ~ @@ -14566,15 +14400,22 @@ The following is a list of key mapping for the debugger interface. \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 ~ @@ -14583,6 +14424,20 @@ binding\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 ~ @@ -14591,11 +14446,1274 @@ binding\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 .d file with debugging + information. + 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 + + + + + + +\begin_inset Text + +\layout Standard + +Macro +\end_inset + + +\begin_inset Text + +\layout Standard + +Description +\end_inset + + + + +\begin_inset Text + +\layout Standard + +pic18fxxxx +\end_inset + + +\begin_inset Text + +\layout Standard + +MCU Identification. + +\emph on +xxxx +\emph default + is the microcontrol identification number, i.e. + 452, 6620, etc +\end_inset + + + + +\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 + + + + + + + + +\begin_inset Text + +\layout Standard + +Directory +\end_inset + + +\begin_inset Text + +\layout Standard + +Description +\end_inset + + +\begin_inset Text + +\layout Standard + +Target +\end_inset + + +\begin_inset Text + +\layout Standard + +Command prefix +\end_inset + + + + +\begin_inset Text + +\layout Standard + +PREFIX/sdcc/include/pic16 +\end_inset + + +\begin_inset Text + +\layout Standard + +PIC16 specific headers +\end_inset + + +\begin_inset Text + +\layout Standard + +Compiler +\end_inset + + +\begin_inset Text + +\layout Standard + +-I +\end_inset + + + + +\begin_inset Text + +\layout Standard + +PREFIX/sdcc/lib/pic16 +\end_inset + + +\begin_inset Text + +\layout Standard + +PIC16 specific libraries +\end_inset + + +\begin_inset Text + +\layout Standard + +Linker +\end_inset + + +\begin_inset Text + +\layout Standard + +-L +\end_inset + + + + +\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 +\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 + + + + + + + +\begin_inset Text + +\layout Standard + +Stack & Frame pointer sizes according to stack model +\end_inset + + +\begin_inset Text + +\layout Standard + +small +\end_inset + + +\begin_inset Text + +\layout Standard + +large +\end_inset + + + + +\begin_inset Text + +\layout Standard + +Stack pointer FSR1 +\end_inset + + +\begin_inset Text + +\layout Standard + +8-bits +\end_inset + + +\begin_inset Text + +\layout Standard + +16-bits +\end_inset + + + + +\begin_inset Text + +\layout Standard + +Frame pointer FSR2 +\end_inset + + +\begin_inset Text + +\layout Standard + +8-bits +\end_inset + + +\begin_inset Text + +\layout Standard + +16-bits +\end_inset + + + + +\end_inset + + +\layout Subsection + +Pointers +\layout Standard +\align center + +\begin_inset Tabular + + + + + + + +\begin_inset Text + +\layout Standard + +Pointer sizes according to memory model +\end_inset + + +\begin_inset Text + +\layout Standard + +small model +\end_inset + + +\begin_inset Text + +\layout Standard + +large model +\end_inset + + + + +\begin_inset Text + +\layout Standard + +code pointers +\end_inset + + +\begin_inset Text + +\layout Standard + +16-bits +\end_inset + + +\begin_inset Text + +\layout Standard + +24-bits +\end_inset + + + + +\begin_inset Text + +\layout Standard + +data pointers +\end_inset + + +\begin_inset Text + +\layout Standard + +16-bits +\end_inset + + +\begin_inset Text + +\layout Standard + +24-bits +\end_inset + + + + +\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{.cdb} + +\end_inset + + file from the .adb +\begin_inset LatexCommand \index{.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= 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 - change to the . +\layout Itemize + +-fullname - used by GUI front ends. +\layout Itemize + +-cpu - this argument is passed to the simulator please see the + simulator docs for details. +\layout Itemize + +-X this options is passed to the simulator please see + the simulator docs for details. +\layout Itemize + +-s passed to simulator see the simulator docs for details. +\layout Itemize + +-S passed to simulator see the simulator docs for details. +\layout Itemize + +-k 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 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 + (/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 ~ @@ -15836,270 +16954,25 @@ Linker \bar no \noun off \color none -sdcc/bin -\end_inset - - - - -\begin_inset Text - -\layout Standard - -packihx -\end_inset - - -\begin_inset Text - -\layout Standard - -ihx packer -\end_inset - - -\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 - - - - -\end_inset - - -\newline - -\layout Section - -Documentation -\begin_inset LatexCommand \index{Documentation} - -\end_inset - - included in the distribution -\layout Standard -\align center - -\begin_inset Tabular - - - - - - -\begin_inset Text - -\layout Standard - -Subject / Title -\end_inset - - -\begin_inset Text - -\layout Standard - -Where to get / filename -\end_inset - - - - -\begin_inset Text - -\layout Standard - -SDCC Compiler User Guide -\end_inset - - -\begin_inset Text - -\layout Standard - -You're reading it right now -\end_inset - - - - -\begin_inset Text - -\layout Standard - -Changelog of SDCC -\end_inset - - -\begin_inset Text - -\layout Standard - -sdcc/Changelog -\end_inset - - - - -\begin_inset Text - -\layout Standard - -ASXXXX Assemblers and ASLINK Relocating Linker -\end_inset - - -\begin_inset Text - -\layout Standard - -sdcc/as/doc/asxhtm.html -\end_inset - - - - -\begin_inset Text - -\layout Standard - -SDCC regression test -\begin_inset LatexCommand \index{Regression test} - -\end_inset - - -\end_inset - - -\begin_inset Text - -\layout Standard - -sdcc/doc/test_suite_spec.pdf -\end_inset - - - - -\begin_inset Text - -\layout Standard - -Various notes -\end_inset - - -\begin_inset Text - -\layout Standard - -sdcc/doc/* -\end_inset - - - - -\begin_inset Text - -\layout Standard - -Notes on debugging with sdcdb -\begin_inset LatexCommand \index{sdcdb (debugger)} - -\end_inset - - -\end_inset - - -\begin_inset Text - -\layout Standard - -sdcc/debugger/README -\end_inset - - - - -\begin_inset Text - -\layout Standard - -Software simulator for microcontrollers -\end_inset - - -\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 - + \begin_inset Text \layout Standard -Temporary notes on the pic16 -\begin_inset LatexCommand \index{PIC16} - -\end_inset - - port -\end_inset - - -\begin_inset Text - -\layout Standard - -sdcc/src/pic16/NOTES +packihx \end_inset - - \begin_inset Text \layout Standard -SDCC internal documentation (debugging file format) +ihx packer \end_inset @@ -16107,7 +16980,7 @@ SDCC internal documentation (debugging file format) \layout Standard -sdcc/doc/ + \family roman \series medium \shape up @@ -16116,16 +16989,7 @@ sdcc/doc/ \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 @@ -16138,36 +17002,27 @@ f \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 - + - - - + + \begin_inset Text \layout Standard -Name -\end_inset - - -\begin_inset Text - -\layout Standard - -Purpose +Subject / Title \end_inset @@ -16175,7 +17030,7 @@ Purpose \layout Standard -Where to get +Where to get / filename \end_inset @@ -16185,20 +17040,25 @@ Where to get \layout Standard -gpsim -\begin_inset LatexCommand \index{gpsim (pic simulator)} - +SDCC Compiler User Guide \end_inset + + +\begin_inset Text +\layout Standard +You're reading it right now \end_inset + + \begin_inset Text \layout Standard -PIC simulator +Changelog of SDCC \end_inset @@ -16206,12 +17066,7 @@ PIC simulator \layout Standard - -\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html} - -\end_inset - - +sdcc/Changelog \end_inset @@ -16221,51 +17076,48 @@ PIC simulator \layout Standard -gputils -\begin_inset LatexCommand \index{gputils (pic tools)} - -\end_inset - - +ASXXXX Assemblers and ASLINK Relocating Linker \end_inset - + \begin_inset Text \layout Standard -GNU PIC utilities +sdcc/as/doc/asxhtm.html \end_inset - + + + \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 - - - + \begin_inset Text \layout Standard -flP5 +sdcc/doc/test_suite_spec.pdf \end_inset + + \begin_inset Text \layout Standard -PIC programmer +Various notes \end_inset @@ -16273,12 +17125,7 @@ PIC programmer \layout Standard - -\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html} - -\end_inset - - +sdcc/doc/* \end_inset @@ -16288,20 +17135,12 @@ PIC programmer \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 - - -\begin_inset Text -\layout Standard -Formats C source - Master of the white spaces \end_inset @@ -16309,12 +17148,7 @@ Formats C source - Master of the white spaces \layout Standard - -\begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html} - -\end_inset - - +sdcc/debugger/README \end_inset @@ -16324,20 +17158,7 @@ Formats C source - Master of the white spaces \layout Standard -srecord -\begin_inset LatexCommand \index{srecord (tool)} - -\end_inset - - -\end_inset - - -\begin_inset Text - -\layout Standard - -Object file conversion, checksumming, ... +Software simulator for microcontrollers \end_inset @@ -16346,11 +17167,24 @@ Object file conversion, checksumming, ... \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 @@ -16360,20 +17194,12 @@ Object file conversion, checksumming, ... \layout Standard -objdump -\begin_inset LatexCommand \index{objdump (tool)} - -\end_inset - +Temporary notes on the pic16 +\begin_inset LatexCommand \index{PIC16} \end_inset - - -\begin_inset Text - -\layout Standard -Object file conversion, ... + port \end_inset @@ -16381,53 +17207,77 @@ Object file conversion, ... \layout Standard -Part of binutils (should be there anyway) +sdcc/src/pic16/NOTES \end_inset - + \begin_inset Text \layout Standard -doxygen -\begin_inset LatexCommand \index{doxygen (source documentation tool)} - -\end_inset - - +SDCC internal documentation (debugging file format) \end_inset - + \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 - -\begin_inset Text + + -\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 - - - + + +\layout Standard +\align center + +\begin_inset Tabular + + + + + + \begin_inset Text \layout Standard -kdevelop +Name \end_inset @@ -16435,7 +17285,7 @@ kdevelop \layout Standard -IDE (has anyone tried integrating SDCC & sdcdb? Unix only) +Purpose \end_inset @@ -16443,12 +17293,7 @@ IDE (has anyone tried integrating SDCC & sdcdb? Unix only) \layout Standard - -\begin_inset LatexCommand \url{http://www.kdevelop.org} - -\end_inset - - +Where to get \end_inset @@ -16458,8 +17303,8 @@ IDE (has anyone tried integrating SDCC & sdcdb? Unix only) \layout Standard -splint -\begin_inset LatexCommand \index{splint (syntax checking tool)} +gpsim +\begin_inset LatexCommand \index{gpsim (pic simulator)} \end_inset @@ -16471,7 +17316,7 @@ splint \layout Standard -Statically checks c sources +PIC simulator \end_inset @@ -16480,7 +17325,7 @@ Statically checks c sources \layout Standard -\begin_inset LatexCommand \url{http://www.splint.org} +\begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html} \end_inset @@ -16488,14 +17333,14 @@ Statically checks c sources \end_inset - + \begin_inset Text \layout Standard -ddd -\begin_inset LatexCommand \index{ddd (debugger)} +gputils +\begin_inset LatexCommand \index{gputils (pic tools)} \end_inset @@ -16507,12 +17352,7 @@ ddd \layout Standard -Debugger, serves nicely as GUI to sdcdb -\begin_inset LatexCommand \index{sdcdb (debugger)} - -\end_inset - - (Unix only) +GNU PIC utilities \end_inset @@ -16521,7 +17361,7 @@ Debugger, serves nicely as GUI to sdcdb \layout Standard -\begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/} +\begin_inset LatexCommand \url{http://gputils.sourceforge.net/} \end_inset @@ -16529,32 +17369,13 @@ Debugger, serves nicely as GUI to sdcdb \end_inset - - -\end_inset - - -\newline - -\layout Section - -Related documentation / recommended reading -\layout Standard -\align center - -\begin_inset Tabular - - - - - - + \begin_inset Text \layout Standard -Name +flP5 \end_inset @@ -16562,7 +17383,7 @@ Name \layout Standard -Subject / Title +PIC programmer \end_inset @@ -16570,7 +17391,12 @@ Subject / Title \layout Standard -Where to get + +\begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html} + +\end_inset + + \end_inset @@ -16580,16 +17406,12 @@ Where to get \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 @@ -16597,12 +17419,7 @@ c-refcard.pdf \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 @@ -16611,7 +17428,7 @@ C Reference Card \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 @@ -16625,7 +17442,12 @@ C Reference Card \layout Standard -c-faq +srecord +\begin_inset LatexCommand \index{srecord (tool)} + +\end_inset + + \end_inset @@ -16633,7 +17455,7 @@ c-faq \layout Standard -C-FAQ-list +Object file conversion, checksumming, ... \end_inset @@ -16642,7 +17464,7 @@ C-FAQ-list \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 @@ -16656,6 +17478,12 @@ C-FAQ-list \layout Standard +objdump +\begin_inset LatexCommand \index{objdump (tool)} + +\end_inset + + \end_inset @@ -16663,7 +17491,7 @@ C-FAQ-list \layout Standard -Latest datasheet of the target CPU +Object file conversion, ... \end_inset @@ -16671,7 +17499,7 @@ Latest datasheet of the target CPU \layout Standard -vendor +Part of binutils (should be there anyway) \end_inset @@ -16681,6 +17509,12 @@ vendor \layout Standard +doxygen +\begin_inset LatexCommand \index{doxygen (source documentation tool)} + +\end_inset + + \end_inset @@ -16688,7 +17522,7 @@ vendor \layout Standard -Revision history of datasheet +Source code documentation system \end_inset @@ -16696,19 +17530,22 @@ Revision history of datasheet \layout Standard -vendor + +\begin_inset LatexCommand \url{http://www.doxygen.org} + +\end_inset + + \end_inset - + \begin_inset Text \layout Standard -S. - S. - Muchnick +kdevelop \end_inset @@ -16716,7 +17553,7 @@ S. \layout Standard -Advanced Compiler Design and Implementation +IDE (has anyone tried integrating SDCC & sdcdb? Unix only) \end_inset @@ -16724,1704 +17561,1342 @@ Advanced Compiler Design and Implementation \layout Standard -bookstore (very dedicated, probably read other books first) -\end_inset - - - - -\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 + + + + +\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 + + +\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 + + +\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 + + + + +\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 + + +\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 + + +\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 + + + - 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 + + + + + + + +\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 + + +\begin_inset Text -. -\layout Section - -Requesting Features -\begin_inset LatexCommand \label{sub:Requesting-Features} +\layout Standard +Subject / Title \end_inset + + +\begin_inset Text +\layout Standard -\begin_inset LatexCommand \index{Feature request} - +Where to get \end_inset + + + + +\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 - + + +\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 + + +\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 + + + + +\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 + + +\begin_inset Text -diff -Naur unmodified_directory modified_directory >my_changes.patch -\begin_inset Quotes srd +\layout Standard + +C-FAQ-list \end_inset + + +\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 + + + + +\begin_inset Text +\layout Standard -\series default - -\family default -will do. -\layout Section +\end_inset + + +\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 + + +\begin_inset Text + +\layout Standard +vendor \end_inset + + + + +\begin_inset Text +\layout Standard -\begin_inset Foot -collapsed false +\end_inset + + +\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 + + +\begin_inset Text - and the -\begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599} +\layout Standard +vendor \end_inset + + + + +\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 + + +\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 + + +\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} + + + \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( = ; [< | <=] ; [++ | - += 1]) -\newline -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ -\SpecialChar ~ - -\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 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 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( = ; [< | <=] ; [++ | + += 1]) \newline -rl\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ -a -\newline -mov\SpecialChar ~ \SpecialChar ~ -_i,a -\layout Standard +\SpecialChar ~ + +\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 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 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 ~ @@ -18444,13 +18919,16 @@ will generate the following code: \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 ~ @@ -18462,7 +18940,6 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 62\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -18470,14 +18947,21 @@ will generate the following code: \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 ~ @@ -18492,7 +18976,6 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 63\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -18500,15 +18983,16 @@ will generate the following code: \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 ~ @@ -18520,7 +19004,6 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 64\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -18528,11 +19011,17 @@ will generate the following code: \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 ~ @@ -18547,7 +19036,6 @@ will generate the following code: \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ - 65\SpecialChar ~ \SpecialChar ~ \SpecialChar ~ \SpecialChar ~ @@ -18555,467 +19043,478 @@ will generate the following code: \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 - - -\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 ] '{' ' -\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 ~ - ' -\backslash -n' -\newline -\SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - \SpecialChar ~ - '}' [if ] ' -\backslash -n' +Bit-shifting Operations +\begin_inset LatexCommand \index{Bit shifting} + +\end_inset + +. \layout Standard - := 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 ~ ... @@ -19023,542 +19522,801 @@ foo() \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 + +\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 ] '{' ' +\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 ~ + ' +\backslash +n' +\newline +\SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + \SpecialChar ~ + '}' [if ] ' +\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 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