git.gag.com Git - fw/sdcc/blob - doc/SDCCUdoc.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2
   3 <!--Converted with LaTeX2HTML 2K.1beta (1.47)
   4 original version by:  Nikos Drakos, CBLU, University of Leeds
   5 * revised and updated by:  Marcus Hennecke, Ross Moore, Herb Swan
   6 * with significant contributions from:
   7   Jens Lippmann, Marek Rouchal, Martin Wilck and others -->
   8 <HTML>
   9 <HEAD>
  10 <TITLE>SDCC Compiler User Guide</TITLE>
  11 <META NAME="description" CONTENT="SDCC Compiler User Guide">
  12 <META NAME="keywords" CONTENT="SDCCUdoc">
  13 <META NAME="resource-type" CONTENT="document">
  14 <META NAME="distribution" CONTENT="global">
  15
  16 <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
  17 <META NAME="Generator" CONTENT="LaTeX2HTML v2K.1beta">
  18 <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
  19
  20 <LINK REL="STYLESHEET" HREF="SDCCUdoc.css">
  21
  22 </HEAD>
  23
  24 <BODY >
  25 <!--Navigation Panel-->
  26 <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
  27  SRC="file:/usr/share/latex2html/icons/nx_grp_g.png">
  28 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
  29  SRC="file:/usr/share/latex2html/icons/up_g.png">
  30 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
  31  SRC="file:/usr/share/latex2html/icons/prev_g.png">
  32 <BR>
  33 <BR>
  34 <BR>
  35 <!--End of Navigation Panel-->
  36
  37 <P>
  38
  39 <P>
  40 <H1 ALIGN="CENTER">SDCC Compiler User Guide</H1>
  41 <BR>
  42
  43 <H2><A NAME="SECTION00010000000000000000">
  44 Contents</A>
  45 </H2>
  46 <!--Table of Contents-->
  47
  48 <UL>
  49 <LI><A NAME="tex2html120"
  50   HREF="SDCCUdoc.html">1 Introduction</A>
  51 <UL>
  52 <LI><A NAME="tex2html121"
  53   HREF="#SECTION00021000000000000000">1.1 About SDCC</A>
  54 <LI><A NAME="tex2html122"
  55   HREF="#SECTION00022000000000000000">1.2 Open Source</A>
  56 <LI><A NAME="tex2html123"
  57   HREF="#SECTION00023000000000000000">1.3 System Requirements</A>
  58 <LI><A NAME="tex2html124"
  59   HREF="#SECTION00024000000000000000">1.4 Other Resources</A>
  60 </UL>
  61 <BR>
  62 <LI><A NAME="tex2html125"
  63   HREF="#SECTION00030000000000000000">2 Installation</A>
  64 <UL>
  65 <LI><A NAME="tex2html126"
  66   HREF="#SECTION00031000000000000000">2.1 Linux/Unix Installation</A>
  67 <LI><A NAME="tex2html127"
  68   HREF="#SECTION00032000000000000000">2.2 Windows Installation</A>
  69 <LI><A NAME="tex2html128"
  70   HREF="#SECTION00033000000000000000">2.3 Testing out the SDCC Compiler</A>
  71 <LI><A NAME="tex2html129"
  72   HREF="#SECTION00034000000000000000">2.4 Install Trouble-shooting</A>
  73 <LI><A NAME="tex2html130"
  74   HREF="#SECTION00035000000000000000">2.5 Additional Information for Windows Users</A>
  75 <LI><A NAME="tex2html131"
  76   HREF="#SECTION00036000000000000000">2.6 SDCC on Other Platforms</A>
  77 <LI><A NAME="tex2html132"
  78   HREF="#SECTION00037000000000000000">2.7 Advanced Install Options</A>
  79 <LI><A NAME="tex2html133"
  80   HREF="#SECTION00038000000000000000">2.8 Components of SDCC</A>
  81 </UL>
  82 <BR>
  83 <LI><A NAME="tex2html134"
  84   HREF="#SECTION00040000000000000000">3 Using SDCC</A>
  85 <UL>
  86 <LI><A NAME="tex2html135"
  87   HREF="#SECTION00041000000000000000">3.1 Compiling</A>
  88 <LI><A NAME="tex2html136"
  89   HREF="#SECTION00042000000000000000">3.2 Command Line Options</A>
  90 <LI><A NAME="tex2html137"
  91   HREF="#SECTION00043000000000000000">3.3 MCS51/DS390 Storage Class Language Extensions</A>
  92 <LI><A NAME="tex2html138"
  93   HREF="#SECTION00044000000000000000">3.4 Pointers</A>
  94 <LI><A NAME="tex2html139"
  95   HREF="#SECTION00045000000000000000">3.5 Parameters &amp; Local Variables</A>
  96 <LI><A NAME="tex2html140"
  97   HREF="#SECTION00046000000000000000">3.6 Overlaying</A>
  98 <LI><A NAME="tex2html141"
  99   HREF="#SECTION00047000000000000000">3.7 Interrupt Service Routines</A>
 100 <LI><A NAME="tex2html142"
 101   HREF="#SECTION00048000000000000000">3.8 Critical Functions</A>
 102 <LI><A NAME="tex2html143"
 103   HREF="#SECTION00049000000000000000">3.9 Naked Functions</A>
 104 <LI><A NAME="tex2html144"
 105   HREF="#SECTION000410000000000000000">3.10 Functions using private banks</A>
 106 <LI><A NAME="tex2html145"
 107   HREF="#SECTION000411000000000000000">3.11 Absolute Addressing</A>
 108 <LI><A NAME="tex2html146"
 109   HREF="#SECTION000412000000000000000">3.12 Startup Code</A>
 110 <LI><A NAME="tex2html147"
 111   HREF="#SECTION000413000000000000000">3.13 Inline Assembler Code</A>
 112 <LI><A NAME="tex2html148"
 113   HREF="#SECTION000414000000000000000">3.14 int(16 bit) and long (32 bit ) Support</A>
 114 <LI><A NAME="tex2html149"
 115   HREF="#SECTION000415000000000000000">3.15 Floating Point Support</A>
 116 <LI><A NAME="tex2html150"
 117   HREF="#SECTION000416000000000000000">3.16 MCS51 Memory Models</A>
 118 <LI><A NAME="tex2html151"
 119   HREF="#SECTION000417000000000000000">3.17 Flat 24 bit Addressing Model</A>
 120 <LI><A NAME="tex2html152"
 121   HREF="#SECTION000418000000000000000">3.18 Defines Created by the Compiler</A>
 122 </UL>
 123 <BR>
 124 <LI><A NAME="tex2html153"
 125   HREF="#SECTION00050000000000000000">4 SDCC Technical Data</A>
 126 <UL>
 127 <LI><A NAME="tex2html154"
 128   HREF="#SECTION00051000000000000000">4.1 Optimizations</A>
 129 <LI><A NAME="tex2html155"
 130   HREF="#SECTION00052000000000000000">4.2 Pragmas</A>
 131 <LI><A NAME="tex2html156"
 132   HREF="#SECTION00053000000000000000">4.3 Library Routines</A>
 133 <LI><A NAME="tex2html157"
 134   HREF="#SECTION00054000000000000000">4.4 Interfacing with Assembly Routines</A>
 135 <LI><A NAME="tex2html158"
 136   HREF="#SECTION00055000000000000000">4.5 Global Registers used for Parameter Passing</A>
 137 <LI><A NAME="tex2html159"
 138   HREF="#SECTION00056000000000000000">4.6 External Stack</A>
 139 <LI><A NAME="tex2html160"
 140   HREF="#SECTION00057000000000000000">4.7 ANSI-Compliance</A>
 141 <LI><A NAME="tex2html161"
 142   HREF="#SECTION00058000000000000000">4.8 Cyclomatic Complexity</A>
 143 </UL>
 144 <BR>
 145 <LI><A NAME="tex2html162"
 146   HREF="#SECTION00060000000000000000">5 TIPS</A>
 147 <LI><A NAME="tex2html163"
 148   HREF="#SECTION00070000000000000000">6 Retargetting for other MCUs.</A>
 149 <LI><A NAME="tex2html164"
 150   HREF="#SECTION00080000000000000000">7 SDCDB - Source Level Debugger</A>
 151 <UL>
 152 <LI><A NAME="tex2html165"
 153   HREF="#SECTION00081000000000000000">7.1 Compiling for Debugging</A>
 154 <LI><A NAME="tex2html166"
 155   HREF="#SECTION00082000000000000000">7.2 How the Debugger Works</A>
 156 <LI><A NAME="tex2html167"
 157   HREF="#SECTION00083000000000000000">7.3 Starting the Debugger</A>
 158 <LI><A NAME="tex2html168"
 159   HREF="#SECTION00084000000000000000">7.4 Command Line Options.</A>
 160 <LI><A NAME="tex2html169"
 161   HREF="#SECTION00085000000000000000">7.5 Debugger Commands.</A>
 162 <LI><A NAME="tex2html170"
 163   HREF="#SECTION00086000000000000000">7.6 Interfacing with XEmacs.</A>
 164 </UL>
 165 <BR>
 166 <LI><A NAME="tex2html171"
 167   HREF="#SECTION00090000000000000000">8 Other Processors</A>
 168 <UL>
 169 <LI><A NAME="tex2html172"
 170   HREF="#SECTION00091000000000000000">8.1 The Z80 and gbz80 port</A>
 171 </UL>
 172 <BR>
 173 <LI><A NAME="tex2html173"
 174   HREF="#SECTION000100000000000000000">9 Support</A>
 175 <UL>
 176 <LI><A NAME="tex2html174"
 177   HREF="#SECTION000101000000000000000">9.1 Reporting Bugs</A>
 178 <LI><A NAME="tex2html175"
 179   HREF="#SECTION000102000000000000000">9.2 Acknowledgments</A>
 180 </UL>
 181 <BR>
 182 <LI><A NAME="tex2html176"
 183   HREF="#SECTION000110000000000000000">About this document ...</A>
 184 </UL>
 185 <!--End of Table of Contents-->
 186
 187 <P>
 188
 189 <H1><A NAME="SECTION00020000000000000000">
 190 1 Introduction</A>
 191 </H1>
 192
 193 <P>
 194
 195 <H2><A NAME="SECTION00021000000000000000">
 196 1.1 About SDCC</A>
 197 </H2>
 198
 199 <P>
 200 <B>SDCC</B> is a Free ware, retargettable, optimizing ANSI-C compiler
 201 by <B>Sandeep Dutta</B> designed for 8 bit Microprocessors. The
 202 current version targets Intel MCS51 based Microprocessors(8051,8052,
 203 etc), Zilog Z80 based MCUs, and the Dallas 80C390 MCS51 variant. It
 204 can be retargetted for other microprocessors, support for PIC, AVR
 205 and 186 is under development. The entire source code for the compiler
 206 is distributed under GPL. SDCC uses ASXXXX &amp; ASLINK, a Freeware,
 207 retargettable assembler &amp; linker. SDCC has extensive language extensions
 208 suitable for utilizing various microcontrollers underlying hardware
 209 effectively. In addition to the MCU specific optimizations SDCC also
 210 does a host of standard optimizations like <I>global sub expression
 211 elimination, loop optimizations (loop invariant, strength reduction
 212 of induction variables and loop reversing), constant folding &amp; propagation,
 213 copy propagation, dead code elimination and jumptables for 'switch'
 214 statements.</I> For the back-end SDCC uses a global register allocation
 215 scheme which should be well suited for other 8 bit MCUs. The peep
 216 hole optimizer uses a rule based substitution mechanism which is MCU
 217 dependent. Supported data-types are <I>char (8 bits, 1 byte), short
 218 and int (16 bits, 2 bytes ), long (32 bit, 4 bytes)</I> and <I>float
 219 (4 byte IEEE).</I> The compiler also allows <I>inline assembler code</I>
 220 to be embedded anywhere in a function. In addition routines developed
 221 in assembly can also be called. SDCC also provides an option to report
 222 the relative complexity of a function, these functions can then be
 223 further optimized, or hand coded in assembly if needed. SDCC also
 224 comes with a companion source level debugger SDCDB, the debugger currently
 225 uses ucSim a freeware simulator for 8051 and other micro-controllers.
 226 The latest version can be downloaded from <B>http://sdcc.sourceforge.net/.</B>
 227
 228 <P>
 229
 230 <H2><A NAME="SECTION00022000000000000000">
 231 1.2 Open Source</A>
 232 </H2>
 233
 234 <P>
 235 All packages used in this compiler system are <I>opensource</I>(freeware);
 236 source code for all the sub-packages (asxxxx assembler/linker, pre-processor)
 237 are distributed with the package. This documentation is maintained
 238 using a freeware word processor (LYX).
 239
 240 <P>
 241 This program is free software; you can redistribute it and/or modify
 242 it under the terms of the GNU General Public License as published
 243 by the Free Software Foundation; either version 2, or (at your option)
 244 any later version. This program is distributed in the hope that it
 245 will be useful, but WITHOUT ANY WARRANTY; without even the implied
 246 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
 247 the GNU General Public License for more details. You should have received
 248 a copy of the GNU General Public License along with this program;
 249 if not, write to the Free Software Foundation, 59 Temple Place - Suite
 250 330, Boston, MA 02111-1307, USA. In other words, you are welcome to
 251 use, share and improve this program. You are forbidden to forbid anyone
 252 else to use, share and improve what you give them. Help stamp out
 253 software-hoarding!
 254
 255 <P>
 256
 257 <H2><A NAME="SECTION00023000000000000000">
 258 1.3 System Requirements</A>
 259 </H2>
 260
 261 <P>
 262 What do you need before you start installation of SDCC? A computer,
 263 and a desire to compute. The preferred method of installation is to
 264 compile SDCC from source using GNU GCC and make. For Windows some
 265 pre-compiled binary distributions are available for your convenience.
 266 You should have some experience with command line tools and compiler
 267 use.
 268
 269 <P>
 270
 271 <H2><A NAME="SECTION00024000000000000000">
 272 1.4 Other Resources</A>
 273 </H2>
 274
 275 <P>
 276 The SDCC home page at http://sdcc.sourceforge.net/ is a great
 277 place to find distribution sets. You can also find links to the user
 278 mailing lists that offer help or discuss SDCC with other SDCC users.
 279 Web links to other SDCC related sites can also be found here. This
 280 document can be found in the DOC directory of the source package as
 281 a text or HTML file. Some of the other tools (simulator and assembler)
 282 included with SDCC contain their own documentation and can be found
 283 in the source distribution. If you want the latest unreleased software,
 284 the complete source package is available directly by anonymous CVS
 285 on www.sourceforge.net.
 286
 287 <P>
 288
 289 <H1><A NAME="SECTION00030000000000000000">
 290 2 Installation</A>
 291 </H1>
 292
 293 <P>
 294
 295 <H2><A NAME="SECTION00031000000000000000">
 296 2.1 Linux/Unix Installation</A>
 297 </H2>
 298
 299 <P>
 300
 301 <OL>
 302 <LI>Download the source package, it will be named something like sdcc-2.x.x.tgz.
 303 </LI>
 304 <LI>Bring up a command line terminal, such as xterm.
 305 </LI>
 306 <LI>Unpack the file using a command like: tar -xzf sdcc-2.x.x.tgz, this
 307 will create a sub-directory called sdcc with all of the sources.
 308 </LI>
 309 <LI>Change directory into the main SDCC directory, for example type: ``cd
 310 sdcc''.
 311 </LI>
 312 <LI>Type ``./configure''. This configures the package for compilation
 313 on your system.
 314 </LI>
 315 <LI>Type ``make''. All of the source packages will compile, this can
 316 take a while.
 317 </LI>
 318 <LI>Type ``make install'' as root. This copies the binary executables
 319 to the install directories.
 320 </LI>
 321 </OL>
 322
 323 <P>
 324
 325 <H2><A NAME="SECTION00032000000000000000">
 326 2.2 Windows Installation</A>
 327 </H2>
 328
 329 <P>
 330 For installation under Windows you first need to pick between a pre-compiled
 331 binary package, or installing the source package along with the Cygwin
 332 package. The binary package is the quickest to install, while the
 333 Cygwin package includes all of the open source power tools used to
 334 compile the complete SDCC source package in the Windows environment.
 335 If you are not familiar with the Unix command line environment, you
 336 may want to read the section on additional information for Windows
 337 users prior to your initial installation.
 338
 339 <P>
 340
 341 <H3><A NAME="SECTION00032100000000000000">
 342 2.2.1 Windows Install Using a Binary Package</A>
 343 </H3>
 344
 345 <P>
 346
 347 <OL>
 348 <LI>Download the binary package and unpack it using your favorite unpacking
 349 tool(gunzip, WinZip, etc). This should unpack to a group of sub-directories.
 350 An example directory structure after unpacking is: c:&#92;usr&#92;local&#92;bin
 351 for the executables, c:&#92;usr&#92;local&#92;share&#92;sdcc&#92;include
 352 and c:&#92;usr&#92;local&#92;share&#92;sdcc&#92;lib
 353 for the include and libraries.
 354 </LI>
 355 <LI>Adjust your environment PATH to include the location of the bin directory.
 356 For example, make a setsdcc.bat file with the following: set PATH=c:&#92;usr&#92;local&#92;bin;%PATH%
 357 </LI>
 358 <LI>When you compile with sdcc, you may need to specify the location of
 359 the lib and include folders. For example, sdcc -I c:&#92;usr&#92;local&#92;share&#92;sdcc&#92;include
 360 -L c:&#92;usr&#92;local&#92;share&#92;sdcc&#92;lib&#92;small
 361 test.c
 362 </LI>
 363 </OL>
 364
 365 <P>
 366
 367 <H3><A NAME="SECTION00032200000000000000">
 368 2.2.2 Windows Install Using Cygwin</A>
 369 </H3>
 370
 371 <P>
 372
 373 <OL>
 374 <LI>Download and install the cygwin package from the redhat site<I>http://sources.redhat.com/cygwin/</I>.
 375 Currently, this involved downloading a small install program which
 376 then automates downloading and installing selected parts of the package(a
 377 large 80M byte sized dowload for the whole thing).
 378 </LI>
 379 <LI>Bring up a Unix/Bash command line terminal from the Cygwin menu.
 380 </LI>
 381 <LI>Follow the instructions in the preceding Linux/Unix installation section.
 382 </LI>
 383 </OL>
 384
 385 <P>
 386
 387 <H2><A NAME="SECTION00033000000000000000">
 388 2.3 Testing out the SDCC Compiler</A>
 389 </H2>
 390
 391 <P>
 392 The first thing you should do after installing your SDCC compiler
 393 is to see if it runs. Type ``sdcc -version'' at the prompt, and
 394 the program should run and tell you the version. If it doesn't run,
 395 or gives a message about not finding sdcc program, then you need to
 396 check over your installation. Make sure that the sdcc bin directory
 397 is in your executable search path defined by the PATH environment
 398 setting (see the Trouble-shooting section for suggestions). Make sure
 399 that the sdcc program is in the bin folder, if not perhaps something
 400 did not install correctly.
 401
 402 <P>
 403 SDCC binaries are commonly installed in a directory arrangement like
 404 this:
 405 <BR>
 406 <P>
 407 <TABLE CELLPADDING=3 BORDER="1">
 408 <TR><TD ALIGN="LEFT">/usr/local/bin</TD>
 409 <TD ALIGN="LEFT">Holds executables(sdcc, s51, aslink, ...)</TD>
 410 </TR>
 411 <TR><TD ALIGN="LEFT">/usr/local/share/sdcc/lib</TD>
 412 <TD ALIGN="LEFT">Holds common C libraries</TD>
 413 </TR>
 414 <TR><TD ALIGN="LEFT">/usr/local/share/sdcc/include</TD>
 415 <TD ALIGN="LEFT">Holds common C header files</TD>
 416 </TR>
 417 </TABLE>
 418 <BR>
 419 <BR>
 420 Make sure the compiler works on a very simple example. Type in the
 421 following test.c program using your favorite editor:
 422 <BR>
 423 <BR><TT>main()</TT>&nbsp;
 424 <BR><TT>{ </TT>
 425
 426 <P>
 427 <TT>int i;</TT>
 428
 429 <P>
 430 <TT>i = 0;</TT>
 431
 432 <P>
 433 <TT>i += 10;</TT>&nbsp;
 434 <BR><TT>}</TT>
 435 <BR>
 436 <P>
 437 Compile this using the following command: ``sdcc -c test.c''.
 438 If all goes well, the compiler will generate a test.asm and test.rel
 439 file. Congratulations, you've just compiled your first program with
 440 SDCC. We used the -c option to tell SDCC not to link the generated
 441 code, just to keep things simple for this step.
 442
 443 <P>
 444 The next step is to try it with the linker. Type in ``sdcc test.c''.
 445 If all goes well the compiler will link with the libraries and produce
 446 a test.ihx output file. If this step fails (no test.ihx, and the linker
 447 generates warnings), then the problem is most likely that sdcc cannot
 448 find the /usr/local/share/sdcc/lib directory (see the Install trouble-shooting
 449 section for suggestions).
 450
 451 <P>
 452 The final test is to ensure sdcc can use the standard header files
 453 and libraries. Edit test.c and change it to the following:
 454 <BR>
 455 <BR><TT>#include &lt;string.h&gt;</TT>&nbsp;
 456 <BR><TT>main()</TT>&nbsp;
 457 <BR><TT>{ </TT>
 458
 459 <P>
 460 <TT>char str1[10];</TT>
 461
 462 <P>
 463 <TT>strcpy(str1, ``testing'');</TT>&nbsp;
 464 <BR>&nbsp;
 465 <BR><TT>}</TT>
 466 <BR>
 467 <P>
 468 Compile this by typing: ``sdcc test.c''. This should generate
 469 a test.ihx output file, and it should give no warnings such as not
 470 finding the string.h file. If it cannot find the string.h file, then
 471 the problem is that sdcc cannot find the /usr/local/share/sdcc/include
 472 directory (see the Install trouble-shooting section for suggestions).
 473
 474 <P>
 475
 476 <H2><A NAME="SECTION00034000000000000000">
 477 2.4 Install Trouble-shooting</A>
 478 </H2>
 479
 480 <P>
 481
 482 <H3><A NAME="SECTION00034100000000000000">
 483 2.4.1 SDCC cannot find libraries or header files.</A>
 484 </H3>
 485
 486 <P>
 487 The default installation assumes the libraries and header files are
 488 located at ``/usr/local/share/sdcc/lib'' and ``/usr/local/share/sdcc/include''.
 489 An alternative is to specify these locations as compiler options like
 490 this: sdcc -L /usr/local/sdcc/lib/small -I /usr/local/sdcc/include
 491 test.c
 492
 493 <P>
 494
 495 <H3><A NAME="SECTION00034200000000000000">
 496 2.4.2 SDCC does not compile correctly.</A>
 497 </H3>
 498
 499 <P>
 500 A thing to try is starting from scratch by unpacking the .tgz source
 501 package again in an empty directory. Confure it again and build like:
 502
 503 <P>
 504 ``make 2SPMamp;&gt;1 | tee make.log''
 505
 506 <P>
 507 After this you can review the make.log file to locate the problem.
 508 Or a relevant part of this be attached to an email that could be helpful
 509 when requesting help from the mailing list.
 510
 511 <P>
 512
 513 <H3><A NAME="SECTION00034300000000000000">
 514 2.4.3 What the ``./configure'' does</A>
 515 </H3>
 516
 517 <P>
 518 The ``./configure'' command is a script that analyzes your system
 519 and performs some configuration to ensure the source package compiles
 520 on your system. It will take a few minutes to run, and will compile
 521 a few tests to determine what compiler features are installed.
 522
 523 <P>
 524
 525 <H3><A NAME="SECTION00034400000000000000">
 526 2.4.4 What the ``make'' does.</A>
 527 </H3>
 528
 529 <P>
 530 This runs the GNU make tool, which automatically compiles all the
 531 source packages into the final installed binary executables.
 532
 533 <P>
 534
 535 <H3><A NAME="SECTION00034500000000000000">
 536 2.4.5 What the ``make install'' command does.</A>
 537 </H3>
 538
 539 <P>
 540 This will install the compiler, other executables and libraries in
 541 to the appropriate system directories. The default is to copy the
 542 executables to /usr/local/bin and the libraries and header files to
 543 /usr/local/share/sdcc/lib and /usr/local/share/sdcc/include.
 544
 545 <P>
 546
 547 <H2><A NAME="SECTION00035000000000000000">
 548 2.5 Additional Information for Windows Users</A>
 549 </H2>
 550
 551 <P>
 552 The standard method of installing on a Unix system involves compiling
 553 the source package. This is easily done under Unix, but under Windows
 554 it can be a more difficult process. The Cygwin is a large package
 555 to download, and the compilation runs considerably slower under Windows
 556 due to the overhead of the Cygwin tool set. An alternative is to install
 557 a pre-compiled Windows binary package. There are various trade-offs
 558 between each of these methods.
 559
 560 <P>
 561 The Cygwin package allows a Windows user to run a Unix command line
 562 interface(bash shell) and also implements a Unix like file system
 563 on top of Windows. Included are many of the famous GNU software development
 564 tools which can augment the SDCC compiler.This is great if you have
 565 some experience with Unix command line tools and file system conventions,
 566 if not you may find it easier to start by installing a binary Windows
 567 package. The binary packages work with the Windows file system conventions.
 568
 569 <P>
 570
 571 <H3><A NAME="SECTION00035100000000000000">
 572 2.5.1 Getting started with Cygwin</A>
 573 </H3>
 574
 575 <P>
 576 SDCC is typically distributed as a tarred/gzipped file(.tgz). This
 577 is a packed file similar to a .zip file. Cygwin includes the tools
 578 you will need to unpack the SDCC distribution(tar and gzip). To unpack
 579 it, simply follow the instructions under the Linux/Unix install section.
 580 Before you do this you need to learn how to start a cygwin shell and
 581 some of the basic commands used to move files, change directory, run
 582 commands and so on. The change directory command is ``cd'', the
 583 move command is ``mv''. To print the current working directory,
 584 type ``pwd''. To make a directory, use ``mkdir''.
 585
 586 <P>
 587 There are some basic differences between Unix and Windows file systems
 588 you should understand. When you type in directory paths, Unix and
 589 the Cygwin bash prompt uses forward slashes '/' between directories
 590 while Windows traditionally uses '&#92;' backward slashes.
 591 So when you work at the Cygwin bash prompt, you will need to use the
 592 forward '/' slashes. Unix does not have a concept of drive letters,
 593 such as ``c:``, instead all files systems attach and appear
 594 as directories.
 595
 596 <P>
 597
 598 <H3><A NAME="SECTION00035200000000000000">
 599 2.5.2 Running SDCC as Native Compiled Executables</A>
 600 </H3>
 601
 602 <P>
 603 If you use the pre-compiled binaries, the install directories for
 604 the libraries and header files may need to be specified on the sdcc
 605 command line like this: sdcc -L c:&#92;usr&#92;local&#92;sdcc&#92;lib&#92;small
 606 -I c:&#92;usr&#92;local&#92;sdcc&#92;include
 607 test.c if you are running outside of a Unix bash shell.
 608
 609 <P>
 610 If you have successfully installed and compiled SDCC with the Cygwin
 611 package, it is possible to compile into native .exe files by using
 612 the additional makefiles included for this purpose. For example, with
 613 the Borland 32-bit compiler you would run make -f Makefile.bcc. A
 614 command line version of the Borland 32-bit compiler can be downloaded
 615 from the Inprise web site.
 616
 617 <P>
 618
 619 <H2><A NAME="SECTION00036000000000000000">
 620 2.6 SDCC on Other Platforms</A>
 621 </H2>
 622
 623 <P>
 624
 625 <UL>
 626 <LI><B>FreeBSD and other non-GNU Unixes</B> - Make sure the GNU make
 627 is installed as the default make tool.
 628 </LI>
 629 <LI>SDCC has been ported to run under a variety of operating systems and
 630 processors. If you can run GNU GCC/make then chances are good SDCC
 631 can be compiled and run on your system.
 632 </LI>
 633 </UL>
 634
 635 <P>
 636
 637 <H2><A NAME="SECTION00037000000000000000">
 638 2.7 Advanced Install Options</A>
 639 </H2>
 640
 641 <P>
 642 The ``configure'' command has several options. The most commonly
 643 used option is -prefix=&lt;directory name&gt;, where &lt;directory name&gt; is
 644 the final location for the sdcc executables and libraries, (default
 645 location is /usr/local). The installation process will create the
 646 following directory structure under the &lt;directory name&gt; specified.
 647
 648 <P>
 649 bin/ - binary exectables (add to PATH environment variable)
 650 <BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;share/
 651 <BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sdcc/include/ - include header files
 652 <BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;sdcc/lib/ -
 653 <BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;small/ - Object &amp; library files for small
 654 model library
 655 <BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;large/ - Object &amp; library files for large
 656 model library
 657 <BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ds390/ - Object &amp; library files forDS80C390
 658 library
 659
 660 <P>
 661 The command
 662
 663 <P>
 664 <B><U><FONT SIZE="+1">'./configure -prefix=/usr/local'' </FONT></U></B>
 665 <P>
 666
 667
 668 <P>
 669 will configure the compiler to be installed in directory /usr/local/bin.
 670
 671 <P>
 672
 673 <H2><A NAME="SECTION00038000000000000000">
 674 2.8 Components of SDCC</A>
 675 </H2>
 676
 677 <P>
 678 SDCC is not just a compiler, but a collection of tools by various
 679 developers. These include linkers, assemblers, simulators and other
 680 components. Here is a summary of some of the components. Note that
 681 the included simulator and assembler have separate documentation which
 682 you can find in the source package in their respective directories.
 683 As SDCC grows to include support for other processors, other packages
 684 from various developers are included and may have their own sets of
 685 documentation.
 686
 687 <P>
 688 You might want to look at the various executables which are installed
 689 in the bin directory. At the time of this writing, we find the following
 690 programs:
 691
 692 <P>
 693 <B>sdcc</B> - The compiler.
 694
 695 <P>
 696 <B>aslink</B> -The linker for 8051 type processors.
 697
 698 <P>
 699 <B>asx8051</B> - The assembler for 8051 type processors.
 700
 701 <P>
 702 <B>sdcpp</B> - The C preprocessor.
 703
 704 <P>
 705 <B>sdcpd</B> - The source debugger.
 706
 707 <P>
 708 <B>s51</B> - The ucSim 8051 simulator.
 709
 710 <P>
 711 <B>linkz80, linkgbz80</B> - The Z80 and GameBoy Z80 linkers.
 712
 713 <P>
 714 <B>as-z80, as-gbz80</B> - The Z80 and GameBoy Z80 assemblers.
 715
 716 <P>
 717 <B>packihx</B> - A tool to pack Intel hex files.
 718
 719 <P>
 720 As development for other processors proceeds, this list will expand
 721 to include executables to support processors like AVR, PIC, etc.
 722
 723 <P>
 724
 725 <H3><A NAME="SECTION00038100000000000000">
 726 2.8.1 cpp ( C-Preprocessor)</A>
 727 </H3>
 728
 729 <P>
 730 The preprocessor is extracted into the directory <I>SDCCDIR/cpp</I>,
 731 it is a modified version of the GNU preprocessor. The C preprocessor
 732 is used to pull in #include sources, process #ifdef statements,
 733 #defines and so on.
 734
 735 <P>
 736
 737 <H3><A NAME="SECTION00038200000000000000">
 738 2.8.2 asxxxx &amp; aslink ( The assembler and Linkage Editor)</A>
 739 </H3>
 740
 741 <P>
 742 This is retargettable assembler &amp; linkage editor, it was developed
 743 by Alan Baldwin, John Hartman created the version for 8051, and I
 744 (Sandeep) have some enhancements and bug fixes for it to work properly
 745 with the SDCC. This component is extracted into the directory <I>SDCCDIR/asxxxx.</I>
 746
 747 <P>
 748
 749 <H3><A NAME="SECTION00038300000000000000">
 750 2.8.3 SDCC - The compiler</A>
 751 </H3>
 752
 753 <P>
 754 This is the actual compiler, it in turn uses the c-preprocessor and
 755 invokes the assembler and linkage editors. All files with the prefix
 756 <I>SDCC</I> are part of the compiler and are extracted into the the
 757 directory <I>SDCCDIR.</I>
 758
 759 <P>
 760
 761 <H3><A NAME="SECTION00038400000000000000">
 762 2.8.4 S51 - Simulator</A>
 763 </H3>
 764
 765 <P>
 766 s51 is a freeware, opensource simulator developed by Daniel Drotos
 767 &lt;drdani@mazsola.iit.uni-miskolc.hu&gt;. The executable is built as part
 768 of the build process, for more information visit Daniel's website
 769 at &lt;http://mazsola.iit.uni-miskolc.hu/drdani/embedded/s51/&gt;.
 770
 771 <P>
 772
 773 <H3><A NAME="SECTION00038500000000000000">
 774 2.8.5 SDCDB - Source Level Debugger</A>
 775 </H3>
 776
 777 <P>
 778 SDCDB is the companion source level debugger. The current version
 779 of the debugger uses Daniel's Simulator S51, but can be easily changed
 780 to use other simulators.
 781
 782 <P>
 783
 784 <H1><A NAME="SECTION00040000000000000000">
 785 3 Using SDCC</A>
 786 </H1>
 787
 788 <P>
 789
 790 <H2><A NAME="SECTION00041000000000000000">
 791 3.1 Compiling</A>
 792 </H2>
 793
 794 <P>
 795
 796 <H3><A NAME="SECTION00041100000000000000">
 797 3.1.1 Single Source File Projects</A>
 798 </H3>
 799
 800 <P>
 801 For single source file 8051 projects the process is very simple. Compile
 802 your programs with the following command
 803
 804 <P>
 805 <FONT SIZE="-1">sdcc sourcefile.c</FONT>
 806 <P>
 807
 808
 809 <P>
 810 The above command will compile ,assemble and link your source file.
 811 Output files are as follows.
 812
 813 <P>
 814
 815 <UL>
 816 <LI><FONT SIZE="-1">sourcefile.asm - Assembler source file created by the
 817 compiler</FONT>
 818 <P>
 819
 820 </LI>
 821 <LI><FONT SIZE="-1">sourcefile.lst - Assembler listing file created by
 822 the Assembler</FONT>
 823 <P>
 824
 825 </LI>
 826 <LI><FONT SIZE="-1">sourcefile.rst - Assembler listing file updated with
 827 linkedit information , created by linkage editor</FONT>
 828 <P>
 829
 830 </LI>
 831 <LI><FONT SIZE="-1">sourcefile.sym - symbol listing for the sourcefile,
 832 created by the assembler.</FONT>
 833 <P>
 834
 835 </LI>
 836 <LI><FONT SIZE="-1">sourcefile.rel - Object file created by the assembler,
 837 input to Linkage editor.</FONT>
 838 <P>
 839
 840 </LI>
 841 <LI><FONT SIZE="-1">sourcefile.map - The memory map for the load module,
 842 created by the Linker.</FONT>
 843 <P>
 844
 845 </LI>
 846 <LI><FONT SIZE="-1">sourcefile.ihx - The load module in Intel hex format
 847 (you can select the Motorola S19 format with -out-fmt-s19)</FONT>
 848 <P>
 849
 850 </LI>
 851 <LI>sourcefile.cdb - An optional file (with -debug) containing debug
 852 information.
 853 </LI>
 854 </UL>
 855
 856 <P>
 857
 858 <H3><A NAME="SECTION00041200000000000000">
 859 3.1.2 Projects with Multiple Source Files</A>
 860 </H3>
 861
 862 <P>
 863 SDCC can compile only ONE file at a time. Let us for example assume
 864 that you have a project containing the following files.
 865
 866 <P>
 867 <FONT SIZE="-1">foo1.c ( contains some functions )</FONT>
 868 <P>
 869
 870
 871 <P>
 872 <FONT SIZE="-1">foo2.c (contains some more functions)</FONT>
 873 <P>
 874
 875
 876 <P>
 877 <FONT SIZE="-1">foomain.c (contains more functions and the function
 878 main)</FONT>
 879 <P>
 880
 881
 882 <P>
 883 The first two files will need to be compiled separately with the commands
 884
 885 <P>
 886 <FONT SIZE="-1">sdcc -c foo1.c</FONT>
 887 <P>
 888
 889
 890 <P>
 891 <FONT SIZE="-1">sdcc -c foo2.c</FONT>
 892 <P>
 893
 894
 895 <P>
 896 Then compile the source file containing main and link the other files
 897 together with the following command.
 898
 899 <P>
 900 <FONT SIZE="-1">sdcc foomain.c foo1.rel foo2.rel</FONT>
 901 <P>
 902
 903
 904 <P>
 905 Alternatively <I>foomain.c</I> can be separately compiled as well
 906
 907 <P>
 908 <FONT SIZE="-1">sdcc -c foomain.c </FONT>
 909 <P>
 910
 911
 912 <P>
 913 <FONT SIZE="-1">sdcc foomain.rel foo1.rel foo2.rel</FONT>
 914 <P>
 915
 916
 917 <P>
 918 The file containing the main function MUST be the FIRST file specified
 919 in the command line , since the linkage editor processes file in the
 920 order they are presented to it.
 921
 922 <P>
 923
 924 <H3><A NAME="SECTION00041300000000000000">
 925 3.1.3 Projects with Additional Libraries</A>
 926 </H3>
 927
 928 <P>
 929 Some reusable routines may be compiled into a library, see the documentation
 930 for the assembler and linkage editor in the directory <I>SDCCDIR/asxxxx/asxhtm.htm</I>
 931 this describes how to create a <I>.lib</I> library file, the libraries
 932 created in this manner may be included using the command line, make
 933 sure you include the -L &lt;library-path&gt; option to tell the linker where
 934 to look for these files. Here is an example, assuming you have the
 935 source file <I>'foomain.c</I>' and a library <I>'foolib.lib'</I> in
 936 the directory <I>'mylib</I>' (if that is not the same as your current
 937 project).
 938
 939 <P>
 940 <FONT SIZE="-1">sdcc foomain.c foolib.lib -L mylib</FONT>
 941 <P>
 942
 943
 944 <P>
 945 Note here that <I>'mylib</I>' must be an absolute path name.
 946
 947 <P>
 948 The view of the way the linkage editor processes the library files,
 949 it is recommended that you put each source routine in a separate file
 950 and combine them using the .lib file. For an example see the standard
 951 library file 'libsdcc.lib' in the directory SDCCDIR/sdcc51lib.
 952
 953 <P>
 954
 955 <H2><A NAME="SECTION00042000000000000000">
 956 3.2 Command Line Options</A>
 957 </H2>
 958
 959 <P>
 960
 961 <H3><A NAME="SECTION00042100000000000000">
 962 3.2.1 Processor Selection Options</A>
 963 </H3>
 964
 965 <P>
 966
 967 <UL>
 968 <LI>[<B>-mmcs51</B>]Generate code for the MCS51 (8051) family of processors.
 969 This is the default processor target.
 970 </LI>
 971 <LI>[<B>-mds390</B>]Generate code for the DS80C390 processor.
 972 </LI>
 973 <LI>[<B>-mz80</B>]Generate code for the Z80 family of processors.
 974 </LI>
 975 <LI>[<B>-mgbz80</B>]Generate code for the GameBoy Z80 processor.
 976 </LI>
 977 <LI>[<B>-mavr</B>]Generate code for the Atmel AVR processor(In development,
 978 not complete).
 979 </LI>
 980 <LI>[<B>-mpic14</B>]Generate code for the PIC 14-bit processors(In development,
 981 not complete).
 982 </LI>
 983 <LI>[<B>-mtlcs900h</B>]Generate code for the Toshiba TLCS-900H processor(In
 984 development, not complete).
 985 </LI>
 986 </UL>
 987 <P>
 988
 989 <H3><A NAME="SECTION00042200000000000000">
 990 3.2.2 Preprocessor Options</A>
 991 </H3>
 992
 993 <P>
 994
 995 <UL>
 996 <LI>[<B>-I&lt;path&gt;</B>]The additional location where the pre processor
 997 will look for &lt;..h&gt; or ``..h'' files.
 998 </LI>
 999 <LI>[<B>-D&lt;macro[=value]&gt;</B>]Command line definition of macros.
1000 Passed to the pre processor.
1001 </LI>
1002 <LI>[<B>-compile-only(-c)</B>] will compile and assemble the source,
1003 but will not call the linkage editor.
1004 </LI>
1005 </UL>
1006 <P>
1007
1008 <H3><A NAME="SECTION00042300000000000000">
1009 3.2.3 Linker Options</A>
1010 </H3>
1011
1012 <P>
1013 <B>-lib-path(-L)</B> &lt;absolute path to additional libraries&gt; This
1014 option is passed to the linkage editor's additional libraries search
1015 path. The path name must be absolute. Additional library files may
1016 be specified in the command line. See section Compiling programs for
1017 more details.
1018
1019 <P>
1020 <B>-xram-loc</B>&lt;Value&gt; The start location of the external ram,
1021 default value is 0. The value entered can be in Hexadecimal or Decimal
1022 format, e.g.: -xram-loc 0x8000 or -xram-loc 32768.
1023
1024 <P>
1025
1026 <UL>
1027 <LI>[<B>-code-loc</B>&lt;Value&gt;]The start location of the code segment
1028 , default value 0. Note when this option is used the interrupt vector
1029 table is also relocated to the given address. The value entered can
1030 be in Hexadecimal or Decimal format, e.g.: -code-loc 0x8000 or -code-loc
1031 32768.
1032 </LI>
1033 <LI>[<B>-stack-loc</B>&lt;Value&gt;]The initial value of the stack pointer.
1034 The default value of the stack pointer is 0x07 if only register bank
1035 0 is used, if other register banks are used then the stack pointer
1036 is initialized to the location above the highest register bank used.
1037 eg. if register banks 1 &amp; 2 are used the stack pointer will default
1038 to location 0x18. The value entered can be in Hexadecimal or Decimal
1039 format, eg. -stack-loc 0x20 or -stack-loc 32. If all four register
1040 banks are used the stack will be placed after the data segment (equivalent
1041 to -stack-after-data)
1042 </LI>
1043 <LI>[<B>-stack-after-data</B>]This option will cause the stack to be
1044 located in the internal ram after the data segment.
1045 </LI>
1046 <LI>[<B>-data-loc</B>&lt;Value&gt;]The start location of the internal ram
1047 data segment, the default value is 0x30.The value entered can be in
1048 Hexadecimal or Decimal format, eg. -data-loc 0x20 or -data-loc 32.
1049 </LI>
1050 <LI>[<B>-idata-loc</B>&lt;Value&gt;]The start location of the indirectly
1051 addressable internal ram, default value is 0x80. The value entered
1052 can be in Hexadecimal or Decimal format, eg. -idata-loc 0x88 or -idata-loc
1053 136.
1054 </LI>
1055 </UL>
1056 <P>
1057
1058 <H3><A NAME="SECTION00042400000000000000">
1059 3.2.4 MCS51 Options</A>
1060 </H3>
1061
1062 <P>
1063
1064 <UL>
1065 <LI>[<B>-model-large</B>]Generate code for Large model programs see
1066 section Memory Models for more details. If this option is used all
1067 source files in the project should be compiled with this option. In
1068 addition the standard library routines are compiled with small model
1069 , they will need to be recompiled.
1070 </LI>
1071 <LI>[<B>-model-small</B>]Generate code for Small Model programs see
1072 section Memory Models for more details. This is the default model.
1073 </LI>
1074 <LI>[<B>-stack-auto</B>]All functions in the source file will be compiled
1075 as <I>reentrant</I>, i.e. the parameters and local variables will
1076 be allocated on the stack. see section Parameters and Local Variables
1077 for more details. If this option is used all source files in the project
1078 should be compiled with this option.
1079 </LI>
1080 <LI>[<B>-xstack</B>]Uses a pseudo stack in the first 256 bytes in the
1081 external ram for allocating variables and passing parameters. See
1082 section on external stack for more details.
1083 </LI>
1084 </UL>
1085 <P>
1086
1087 <H3><A NAME="SECTION00042500000000000000">
1088 3.2.5 Optimization Options</A>
1089 </H3>
1090
1091 <P>
1092
1093 <UL>
1094 <LI>[<B>-nogcse</B>]Will not do global subexpression elimination, this
1095 option may be used when the compiler creates undesirably large stack/data
1096 spaces to store compiler temporaries. A warning message will be generated
1097 when this happens and the compiler will indicate the number of extra
1098 bytes it allocated. It recommended that this option NOT be used ,
1099 #pragma NOGCSE can be used to turn off global subexpression elimination
1100 for a given function only.
1101 </LI>
1102 <LI>[<B>-noinvariant</B>]Will not do loop invariant optimizations,
1103 this may be turned off for reasons explained for the previous option.
1104 For more details of loop optimizations performed see section Loop
1105 Invariants.It recommended that this option NOT be used , #pragma
1106 NOINVARIANT can be used to turn off invariant optimizations for a
1107 given function only.
1108 </LI>
1109 <LI>[<B>-noinduction</B>]Will not do loop induction optimizations,
1110 see section Strength reduction for more details.It recommended that
1111 this option NOT be used , #pragma NOINDUCTION can be used to turn
1112 off induction optimizations for given function only.
1113 </LI>
1114 <LI>[<B>-nojtbound</B>] Will not generate boundary condition check
1115 when switch statements are implemented using jump-tables. See section
1116 Switch Statements for more details.It recommended that this option
1117 NOT be used , #pragma NOJTBOUND can be used to turn off boundary
1118 checking for jump tables for a given function only.
1119 </LI>
1120 <LI>[<B>-noloopreverse</B>]Will not do loop reversal optimization
1121 </LI>
1122 </UL>
1123 <P>
1124
1125 <H3><A NAME="SECTION00042600000000000000">
1126 3.2.6 DS390 Options</A>
1127 </H3>
1128
1129 <P>
1130
1131 <UL>
1132 <LI>[<B>-stack-auto</B>]See MCS51 section for description.
1133 </LI>
1134 <LI>[-<B>model</B>-<B>flat24</B>]Generate 24-bit flat mode code.
1135 This is the one and only that the ds390 code generator supports right
1136 now and is default when using -mds390. See section Memory Models for
1137 more details.
1138 </LI>
1139 <LI>[<B>-stack-10bit</B>]This option generates code for the 10 bit
1140 stack mode of the Dallas DS80C390 part. This is the one and only that
1141 the ds390 code generator supports right now and is default when using
1142 -mds390. In this mode, the stack is located in the lower 1K of the
1143 internal RAM, which is mapped to 0x400000. Note that the support is
1144 incomplete, since it still uses a single byte as the stack pointer.
1145 This means that only the lower 256 bytes of the potential 1K stack
1146 space will actually be used. However, this does allow you to reclaim
1147 the precious 256 bytes of low RAM for use for the DATA and IDATA segments.
1148 The compiler will not generate any code to put the processor into
1149 10 bit stack mode. It is important to ensure that the processor is
1150 in this mode before calling any re-entrant functions compiled with
1151 this option. In principle, this should work with the -stack-auto
1152 option, but that has not been tested. It is incompatible with the
1153 -xstack option. It also only makes sense if the processor is in 24
1154 bit contiguous addressing mode (see the -model-flat24 option).
1155 </LI>
1156 </UL>
1157 <P>
1158
1159 <H3><A NAME="SECTION00042700000000000000">
1160 3.2.7 Other Options</A>
1161 </H3>
1162
1163 <P>
1164
1165 <UL>
1166 <LI>[<B>-callee-saves</B>]<B>function1[,function2][,function3]....</B>
1167 The compiler by default uses a caller saves convention for register
1168 saving across function calls, however this can cause unneccessary
1169 register pushing &amp; popping when calling small functions from larger
1170 functions. This option can be used to switch the register saving convention
1171 for the function names specified. The compiler will not save registers
1172 when calling these functions, no extra code will be generated at the
1173 entry &amp; exit for these functions to save &amp; restore the registers
1174 used by these functions, this can SUBSTANTIALLY reduce code &amp; improve
1175 run time performance of the generated code. In the future the compiler
1176 (with interprocedural analysis) will be able to determine the appropriate
1177 scheme to use for each function call. DO NOT use this option for built-in
1178 functions such as _muluint..., if this option is used for a library
1179 function the appropriate library function needs to be recompiled with
1180 the same option. If the project consists of multiple source files
1181 then all the source file should be compiled with the same -callee-saves
1182 option string. Also see Pragma Directive CALLEE-SAVES.
1183 </LI>
1184 <LI>[<B>-debug</B>]When this option is used the compiler will generate
1185 debug information , that can be used with the SDCDB. The debug information
1186 is collected in a file with .cdb extension. For more information see
1187 documentation for SDCDB.
1188 </LI>
1189 <LI>[<B>-regextend</B>] This option will cause the compiler to define
1190 pseudo registers , if this option is used, all source files in the
1191 project should be compiled with this option. See section Register
1192 Extension for more details.
1193 </LI>
1194 <LI>[<B>-peep-file</B>&lt;filename&gt;]This option can be used to use additional
1195 rules to be used by the peep hole optimizer. See section Peep Hole
1196 optimizations for details on how to write these rules.
1197 </LI>
1198 <LI>[<B>-E</B>]Run only the C preprocessor. Preprocess all the C source
1199 files specified and output the results to standard output.
1200 </LI>
1201 <LI>[<B>-M</B>]Tell the preprocessor to output a rule suitable for make
1202 describing the dependencies of each object file. For each source file,
1203 the preprocessor outputs one make-rule whose target is the object
1204 file name for that source file and whose dependencies are all the
1205 files `#include'd in it. This rule may be a single line or may be
1206 continued with `&#92;'-newline if it is long. The list
1207 of rules is printed on standard output instead of the preprocessed
1208 C program. `-M' implies `-E'.
1209 </LI>
1210 <LI>[<B>-C</B>]Tell the preprocessor not to discard comments. Used with
1211 the `-E' option.
1212 </LI>
1213 <LI>[<B>-MM</B>]Like `-M' but the output mentions only the user header
1214 files included with `#include ``file&#34;'. System header
1215 files included with `#include &lt;file&gt;' are omitted.
1216 </LI>
1217 <LI>[<B>-Aquestion(answer)</B>]Assert the answer answer for question,
1218 in case it is tested with a preprocessor conditional such as `#if
1219 #question(answer)'. `-A-' disables the standard assertions that normally
1220 describe the target machine.
1221 </LI>
1222 <LI>[<B>-Aquestion</B>](answer) Assert the answer answer for question,
1223 in case it is tested with a preprocessor conditional such as `#if
1224 #question(answer)'. `-A-' disables the standard assertions that normally
1225 describe the target machine.
1226 </LI>
1227 <LI>[<B>-Umacro</B>]Undefine macro macro. `-U' options are evaluated
1228 after all `-D' options, but before any `-include' and `-imacros' options.
1229 </LI>
1230 <LI>[<B>-dM</B>]Tell the preprocessor to output only a list of the macro
1231 definitions that are in effect at the end of preprocessing. Used with
1232 the `-E' option.
1233 </LI>
1234 <LI>[<B>-dD</B>]Tell the preprocessor to pass all macro definitions
1235 into the output, in their proper sequence in the rest of the output.
1236 </LI>
1237 <LI>[<B>-dN</B>]Like `-dD' except that the macro arguments and contents
1238 are omitted. Only `#define name' is included in the output.
1239 </LI>
1240 <LI>[<B>-S</B>]Stop after the stage of compilation proper; do not assemble.
1241 The output is an assembler code file for the input file specified.
1242 </LI>
1243 <LI>[<B>-Wa_asmOption[,asmOption]</B>...]Pass the asmOption to
1244 the assembler.
1245 </LI>
1246 <LI>[<B>-Wl_linkOption[,linkOption]</B>...]Pass the linkOption
1247 to the linker.
1248 </LI>
1249 <LI>[<B>-int-long-reent</B>] Integer (16 bit) and long (32 bit) libraries
1250 have been compiled as reentrant. Note by default these libraries are
1251 compiled as non-reentrant. See section Installation for more details.
1252 </LI>
1253 <LI>[<B>-cyclomatic</B>]This option will cause the compiler to generate
1254 an information message for each function in the source file. The message
1255 contains some <I>important</I> information about the function. The
1256 number of edges and nodes the compiler detected in the control flow
1257 graph of the function, and most importantly the <I>cyclomatic complexity</I>
1258 see section on Cyclomatic Complexity for more details.
1259 </LI>
1260 <LI>[<B>-float-reent</B>] Floating point library is compiled as reentrant.See
1261 section Installation for more details.
1262 </LI>
1263 <LI>[<B>-out-fmt-ihx</B>]The linker output (final object code) is in
1264 Intel Hex format. (This is the default option).
1265 </LI>
1266 <LI>[<B>-out-fmt-s19</B>]The linker output (final object code) is in
1267 Motorola S19 format.
1268 </LI>
1269 <LI>[<B>-nooverlay</B>] The compiler will not overlay parameters and
1270 local variables of any function, see section Parameters and local
1271 variables for more details.
1272 </LI>
1273 <LI>[<B>-main-return</B>]This option can be used when the code generated
1274 is called by a monitor program. The compiler will generate a 'ret'
1275 upon return from the 'main' function. The default option is to lock
1276 up i.e. generate a 'ljmp '.
1277 </LI>
1278 <LI>[<B>-no-peep</B>] Disable peep-hole optimization.
1279 </LI>
1280 <LI>[<B>-peep-asm</B>] Pass the inline assembler code through the peep
1281 hole optimizer. This can cause unexpected changes to inline assembler
1282 code, please go through the peephole optimizer rules defined in the
1283 source file tree '&lt;target&gt;/peeph.def' before using this option.
1284 </LI>
1285 <LI>[<B>-iram-size</B>&lt;Value&gt;]Causes the linker to check if the interal
1286 ram usage is within limits of the given value.
1287 </LI>
1288 </UL>
1289 <P>
1290
1291 <H3><A NAME="SECTION00042800000000000000">
1292 3.2.8 Intermediate Dump Options</A>
1293 </H3>
1294
1295 <P>
1296 The following options are provided for the purpose of retargetting
1297 and debugging the compiler. These provided a means to dump the intermediate
1298 code (iCode) generated by the compiler in human readable form at various
1299 stages of the compilation process.
1300
1301 <P>
1302
1303 <UL>
1304 <LI>[<B>-dumpraw</B>]This option will cause the compiler to dump the
1305 intermediate code into a file of named <I>&lt;source filename&gt;.dumpraw</I>
1306 just after the intermediate code has been generated for a function,
1307 i.e. before any optimizations are done. The basic blocks at this stage
1308 ordered in the depth first number, so they may not be in sequence
1309 of execution.
1310 </LI>
1311 <LI>[<B>-dumpgcse</B>]Will create a dump of iCode's, after global subexpression
1312 elimination, into a file named <I>&lt;source filename&gt;.dumpgcse.</I>
1313 </LI>
1314 <LI>[<B>-dumpdeadcode</B>]Will create a dump of iCode's, after deadcode
1315 elimination, into a file named <I>&lt;source filename&gt;.dumpdeadcode.</I>
1316 </LI>
1317 <LI>[<B>-dumploop</B>]Will create a dump of iCode's, after loop optimizations,
1318 into a file named <I>&lt;source filename&gt;.dumploop.</I>
1319 </LI>
1320 <LI>[<B>-dumprange</B>]Will create a dump of iCode's, after live range
1321 analysis, into a file named <I>&lt;source filename&gt;.dumprange.</I>
1322 </LI>
1323 <LI>[<B>-dumlrange</B>]Will dump the life ranges for all symbols
1324 </LI>
1325 <LI>[<B>-dumpregassign</B>]Will create a dump of iCode's, after register
1326 assignment , into a file named <I>&lt;source filename&gt;.dumprassgn.</I>
1327 </LI>
1328 <LI>[<B>-dumplrange</B>]Will create a dump of the live ranges of iTemp's
1329 </LI>
1330 <LI>[<B>-dumpall</B>]Will cause all the above mentioned dumps to be
1331 created.
1332 </LI>
1333 </UL>
1334 <P>
1335
1336 <H2><A NAME="SECTION00043000000000000000">
1337 3.3 MCS51/DS390 Storage Class Language Extensions</A>
1338 </H2>
1339
1340 <P>
1341 In addition to the ANSI storage classes SDCC allows the following
1342 MCS51 specific storage classes.
1343
1344 <P>
1345
1346 <H3><A NAME="SECTION00043100000000000000">
1347 3.3.1 xdata</A>
1348 </H3>
1349
1350 <P>
1351 Variables declared with this storage class will be placed in the extern
1352 RAM. This is the <B>default</B> storage class for Large Memory model,
1353 e.g.:
1354 <BR>
1355 <BR><TT>xdata unsigned char xduc;</TT>
1356
1357 <P>
1358
1359 <H3><A NAME="SECTION00043200000000000000">
1360 3.3.2 data</A>
1361 </H3>
1362
1363 <P>
1364 This is the <B>default</B> storage class for Small Memory model.
1365 Variables declared with this storage class will be allocated in the
1366 internal RAM, e.g.:
1367 <BR>
1368 <BR><TT>data int iramdata;</TT>
1369
1370 <P>
1371
1372 <H3><A NAME="SECTION00043300000000000000">
1373 3.3.3 idata</A>
1374 </H3>
1375
1376 <P>
1377 Variables declared with this storage class will be allocated into
1378 the indirectly addressable portion of the internal ram of a 8051,
1379 e.g.:
1380 <BR>
1381 <BR><TT>idata int idi;</TT>
1382
1383 <P>
1384
1385 <H3><A NAME="SECTION00043400000000000000">
1386 3.3.4 bit</A>
1387 </H3>
1388
1389 <P>
1390 This is a data-type and a storage class specifier. When a variable
1391 is declared as a bit , it is allocated into the bit addressable memory
1392 of 8051, e.g.:
1393 <BR>
1394 <BR><TT>bit iFlag;</TT>
1395
1396 <P>
1397
1398 <H3><A NAME="SECTION00043500000000000000">
1399 3.3.5 sfr / sbit</A>
1400 </H3>
1401
1402 <P>
1403 Like the bit keyword, <I>sfr / sbit</I> signifies both a data-type
1404 and storage class, they are used to describe the special function
1405 registers and special bit variables of a 8051, eg:
1406 <BR>
1407 <BR><TT>sfr at 0x80 P0; /* special function register P0 at location
1408 0x80 */</TT>&nbsp;
1409 <BR><TT>sbit at 0xd7 CY; /* CY (Carry Flag) */</TT>
1410
1411 <P>
1412
1413 <H2><A NAME="SECTION00044000000000000000">
1414 3.4 Pointers</A>
1415 </H2>
1416
1417 <P>
1418 SDCC allows (via language extensions) pointers to explicitly point
1419 to any of the memory spaces of the 8051. In addition to the explicit
1420 pointers, the compiler also allows a <I>_generic</I> class of pointers
1421 which can be used to point to any of the memory spaces.
1422 <BR>
1423 <BR>
1424 Pointer declaration examples.
1425 <BR>
1426 <BR><TT>/* pointer physically in xternal ram pointing to object
1427 in internal ram */ </TT>&nbsp;
1428 <BR><TT>data unsigned char * xdata p;</TT>&nbsp;
1429 <BR>&nbsp;
1430 <BR><TT>/* pointer physically in code rom pointing to data in xdata
1431 space */ </TT>&nbsp;
1432 <BR><TT>xdata unsigned char * code p;</TT>&nbsp;
1433 <BR>&nbsp;
1434 <BR><TT>/* pointer physically in code space pointing to data in
1435 code space */ </TT>&nbsp;
1436 <BR><TT>code unsigned char * code p;</TT>&nbsp;
1437 <BR>&nbsp;
1438 <BR><TT>/* the folowing is a generic pointer physically located
1439 in xdata space */</TT>&nbsp;
1440 <BR><TT>char * xdata p;</TT>
1441 <BR>
1442 <BR>
1443 Well you get the idea. For compatibility with the previous version
1444 of the compiler, the following syntax for pointer declaration is still
1445 supported but will disappear int the near future.
1446 <BR>
1447 <BR><TT>unsigned char _xdata *ucxdp; /* pointer to data in external
1448 ram */ </TT>&nbsp;
1449 <BR><TT>unsigned char _data &nbsp;*ucdp ; /* pointer to data in internal
1450 ram */ </TT>&nbsp;
1451 <BR><TT>unsigned char _code &nbsp;*uccp ; /* pointer to data in R/O
1452 code space */</TT>&nbsp;
1453 <BR><TT>unsigned char _idata *uccp; &nbsp;/* pointer to upper 128
1454 bytes of ram */</TT>
1455 <BR>
1456 <BR>
1457 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
1458 '_generic' pointers. These type of pointers can also to be explicitly
1459 declared.
1460 <BR>
1461 <BR><TT>unsigned char _generic *ucgp;</TT>
1462 <BR>
1463 <BR>
1464 The highest order byte of the generic pointers contains the data space
1465 information. Assembler support routines are called whenever data is
1466 stored or retrieved using _generic pointers. These are useful for
1467 developing reusable library routines. Explicitly specifying the pointer
1468 type will generate the most efficient code. Pointers declared using
1469 a mixture of OLD/NEW style could have unpredictable results.
1470
1471 <P>
1472
1473 <H2><A NAME="SECTION00045000000000000000">
1474 3.5 Parameters &amp; Local Variables</A>
1475 </H2>
1476
1477 <P>
1478 Automatic (local) variables and parameters to functions can either
1479 be placed on the stack or in data-space. The default action of the
1480 compiler is to place these variables in the internal RAM ( for small
1481 model) or external RAM (for Large model). They can be placed on the
1482 stack either by using the <I>-stack-auto</I> compiler option or by
1483 using the 'reentrant' keyword in the function declaration, e.g.:
1484 <BR>
1485 <BR><TT>unsigned char foo( char i) reentrant </TT>&nbsp;
1486 <BR><TT>{ </TT>&nbsp;
1487 <BR><TT>... </TT>&nbsp;
1488 <BR><TT>}</TT>&nbsp;
1489 <BR>
1490 <BR>
1491 Note that when the parameters &amp; local variables are declared in the
1492 internal/external ram the functions are non-reentrant. Since stack
1493 space on 8051 is limited the <I>'reentrant'</I> keyword or the <I>-stack-auto</I>
1494 option should be used sparingly. Note the reentrant keyword just means
1495 that the parameters &amp; local variables will be allocated to the stack,
1496 it DOES NOT mean that the function is register bank independent.
1497
1498 <P>
1499 When compiled with the default option (i.e. non-reentrant ), local
1500 variables can be assigned storage classes and absolute addresses,
1501 e.g.: (jwk: pending: this is obsolete and need a rewrite)
1502 <BR>
1503 <BR><TT>unsigned char foo() {</TT>
1504
1505 <P>
1506 <TT>xdata unsigned char i;</TT>
1507
1508 <P>
1509 <TT>bit bvar;</TT>
1510
1511 <P>
1512 <TT>data at 0x31 unsiged char j;</TT>
1513
1514 <P>
1515 <TT>... </TT>&nbsp;
1516 <BR><TT>}</TT>
1517
1518 <P>
1519 In the above example the variable <I>i</I> will be allocated in the
1520 external ram, <I>bvar</I> in bit addressable space and <I>j</I> in
1521 internal ram. When compiled with the <I>-stack-auto</I> or when a
1522 function is declared as <I>'reentrant'</I> local variables cannot
1523 be assigned storage classes or absolute addresses.
1524
1525 <P>
1526 Parameters however are not allowed any storage class, (storage classes
1527 for parameters will be ignored), their allocation is governed by the
1528 memory model in use , and the reentrancy options.
1529
1530 <P>
1531
1532 <H2><A NAME="SECTION00046000000000000000">
1533 3.6 Overlaying</A>
1534 </H2>
1535
1536 <P>
1537 For non-reentrant functions SDCC will try to reduce internal ram space
1538 usage by overlaying parameters and local variables of a function (if
1539 possible). Parameters and local variables of a function will be allocated
1540 to an overlayable segment if the function has <I>no other function
1541 calls and the function is non-reentrant and the memory model is small.</I>
1542 If an explicit storage class is specified for a local variable , it
1543 will NOT be overplayed.
1544
1545 <P>
1546 Note that the compiler (not the linkage editor) makes the decision
1547 for overlaying the data items. Functions that are called from an interrupt
1548 service routine should be preceded by a #pragma NOOVERLAY if they
1549 are not reentrant Along the same lines the compiler does not do any
1550 processing with the inline assembler code so the compiler might incorrectly
1551 assign local variables and parameters of a function into the overlay
1552 segment if the only function call from a function is from inline assembler
1553 code, it is safe to use the #pragma NOOVERLAY for functions which
1554 call other functions using inline assembler code.
1555
1556 <P>
1557 Parameters and Local variables of functions that contain 16 or 32
1558 bit multiplication or division will NOT be overlayed since these are
1559 implemented using external functions, e.g.:
1560 <BR>
1561 <BR><TT>#pragma SAVE </TT>&nbsp;
1562 <BR><TT>#pragma NOOVERLAY </TT>&nbsp;
1563 <BR><TT>void set_error( unsigned char errcd) </TT>&nbsp;
1564 <BR><TT>{</TT>
1565
1566 <P>
1567 <TT>P3 = errcd;</TT>&nbsp;
1568 <BR><TT>} </TT>&nbsp;
1569 <BR><TT>#pragma RESTORE </TT>&nbsp;
1570 <BR><TT>void some_isr () interrupt 2 using 1 </TT>&nbsp;
1571 <BR><TT>{</TT>
1572
1573 <P>
1574 <TT>...</TT>
1575
1576 <P>
1577 <TT>set_error(10);</TT>
1578
1579 <P>
1580 <TT>... </TT>&nbsp;
1581 <BR><TT>}</TT>
1582
1583 <P>
1584 In the above example the parameter <I>errcd</I> for the function <I>set_error</I>
1585 would be assigned to the overlayable segment (if the #pragma NOOVERLAY
1586 was not present) , this could cause unpredictable runtime behavior
1587 when called from an ISR. The pragma NOOVERLAY ensures that the parameters
1588 and local variables for the function are NOT overlayed.
1589
1590 <P>
1591
1592 <H2><A NAME="SECTION00047000000000000000">
1593 3.7 Interrupt Service Routines</A>
1594 </H2>
1595
1596 <P>
1597 SDCC allows interrupt service routines to be coded in C, with some
1598 extended keywords.
1599
1600 <P>
1601 <FONT SIZE="-1">void timer_isr (void) interrupt 2 using 1 </FONT>
1602 <BR><FONT SIZE="-1">{ </FONT>
1603 <BR><FONT SIZE="-1">.. </FONT>
1604 <BR><FONT SIZE="-1">}</FONT>
1605 <P>
1606
1607
1608 <P>
1609 The number following the 'interrupt' keyword is the interrupt number
1610 this routine will service. The compiler will insert a call to this
1611 routine in the interrupt vector table for the interrupt number specified.
1612 The 'using' keyword is used to tell the compiler to use the specified
1613 register bank (8051 specific) when generating code for this function.
1614 Note that when some function is called from an interrupt service routine
1615 it should be preceded by a #pragma NOOVERLAY (if it is not reentrant).
1616 A special note here, int (16 bit) and long (32 bit) integer division,
1617 multiplication &amp; modulus operations are implemented using external
1618 support routines developed in ANSI-C, if an interrupt service routine
1619 needs to do any of these operations then the support routines (as
1620 mentioned in a following section) will have to recompiled using the
1621 -stack-auto option and the source file will need to be compiled using
1622 the -int-long-rent compiler option.
1623
1624 <P>
1625 If you have multiple source files in your project, interrupt service
1626 routines can be present in any of them, but a prototype of the isr
1627 MUST be present in the file that contains the function <I>'main'</I>.
1628
1629 <P>
1630 Interrupt Numbers and the corresponding address &amp; descriptions for
1631 the Standard 8051 are listed below. SDCC will automatically adjust
1632 the interrupt vector table to the maximum interrupt number specified.
1633 <BR>
1634 <P>
1635 <TABLE CELLPADDING=3 BORDER="1">
1636 <TR><TD ALIGN="CENTER">Interrupt #</TD>
1637 <TD ALIGN="CENTER">Description</TD>
1638 <TD ALIGN="CENTER">Vector Address</TD>
1639 </TR>
1640 <TR><TD ALIGN="CENTER">0</TD>
1641 <TD ALIGN="CENTER">External 0</TD>
1642 <TD ALIGN="CENTER">0x0003</TD>
1643 </TR>
1644 <TR><TD ALIGN="CENTER">1</TD>
1645 <TD ALIGN="CENTER">Timer 0</TD>
1646 <TD ALIGN="CENTER">0x000B</TD>
1647 </TR>
1648 <TR><TD ALIGN="CENTER">2</TD>
1649 <TD ALIGN="CENTER">External 1</TD>
1650 <TD ALIGN="CENTER">0x0013</TD>
1651 </TR>
1652 <TR><TD ALIGN="CENTER">3</TD>
1653 <TD ALIGN="CENTER">Timer 1</TD>
1654 <TD ALIGN="CENTER">0x001B</TD>
1655 </TR>
1656 <TR><TD ALIGN="CENTER">4</TD>
1657 <TD ALIGN="CENTER">Serial</TD>
1658 <TD ALIGN="CENTER">0x0023</TD>
1659 </TR>
1660 </TABLE>
1661 <BR>
1662 <P>
1663 If the interrupt service routine is defined without <I>'using'</I>
1664 a register bank or with register bank 0 (using 0), the compiler will
1665 save the registers used by itself on the stack (upon entry and restore
1666 them at exit), however if such an interrupt service routine calls
1667 another function then the entire register bank will be saved on the
1668 stack. This scheme may be advantageous for small interrupt service
1669 routines which have low register usage.
1670
1671 <P>
1672 If the interrupt service routine is defined to be using a specific
1673 register bank then only ``a'',''b'' &amp; ``dptr'' are save
1674 and restored, if such an interrupt service routine calls another function
1675 (using another register bank) then the entire register bank of the
1676 called function will be saved on the stack. This scheme is recommended
1677 for larger interrupt service routines.
1678
1679 <P>
1680 Calling other functions from an interrupt service routine is not recommended
1681 avoid it if possible.
1682
1683 <P>
1684
1685 <H2><A NAME="SECTION00048000000000000000">
1686 3.8 Critical Functions</A>
1687 </H2>
1688
1689 <P>
1690 A special keyword may be associated with a function declaring it as
1691 '<I>critical</I>'. SDCC will generate code to disable all interrupts
1692 upon entry to a critical function and enable them back before returning.
1693 Note that nesting critical functions may cause unpredictable results.
1694 <BR>
1695 <BR>
1696 eg:
1697 <BR>
1698 <BR><FONT SIZE="-1">int foo () critical </FONT>
1699 <BR><FONT SIZE="-1">{ </FONT>
1700 <BR><FONT SIZE="-1">... </FONT>
1701 <BR><FONT SIZE="-1">... </FONT>
1702 <BR><FONT SIZE="-1">}</FONT>
1703 <BR>
1704 <BR>
1705 The critical attribute maybe used with other attributes like <I>reentrant.</I>
1706
1707 <P>
1708
1709 <H2><A NAME="SECTION00049000000000000000">
1710 3.9 Naked Functions</A>
1711 </H2>
1712
1713 <P>
1714 A special keyword may be associated with a function declaring it as
1715 <I>'_naked'.</I> The <I>'_naked'</I> function modifier attribute
1716 prevents the compiler from generating prologue and epilogue code for
1717 that function. This means that the user is entirely responsible for
1718 such things as saving any registers that may need to be preserved,
1719 selecting the proper register bank, generating the <I>'return'</I>
1720 instruction at the end, etc. Practically, this means that the contents
1721 of the function must be written in inline assembler. This is particularly
1722 useful for interrupt functions, which can have a large (and often
1723 unnecessary) prologue/epilogue. For example, compare the code generated
1724 by these two functions:
1725 <BR>
1726 <BR>
1727 data unsigned char counter;
1728 <BR>
1729 void simpleIterrupt(void) interrupt 1
1730 <BR>{
1731
1732 <P>
1733 counter++;
1734 <BR>}
1735 <BR>
1736 <BR>
1737 void nakedInterrupt(void) interrupt 2 _naked
1738 <BR>{
1739
1740 <P>
1741 _asm
1742
1743 <P>
1744 &nbsp;&nbsp; inc&nbsp; _counter
1745
1746 <P>
1747 &nbsp;&nbsp; reti&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ; MUST explicitly include ret in _naked
1748 function.
1749
1750 <P>
1751 _endasm;
1752 <BR>}
1753 <BR>
1754 <BR>
1755 For an 8051 target, the generated simpleInterrupt looks like:
1756 <BR>
1757 <BR>
1758 _simpleIterrupt:
1759
1760 <P>
1761 push&nbsp;&nbsp;&nbsp; acc
1762
1763 <P>
1764 push&nbsp;&nbsp;&nbsp; b
1765
1766 <P>
1767 push&nbsp;&nbsp;&nbsp; dpl
1768
1769 <P>
1770 push&nbsp;&nbsp;&nbsp; dph
1771
1772 <P>
1773 push&nbsp;&nbsp;&nbsp; psw
1774
1775 <P>
1776 mov&nbsp;&nbsp;&nbsp;&nbsp; psw,#0x00
1777
1778 <P>
1779 inc&nbsp;&nbsp;&nbsp;&nbsp; _counter
1780
1781 <P>
1782 pop&nbsp;&nbsp;&nbsp;&nbsp; psw
1783
1784 <P>
1785 pop&nbsp;&nbsp;&nbsp;&nbsp; dph
1786
1787 <P>
1788 pop&nbsp;&nbsp;&nbsp;&nbsp; dpl
1789
1790 <P>
1791 pop&nbsp;&nbsp;&nbsp;&nbsp; b
1792
1793 <P>
1794 pop&nbsp;&nbsp;&nbsp;&nbsp; acc
1795
1796 <P>
1797 reti
1798 <BR>
1799 <BR>
1800 whereas nakedInterrupt looks like:
1801 <BR>
1802 <BR>
1803 _nakedInterrupt:
1804
1805 <P>
1806 inc&nbsp; _counter
1807
1808 <P>
1809 reti&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ; MUST explicitly include ret(i) in _naked function.
1810 <BR>
1811 <BR>
1812 While there is nothing preventing you from writing C code inside a
1813 _naked function, there are many ways to shoot yourself in the foot
1814 doing this, and is is recommended that you stick to inline assembler.
1815
1816 <P>
1817
1818 <H2><A NAME="SECTION000410000000000000000">
1819 3.10 Functions using private banks</A>
1820 </H2>
1821
1822 <P>
1823 The <I>'using'</I> attribute (which tells the compiler to use a register
1824 bank other than the default bank zero) should only be applied to 'interrupt'
1825 functions (see note A below). This will in most circumstances make
1826 the generated ISR code more efficient since it will not have to save
1827 registers on the stack.
1828
1829 <P>
1830 The <I>'using'</I> attribute will have no effect on the generated
1831 code for a <I>non-'interrupt'</I> function (but may occasionally be
1832 useful anyway<A NAME="tex2html1"
1833   HREF="#foot456"><SUP>1</SUP></A>).
1834 <BR>(jwk: todo: I don't think this has been done yet)
1835
1836 <P>
1837 An 'interrupt' function using a non-zero bank will assume that it
1838 can trash that register bank, and will not save it. Since high-priority
1839 interrupts can interrupt low-priority ones on the 8051 and friends,
1840 this means that if a high-priority ISR 'using' a particular bank occurs
1841 while processing a low-priority ISR 'using' the same bank, terrible
1842 and bad things can happen. To prevent this, no single register bank
1843 should be 'used' by both a high priority and a low priority ISR. This
1844 is probably most easily done by having all high priority ISRs use
1845 one bank and all low priority ISRs use another. If you have an ISR
1846 which can change priority at runtime, you're on your own: I suggest
1847 using the default bank zero and taking the small performance hit.
1848
1849 <P>
1850 It is most efficient if your ISR calls no other functions. If your
1851 ISR must call other functions, it is most efficient if those functions
1852 use the same bank as the ISR (see note A below); the next best is
1853 if the called functions use bank zero. It is very inefficient to call
1854 a function using a different, non-zero bank from an ISR.
1855
1856 <P>
1857
1858 <H2><A NAME="SECTION000411000000000000000">
1859 3.11 Absolute Addressing</A>
1860 </H2>
1861
1862 <P>
1863 Data items can be assigned an absolute address with the <I>at &lt;address&gt;</I>
1864 keyword, in addition to a storage class.
1865
1866 <P>
1867 eg.
1868
1869 <P>
1870 <FONT SIZE="-1">xdata at 0x8000 unsigned char PORTA_8255 ;</FONT>
1871 <P>
1872
1873
1874 <P>
1875 In the above example the <I>PORTA_8255</I> will be allocated to the
1876 location 0x8000 of the external ram.
1877
1878 <P>
1879 Note that is this feature is provided to give the programmer access
1880 to <I>memory mapped</I> devices attached to the controller. The compiler
1881 does not actually reserve any space for variables declared in this
1882 way (they are implemented with an equate in the assembler), thus it
1883 is left to the programmer to make sure there are no overlaps with
1884 other variables that are declared without the absolute address, the
1885 assembler listing file (.lst) and the linker output files (&lt;filename&gt;.rst)
1886 and (&lt;filename&gt;.map) are a good places to look for such overlaps.
1887
1888 <P>
1889 Absolute address can be specified for variables in all storage classes.
1890
1891 <P>
1892 <FONT SIZE="-1">eg.</FONT>
1893 <P>
1894
1895
1896 <P>
1897 <FONT SIZE="-1">bit at 0x02 bvar;</FONT>
1898 <P>
1899
1900
1901 <P>
1902 The above example will allocate the variable at offset 0x02 in the
1903 bit-addressable space. There is no real advantage to assigning absolute
1904 addresses to variables in this manner , unless you want strict control
1905 over all the variables allocated.
1906
1907 <P>
1908
1909 <H2><A NAME="SECTION000412000000000000000">
1910 3.12 Startup Code</A>
1911 </H2>
1912
1913 <P>
1914 The compiler inserts a jump to the C routine <B>_sdcc__external__startup()</B>
1915 at the start of the CODE area. This routine can be found in the file
1916 <B>SDCCDIR/sdcc51lib/_startup.c</B>, by default this routine returns
1917 0, if this routine returns a non-zero value , the static &amp; global
1918 variable initialization will be skipped and the function main will
1919 be invoked, other wise static &amp; global variables will be initialized
1920 before the function main is invoked. You could add a <B>_sdcc__external__startup()</B>
1921 routine to your program to override the default if you needed to setup
1922 hardware or perform some other critical operation prior to static
1923 &amp; global variable initialization.
1924
1925 <P>
1926
1927 <H2><A NAME="SECTION000413000000000000000">
1928 3.13 Inline Assembler Code</A>
1929 </H2>
1930
1931 <P>
1932 SDCC allows the use of in-line assembler with a few restriction as
1933 regards labels. All labels defined within inline assembler code HAS
1934 TO BE of the <I>form nnnnn$</I> where nnnn is a number less than
1935 100 (which implies a limit of utmost 100 inline assembler labels <SMALL>PER
1936 FUNCTION)</SMALL>. It is strongly recommended that each assembly instruction
1937 (including labels) be placed in a separate line ( as the example shows).
1938 When the <B><U>-peep-asm</U></B> command line option is used,
1939 the inline assembler code will be passed through the peephole optimizer,
1940 this might cause some unexpected changes in the inline assembler code,
1941 please go throught the peephole optimizer rules defined in file 'SDCCpeeph.def'
1942 carefully before using this option.
1943
1944 <P>
1945 <FONT SIZE="-1">eg</FONT>
1946 <P>
1947
1948
1949 <P>
1950 <FONT SIZE="-1">_asm </FONT>
1951 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;mov b,#10 </FONT>
1952 <BR><FONT SIZE="-1">00001$: </FONT>
1953 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp;djnz b,00001$ </FONT>
1954 <BR><FONT SIZE="-1">_endasm ;</FONT>
1955 <P>
1956
1957
1958 <P>
1959 The inline assembler code can contain any valid code understood by
1960 the assembler (this includes any assembler directives and comment
1961 lines). The compiler does not do any validation of the code within
1962 the <I>_asm ... _endasm;</I> keyword pair.
1963
1964 <P>
1965 Inline assembler code cannot reference any C-Labels however it can
1966 reference labels defined by the inline assembler.
1967
1968 <P>
1969 <FONT SIZE="-1">eg</FONT>
1970 <P>
1971
1972
1973 <P>
1974 <FONT SIZE="-1">foo() { </FONT>
1975 <BR><FONT SIZE="-1">... /* some c code */ </FONT>
1976 <BR><FONT SIZE="-1">_asm </FONT>
1977 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp;; some assembler code </FONT>
1978 <BR><FONT SIZE="-1">&nbsp; &nbsp; ljmp $0003 </FONT>
1979 <BR><FONT SIZE="-1">_endasm ; </FONT>
1980 <BR><FONT SIZE="-1">... /* some more c code */ </FONT>
1981 <BR><FONT SIZE="-1">clabel: &nbsp; /* inline assembler cannot reference this label
1982 */ </FONT>
1983 <BR><FONT SIZE="-1">_asm </FONT>
1984 <BR><FONT SIZE="-1">&nbsp; &nbsp;$0003: ;label (can be reference by inline assembler
1985 only) </FONT>
1986 <BR><FONT SIZE="-1">_endasm ; </FONT>
1987 <BR><FONT SIZE="-1">... </FONT>
1988 <BR><FONT SIZE="-1">}</FONT>
1989 <P>
1990
1991
1992 <P>
1993 In other words inline assembly code can access labels defined in inline
1994 assembly. The same goes the other way, ie. labels defines in inline
1995 assembly CANNOT be accessed by C statements.
1996
1997 <P>
1998
1999 <H2><A NAME="SECTION000414000000000000000">
2000 3.14 int(16 bit) and long (32 bit ) Support</A>
2001 </H2>
2002
2003 <P>
2004 For signed &amp; unsigned int (16 bit) and long (32 bit) variables, division,
2005 multiplication and modulus operations are implemented by support routines.
2006 These support routines are all developed in ANSI-C to facilitate porting
2007 to other MCUs. The following files contain the described routine,
2008 all of them can be found in the directory SDCCDIR/sdcc51lib
2009
2010 <P>
2011
2012 <UL>
2013 <LI><FONT SIZE="-1">_mulsint.c - signed 16 bit multiplication (calls _muluint)</FONT>
2014 <P>
2015
2016 </LI>
2017 <LI><FONT SIZE="-1">_muluint.c - unsigned 16 bit multiplication</FONT>
2018 <P>
2019
2020 </LI>
2021 <LI><FONT SIZE="-1">_divsint.c - signed 16 bit division (calls _divuint)</FONT>
2022 <P>
2023
2024 </LI>
2025 <LI><FONT SIZE="-1">_divuint.c - unsigned 16 bit division.</FONT>
2026 <P>
2027
2028 </LI>
2029 <LI><FONT SIZE="-1">_modsint.c - signed 16 bit modulus (call _moduint)</FONT>
2030 <P>
2031
2032 </LI>
2033 <LI><FONT SIZE="-1">_moduint.c - unsigned 16 bit modulus.</FONT>
2034 <P>
2035
2036 </LI>
2037 <LI><FONT SIZE="-1">_mulslong.c - signed 32 bit multiplication (calls
2038 _mululong)</FONT>
2039 <P>
2040
2041 </LI>
2042 <LI><FONT SIZE="-1">_mululong.c - unsigned32 bit multiplication.</FONT>
2043 <P>
2044
2045 </LI>
2046 <LI><FONT SIZE="-1">_divslong.c - signed 32 division (calls _divulong)</FONT>
2047 <P>
2048
2049 </LI>
2050 <LI><FONT SIZE="-1">_divulong.c - unsigned 32 division.</FONT>
2051 <P>
2052
2053 </LI>
2054 <LI><FONT SIZE="-1">_modslong.c - signed 32 bit modulus (calls _modulong).</FONT>
2055 <P>
2056
2057 </LI>
2058 <LI><FONT SIZE="-1">_modulong.c - unsigned 32 bit modulus.</FONT>
2059 <P>
2060
2061 </LI>
2062 </UL>
2063 All these routines are compiled as non-reentrant and small model.
2064 Since they are compiled as non-reentrant, interrupt service routines
2065 should not do any of the above operations, if this unavoidable then
2066 the above routines will need to ne compiled with the -stack-auto
2067 option, after which the source program will have to be compiled with
2068 -int-long-rent option.
2069
2070 <P>
2071
2072 <H2><A NAME="SECTION000415000000000000000">
2073 3.15 Floating Point Support</A>
2074 </H2>
2075
2076 <P>
2077 SDCC supports IEEE (single precision 4bytes) floating point numbers.The
2078 floating point support routines are derived from gcc's floatlib.c
2079 and consists of the following routines.
2080
2081 <P>
2082
2083 <UL>
2084 <LI><FONT SIZE="-1">_fsadd.c - add floating point numbers.</FONT>
2085 <P>
2086
2087 </LI>
2088 <LI><FONT SIZE="-1">_fssub.c - subtract floating point numbers</FONT>
2089 <P>
2090
2091 </LI>
2092 <LI><FONT SIZE="-1">_fsdiv.c - divide floating point numbers</FONT>
2093 <P>
2094
2095 </LI>
2096 <LI><FONT SIZE="-1">_fsmul.c - multiply floating point numbers</FONT>
2097 <P>
2098
2099 </LI>
2100 <LI><FONT SIZE="-1">_fs2uchar.c - convert floating point to unsigned char</FONT>
2101 <P>
2102
2103 </LI>
2104 <LI><FONT SIZE="-1">_fs2char.c - convert floating point to signed char.</FONT>
2105 <P>
2106
2107 </LI>
2108 <LI><FONT SIZE="-1">_fs2uint.c - convert floating point to unsigned int.</FONT>
2109 <P>
2110
2111 </LI>
2112 <LI><FONT SIZE="-1">_fs2int.c - convert floating point to signed int.</FONT>
2113 <P>
2114
2115 </LI>
2116 <LI><FONT SIZE="-1">_fs2ulong.c - convert floating point to unsigned long.</FONT>
2117 <P>
2118
2119 </LI>
2120 <LI><FONT SIZE="-1">_fs2long.c - convert floating point to signed long.</FONT>
2121 <P>
2122
2123 </LI>
2124 <LI><FONT SIZE="-1">_uchar2fs.c - convert unsigned char to floating point</FONT>
2125 <P>
2126
2127 </LI>
2128 <LI><FONT SIZE="-1">_char2fs.c - convert char to floating point number</FONT>
2129 <P>
2130
2131 </LI>
2132 <LI><FONT SIZE="-1">_uint2fs.c - convert unsigned int to floating point</FONT>
2133 <P>
2134
2135 </LI>
2136 <LI><FONT SIZE="-1">_int2fs.c - convert int to floating point numbers</FONT>
2137 <P>
2138
2139 </LI>
2140 <LI><FONT SIZE="-1">_ulong2fs.c - convert unsigned long to floating point
2141 number</FONT>
2142 <P>
2143
2144 </LI>
2145 <LI><FONT SIZE="-1">_long2fs.c - convert long to floating point number.</FONT>
2146 <P>
2147
2148 </LI>
2149 </UL>
2150 Note if all these routines are used simultaneously the data space
2151 might overflow. For serious floating point usage it is strongly recommended
2152 that the Large model be used (in which case the floating point routines
2153 mentioned above will need to recompiled with the -model-Large option)
2154
2155 <P>
2156
2157 <H2><A NAME="SECTION000416000000000000000">
2158 3.16 MCS51 Memory Models</A>
2159 </H2>
2160
2161 <P>
2162 SDCC allows two memory models for MCS51 code, small and large. Modules
2163 compiled with different memory models should never be combined together
2164 or the results would be unpredictable. The library routines supplied
2165 with the compiler are compiled as both small and large. The compiled
2166 library modules are contained in seperate directories as small and
2167 large so that you can link to either set. In general the use of the
2168 large model is discouraged.
2169
2170 <P>
2171 When the large model is used all variables declared without a storage
2172 class will be allocated into the external ram, this includes all parameters
2173 and local variables (for non-reentrant functions). When the small
2174 model is used variables without storage class are allocated in the
2175 internal ram.
2176
2177 <P>
2178 Judicious usage of the processor specific storage classes and the
2179 'reentrant' function type will yield much more efficient code, than
2180 using the large-model. Several optimizations are disabled when the
2181 program is compiled using the large model, it is therefore strongly
2182 recommdended that the small model be used unless absolutely required.
2183
2184 <P>
2185
2186 <H2><A NAME="SECTION000417000000000000000">
2187 3.17 Flat 24 bit Addressing Model</A>
2188 </H2>
2189
2190 <P>
2191 This option generates code for the 24 bit contiguous addressing mode
2192 of the Dallas DS80C390 part. In this mode, up to four meg of external
2193 RAM or code space can be directly addressed. See the data sheets at
2194 www.dalsemi.com for further information on this part.
2195
2196 <P>
2197 In older versions of the compiler, this option was used with the MCS51
2198 code generator (-mmcs51). Now, however, the '390 has it's own code
2199 generator, selected by the -mds390 switch. This code generator currently
2200 supports only the flat24 model, but the -model-flat24 switch is still
2201 required, in case later versions of the code generator support other
2202 models (such as the paged mode of the '390). The combination of -mmcs51
2203 and -model-flat24 is now depracated.
2204
2205 <P>
2206 Note that the compiler does not generate any code to place the processor
2207 into24 bitmode (it defaults to 8051 compatible mode). Boot loader
2208 or similar code must ensure that the processor is in 24 bit contiguous
2209 addressing mode before calling the SDCC startup code.
2210
2211 <P>
2212 Like the -model-large option, variables will by default be placed
2213 into the XDATA segment.
2214
2215 <P>
2216 Segments may be placed anywhere in the 4 meg address space using the
2217 usual -*-loc options. Note that if any segments are located above
2218 64K, the -r flag must be passed to the linker to generate the proper
2219 segment relocations, and the Intel HEX output format must be used.
2220 The -r flag can be passed to the linker by using the option -Wl-r
2221 on the sdcc command line.
2222
2223 <P>
2224
2225 <H2><A NAME="SECTION000418000000000000000">
2226 3.18 Defines Created by the Compiler</A>
2227 </H2>
2228
2229 <P>
2230 The compiler creates the following #defines.
2231
2232 <P>
2233
2234 <UL>
2235 <LI>SDCC - this Symbol is always defined.
2236 </LI>
2237 <LI>SDCC_STACK_AUTO - this symbol is defined when -stack-auto option
2238 is used.
2239 </LI>
2240 <LI>SDCC_MODEL_SMALL - when small model is used.
2241 </LI>
2242 <LI>SDCC_MODEL_LARGE - when -model-large is used.
2243 </LI>
2244 <LI>SDCC_USE_XSTACK - when -xstack option is used.
2245 </LI>
2246 </UL>
2247
2248 <P>
2249
2250 <H1><A NAME="SECTION00050000000000000000">
2251 4 SDCC Technical Data</A>
2252 </H1>
2253
2254 <P>
2255
2256 <H2><A NAME="SECTION00051000000000000000">
2257 4.1 Optimizations</A>
2258 </H2>
2259
2260 <P>
2261 SDCC performs a a host of standard optimizations in addition to some
2262 MCU specific optimizations.
2263
2264 <P>
2265
2266 <H3><A NAME="SECTION00051100000000000000">
2267 4.1.1 Sub-expression Elimination</A>
2268 </H3>
2269
2270 <P>
2271 The compiler does <I>local and global</I> common subexpression elimination.
2272
2273 <P>
2274 <TT><FONT SIZE="-2">eg. </FONT></TT>
2275 <P>
2276
2277
2278 <P>
2279 <FONT SIZE="-1">i = x + y + 1;</FONT>
2280 <BR>
2281 j <FONT SIZE="-1">= x + y;</FONT>
2282 <P>
2283
2284
2285 <P>
2286 will be translated to
2287
2288 <P>
2289 <FONT SIZE="-1">iTemp = x + y </FONT>
2290 <BR><FONT SIZE="-1">i = iTemp + 1 </FONT>
2291 <BR><FONT SIZE="-1">j = iTemp</FONT>
2292 <P>
2293
2294
2295 <P>
2296 Some subexpressions are not as obvious as the above example.
2297
2298 <P>
2299 eg.
2300
2301 <P>
2302 <FONT SIZE="-1">a-&gt;b[i].c = 10; </FONT>
2303 <BR><FONT SIZE="-1">a-&gt;b[i].d = 11;</FONT>
2304 <P>
2305
2306
2307 <P>
2308 In this case the address arithmetic <I>a-&gt;b[i]</I> will be computed
2309 only once; the equivalent code in C would be.
2310
2311 <P>
2312 <FONT SIZE="-1">iTemp = a-&gt;b[i]; </FONT>
2313 <BR><FONT SIZE="-1">iTemp.c = 10; </FONT>
2314 <BR><FONT SIZE="-1">iTemp.d = 11;</FONT>
2315 <P>
2316
2317
2318 <P>
2319 The compiler will try to keep these temporary variables in registers.
2320
2321 <P>
2322
2323 <H3><A NAME="SECTION00051200000000000000">
2324 4.1.2 Dead-Code Elimination</A>
2325 </H3>
2326
2327 <P>
2328 eg.
2329
2330 <P>
2331 <FONT SIZE="-1">int global; </FONT>
2332 <BR><FONT SIZE="-1">void f () { </FONT>
2333 <BR><FONT SIZE="-1">&nbsp;&nbsp;int i; </FONT>
2334 <BR><FONT SIZE="-1">&nbsp;&nbsp;i = 1; &nbsp;&nbsp;&nbsp;/* dead store */ </FONT>
2335 <BR><FONT SIZE="-1">&nbsp;&nbsp;global = 1; /* dead store */ </FONT>
2336 <BR><FONT SIZE="-1">&nbsp;&nbsp;global = 2; </FONT>
2337 <BR><FONT SIZE="-1">&nbsp;&nbsp;return; </FONT>
2338 <BR><FONT SIZE="-1">&nbsp;&nbsp;global = 3; /* unreachable */ </FONT>
2339 <BR><FONT SIZE="-1">}</FONT>
2340 <P>
2341
2342
2343 <P>
2344 will be changed to
2345
2346 <P>
2347 <FONT SIZE="-1">int global; void f () </FONT>
2348 <BR><FONT SIZE="-1">{ &nbsp; &nbsp; </FONT>
2349 <BR><FONT SIZE="-1">&nbsp;global = 2; &nbsp; &nbsp; </FONT>
2350 <BR><FONT SIZE="-1">&nbsp;return; </FONT>
2351 <BR><FONT SIZE="-1">}</FONT>
2352 <P>
2353
2354
2355 <P>
2356
2357 <H3><A NAME="SECTION00051300000000000000">
2358 4.1.3 Copy-Propagation</A>
2359 </H3>
2360
2361 <P>
2362 eg.
2363
2364 <P>
2365 <FONT SIZE="-1">int f() { </FONT>
2366 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;int i, j; </FONT>
2367 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;i = 10; </FONT>
2368 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;j = i; </FONT>
2369 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;return j; </FONT>
2370 <BR><FONT SIZE="-1">}</FONT>
2371 <P>
2372
2373
2374 <P>
2375 will be changed to
2376
2377 <P>
2378 <FONT SIZE="-1">int f() { </FONT>
2379 <BR><FONT SIZE="-1">&nbsp; &nbsp; int i,j; </FONT>
2380 <BR><FONT SIZE="-1">&nbsp; &nbsp; i = 10; </FONT>
2381 <BR><FONT SIZE="-1">&nbsp; &nbsp; j = 10; </FONT>
2382 <BR><FONT SIZE="-1">&nbsp; &nbsp; return 10; </FONT>
2383 <BR><FONT SIZE="-1">}</FONT>
2384 <P>
2385
2386
2387 <P>
2388 Note: the dead stores created by this copy propagation will be eliminated
2389 by dead-code elimination.
2390
2391 <P>
2392
2393 <H3><A NAME="SECTION00051400000000000000">
2394 4.1.4 Loop Optimizations</A>
2395 </H3>
2396
2397 <P>
2398 Two types of loop optimizations are done by SDCC loop invariant lifting
2399 and strength reduction of loop induction variables.In addition to
2400 the strength reduction the optimizer marks the induction variables
2401 and the register allocator tries to keep the induction variables in
2402 registers for the duration of the loop. Because of this preference
2403 of the register allocator , loop induction optimization causes an
2404 increase in register pressure, which may cause unwanted spilling of
2405 other temporary variables into the stack / data space. The compiler
2406 will generate a warning message when it is forced to allocate extra
2407 space either on the stack or data space. If this extra space allocation
2408 is undesirable then induction optimization can be eliminated either
2409 for the entire source file ( with -noinduction option) or for a given
2410 function only (#pragma NOINDUCTION).
2411
2412 <P>
2413
2414 <UL>
2415 <LI><B>Loop Invariant:</B>
2416 </LI>
2417 </UL>
2418 eg
2419
2420 <P>
2421 <FONT SIZE="-1">for (i = 0 ; i &lt; 100 ; i ++) </FONT>
2422 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp;f += k + l;</FONT>
2423 <P>
2424
2425
2426 <P>
2427 changed to
2428
2429 <P>
2430 <FONT SIZE="-1">itemp = k + l; </FONT>
2431 <BR><FONT SIZE="-1">for ( i = 0; i &lt; 100; i++ ) f += itemp;</FONT>
2432 <P>
2433
2434
2435 <P>
2436 As mentioned previously some loop invariants are not as apparent,
2437 all static address computations are also moved out of the loop.
2438
2439 <P>
2440
2441 <UL>
2442 <LI><B>Strength Reduction :</B>
2443 </LI>
2444 </UL>
2445 This optimization substitutes an expression by a cheaper expression.
2446
2447 <P>
2448 eg.
2449
2450 <P>
2451 <FONT SIZE="-1">for (i=0;i &lt; 100; i++) ar[i*5] = i*3;</FONT>
2452 <P>
2453
2454
2455 <P>
2456 changed to
2457
2458 <P>
2459 <FONT SIZE="-1">itemp1 = 0; </FONT>
2460 <BR><FONT SIZE="-1">itemp2 = 0; </FONT>
2461 <BR><FONT SIZE="-1">for (i=0;i&lt; 100;i++) { </FONT>
2462 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp;ar[itemp1] = itemp2; </FONT>
2463 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp;itemp1 += 5; </FONT>
2464 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp;itemp2 += 3; </FONT>
2465 <BR><FONT SIZE="-1">}</FONT>
2466 <P>
2467
2468
2469 <P>
2470 The more expensive multiplication is changed to a less expensive addition.
2471
2472 <P>
2473
2474 <H3><A NAME="SECTION00051500000000000000">
2475 4.1.5 Loop Reversing:</A>
2476 </H3>
2477
2478 <P>
2479 This optimization is done to reduce the overhead of checking loop
2480 boundaries for every iteration. Some simple loops can be reversed
2481 and implemented using a ``decrement and jump if not zero'' instruction.
2482 SDCC checks for the following criterion to determine if a loop is
2483 reversible (note: more sophisticated compiers use data-dependency
2484 analysis to make this determination, SDCC uses a more simple minded
2485 analysis).
2486
2487 <P>
2488
2489 <UL>
2490 <LI>The 'for' loop is of the form
2491 <BR>``for ( &lt;symbol&gt; = &lt;expression&gt; ; &lt;sym&gt; [&lt; | &lt;=] &lt;expression&gt;
2492 ; [&lt;sym&gt;++ | &lt;sym&gt; += 1])
2493 <BR>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;for body&gt;''
2494 </LI>
2495 <LI>The &lt;for body&gt; does not contain ``continue'' or 'break''.
2496 </LI>
2497 <LI>All goto's are contained within the loop.
2498 </LI>
2499 <LI>No function calls within the loop.
2500 </LI>
2501 <LI>The loop control variable &lt;sym&gt; is not assigned any value within the
2502 loop
2503 </LI>
2504 <LI>The loop control variable does NOT participate in any arithmetic operation
2505 within the loop.
2506 </LI>
2507 <LI>There are NO switch statements in the loop.
2508 </LI>
2509 </UL>
2510 Note djnz instruction can be used for 8-bit values ONLY, therefore
2511 it is advantageous to declare loop control symbols as either 'char',
2512 ofcourse this may not be possible on all situations.
2513
2514 <P>
2515
2516 <H3><A NAME="SECTION00051600000000000000">
2517 4.1.6 Algebraic Simplifications</A>
2518 </H3>
2519
2520 <P>
2521 SDCC does numerous algebraic simplifications, the following is a small
2522 sub-set of these optimizations.
2523
2524 <P>
2525 <FONT SIZE="-1">eg</FONT> <I></I>
2526 <BR><FONT SIZE="-1">i = j + 0 ; /* changed to */ i = j; </FONT>
2527 <BR><FONT SIZE="-1">i /= 2; /* changed to */ i &gt;&gt;= 1; </FONT>
2528 <BR><FONT SIZE="-1">i = j - j ; /* changed to */ i = 0; </FONT>
2529 <BR><FONT SIZE="-1">i = j / 1 ; /* changed to */ i = j;</FONT>
2530 <P>
2531
2532
2533 <P>
2534 Note the subexpressions given above are generally introduced by macro
2535 expansions or as a result of copy/constant propagation.
2536
2537 <P>
2538
2539 <H3><A NAME="SECTION00051700000000000000">
2540 4.1.7 'switch' Statements</A>
2541 </H3>
2542
2543 <P>
2544 SDCC changes switch statements to jump tables when the following conditions
2545 are true.
2546
2547 <P>
2548
2549 <UL>
2550 <LI>The case labels are in numerical sequence , the labels need not be
2551 in order, and the starting number need not be one or zero.
2552 </LI>
2553 </UL>
2554 eg
2555
2556 <P>
2557 <FONT SIZE="-1">switch(i) {&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;switch (i)
2558 { </FONT>
2559 <BR><FONT SIZE="-1">case 4:... &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;case 1: ...
2560 </FONT>
2561 <BR><FONT SIZE="-1">case 5:... &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;case 2: ...
2562 </FONT>
2563 <BR><FONT SIZE="-1">case 3:... &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;case 3: ...
2564 </FONT>
2565 <BR><FONT SIZE="-1">case 6:... &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;case 4: ...
2566 </FONT>
2567 <BR><FONT SIZE="-1">}&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;}</FONT>
2568 <P>
2569
2570
2571 <P>
2572 Both the above switch statements will be implemented using a jump-table.
2573
2574 <P>
2575
2576 <UL>
2577 <LI>The number of case labels is at least three, since it takes two conditional
2578 statements to handle the boundary conditions.
2579 </LI>
2580 <LI>The number of case labels is less than 84, since each label takes
2581 3 bytes and a jump-table can be utmost 256 bytes long.
2582 </LI>
2583 </UL>
2584 Switch statements which have gaps in the numeric sequence or those
2585 that have more that 84 case labels can be split into more than one
2586 switch statement for efficient code generation.
2587
2588 <P>
2589 eg
2590
2591 <P>
2592 <FONT SIZE="-1">switch (i) { </FONT>
2593 <BR><FONT SIZE="-1">case 1: ... </FONT>
2594 <BR><FONT SIZE="-1">case 2: ... </FONT>
2595 <BR><FONT SIZE="-1">case 3: ... </FONT>
2596 <BR><FONT SIZE="-1">case 4: ... </FONT>
2597 <BR><FONT SIZE="-1">case 9: ... </FONT>
2598 <BR><FONT SIZE="-1">case 10: ... </FONT>
2599 <BR><FONT SIZE="-1">case 11: ... </FONT>
2600 <BR><FONT SIZE="-1">case 12: ... </FONT>
2601 <BR><FONT SIZE="-1">}</FONT>
2602 <P>
2603
2604
2605 <P>
2606 If the above switch statement is broken down into two switch statements
2607
2608 <P>
2609 <FONT SIZE="-1">switch (i) { </FONT>
2610 <BR><FONT SIZE="-1">case 1: ... </FONT>
2611 <BR><FONT SIZE="-1">case 2: ... </FONT>
2612 <BR><FONT SIZE="-1">case 3: ... </FONT>
2613 <BR><FONT SIZE="-1">case 4: ... </FONT>
2614 <BR><FONT SIZE="-1">}</FONT>
2615 <P>
2616
2617
2618 <P>
2619 <FONT SIZE="-1">switch (i) { </FONT>
2620 <BR><FONT SIZE="-1">case 9: ... </FONT>
2621 <BR><FONT SIZE="-1">case 10: ... </FONT>
2622 <BR><FONT SIZE="-1">case 11: ... </FONT>
2623 <BR><FONT SIZE="-1">case 12:... </FONT>
2624 <BR><FONT SIZE="-1">}</FONT>
2625 <P>
2626
2627
2628 <P>
2629 then both the switch statements will be implemented using jump-tables
2630 whereas the unmodified switch statement will not be.
2631
2632 <P>
2633
2634 <H3><A NAME="SECTION00051800000000000000">
2635 4.1.8 Bit-shifting Operations.</A>
2636 </H3>
2637
2638 <P>
2639 Bit shifting is one of the most frequently used operation in embedded
2640 programming. SDCC tries to implement bit-shift operations in the most
2641 efficient way possible.
2642
2643 <P>
2644 eg.
2645
2646 <P>
2647 <FONT SIZE="-1">unsigned char i;</FONT>
2648 <P>
2649
2650
2651 <P>
2652 <FONT SIZE="-1">... </FONT>
2653 <BR><FONT SIZE="-1">i&gt;&gt;= 4; </FONT>
2654 <BR><FONT SIZE="-1">..</FONT>
2655 <P>
2656
2657
2658 <P>
2659 generates the following code.
2660
2661 <P>
2662 <FONT SIZE="-1">mov a,_i </FONT>
2663 <BR><FONT SIZE="-1">swap a </FONT>
2664 <BR><FONT SIZE="-1">anl a,#0x0f </FONT>
2665 <BR><FONT SIZE="-1">mov _i,a</FONT>
2666 <P>
2667
2668
2669 <P>
2670 In general SDCC will never setup a loop if the shift count is known.
2671 Another example
2672
2673 <P>
2674 <FONT SIZE="-1">unsigned int i; </FONT>
2675 <BR><FONT SIZE="-1">... </FONT>
2676 <BR><FONT SIZE="-1">i &gt;&gt;= 9; </FONT>
2677 <BR><FONT SIZE="-1">...</FONT>
2678 <P>
2679
2680
2681 <P>
2682 will generate
2683
2684 <P>
2685 <FONT SIZE="-1">mov a,(_i + 1) </FONT>
2686 <BR><FONT SIZE="-1">mov (_i + 1),#0x00 </FONT>
2687 <BR><FONT SIZE="-1">clr c </FONT>
2688 <BR><FONT SIZE="-1">rrc a </FONT>
2689 <BR><FONT SIZE="-1">mov _i,a</FONT>
2690 <P>
2691
2692
2693 <P>
2694 Note that SDCC stores numbers in <SMALL>LITTLE-ENDIAN</SMALL> format (i.e.
2695 lowest order first)
2696
2697 <P>
2698
2699 <H3><A NAME="SECTION00051900000000000000">
2700 4.1.9 Bit-rotation</A>
2701 </H3>
2702
2703 <P>
2704 A special case of the bit-shift operation is bit rotation, SDCC recognizes
2705 the following expression to be a left bit-rotation.
2706
2707 <P>
2708 <FONT SIZE="-1">unsigned char i; </FONT>
2709 <BR><FONT SIZE="-1">... </FONT>
2710 <BR><FONT SIZE="-1">i = ( ( i &lt;&lt; 1) | ( i &gt;&gt;
2711 7)); </FONT>
2712 <BR><FONT SIZE="-1">...</FONT>
2713 <P>
2714
2715
2716 <P>
2717 will generate the following code.
2718
2719 <P>
2720 <FONT SIZE="-1">mov a,_i </FONT>
2721 <BR><FONT SIZE="-1">rl a </FONT>
2722 <BR><FONT SIZE="-1">mov _i,a</FONT>
2723 <P>
2724
2725
2726 <P>
2727 SDCC uses pattern matching on the parse tree to determine this operation.Variations
2728 of this case will also be recognized as bit-rotation i.e <I>i =
2729 ((i &gt;&gt; 7) | (i &lt;&lt; 1));</I> /*
2730 left-bit rotation */
2731
2732 <P>
2733
2734 <H3><A NAME="SECTION000511000000000000000">
2735 4.1.10 Highest Order Bit</A>
2736 </H3>
2737
2738 <P>
2739 It is frequently required to obtain the highest order bit of an integral
2740 type (long, int, short or char types). SDCC recognizes the following
2741 expression to yield the highest order bit and generates optimized
2742 code for it.
2743
2744 <P>
2745 <FONT SIZE="-1">eg </FONT>
2746 <BR><FONT SIZE="-1">unsigned int gint; </FONT>
2747 <BR><FONT SIZE="-1">foo () { </FONT>
2748 <BR><FONT SIZE="-1">unsigned char hob; </FONT>
2749 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;... </FONT>
2750 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;hob = (gint &gt;&gt; 15) &amp; 1; </FONT>
2751 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;.. </FONT>
2752 <BR><FONT SIZE="-1">}</FONT>
2753 <P>
2754
2755
2756 <P>
2757 Will generate the following code.
2758
2759 <P>
2760 <FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 61
2761 ;&nbsp; hob.c 7 </FONT>
2762 <BR><FONT SIZE="-1">&nbsp;&nbsp; 000A E5*01&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 62&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
2763 mov&nbsp; a,(_gint + 1) </FONT>
2764 <BR><FONT SIZE="-1">&nbsp;&nbsp; 000C 33&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 63&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
2765 rlc&nbsp; a </FONT>
2766 <BR><FONT SIZE="-1">&nbsp;&nbsp; 000D E4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 64&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
2767 clr&nbsp; a </FONT>
2768 <BR><FONT SIZE="-1">&nbsp;&nbsp; 000E 13&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 65&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
2769 rrc&nbsp; a </FONT>
2770 <BR><FONT SIZE="-1">&nbsp;&nbsp; 000F F5*02&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 66&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
2771 mov&nbsp; _foo_hob_1_1,a</FONT>
2772 <P>
2773
2774
2775 <P>
2776 Variations of this case however will NOT be recognized. It is a standard
2777 C expression , so I heartily recommend this be the only way to get
2778 the highest order bit, (it is portable). Of course it will be recognized
2779 even if it is embedded in other expressions.
2780
2781 <P>
2782 <FONT SIZE="-1">eg.</FONT>
2783 <P>
2784
2785
2786 <P>
2787 <FONT SIZE="-1">xyz = gint + ((gint &gt;&gt; 15) &amp; 1);</FONT>
2788 <P>
2789
2790
2791 <P>
2792 will still be recognized.
2793
2794 <P>
2795
2796 <H3><A NAME="SECTION000511100000000000000">
2797 4.1.11 Peep-hole Optimizer</A>
2798 </H3>
2799
2800 <P>
2801 The compiler uses a rule based , pattern matching and re-writing mechanism
2802 for peep-hole optimization. It is inspired by '<I>copt'</I> a peep-hole
2803 optimizer by Christopher W. Fraser (cwfraser@microsoft.com). A default
2804 set of rules are compiled into the compiler, additional rules may
2805 be added with the -peep-file &lt;filename&gt; option. The rule language
2806 is best illustrated with examples.
2807
2808 <P>
2809 <FONT SIZE="-1">replace { </FONT>
2810 <BR><FONT SIZE="-1">mov %1,a </FONT>
2811 <BR><FONT SIZE="-1">mov a,%1 } by { mov %1,a }</FONT>
2812 <P>
2813
2814
2815 <P>
2816 The above rule will the following assembly sequence
2817
2818 <P>
2819 <FONT SIZE="-1">mov r1,a </FONT>
2820 <BR><FONT SIZE="-1">mov a,r1</FONT>
2821 <P>
2822
2823
2824 <P>
2825 to
2826
2827 <P>
2828 <FONT SIZE="-1">mov r1,a</FONT>
2829 <P>
2830
2831
2832 <P>
2833 Note: All occurrences of a '%n' ( pattern variable ) must denote
2834 the same string. With the above rule, the assembly sequence
2835
2836 <P>
2837 <FONT SIZE="-1">mov r1,a </FONT>
2838 <BR><FONT SIZE="-1">mov a,r2</FONT>
2839 <P>
2840
2841
2842 <P>
2843 will remain unmodified. Other special case optimizations may be added
2844 by the user (via -peep-file option), eg. some variants of the 8051
2845 MCU allow only 'AJMP' and 'ACALL' , the following two rules will change
2846 all 'LJMP' &amp; 'LCALL' to 'AJMP' &amp; 'ACALL'.
2847
2848 <P>
2849 <FONT SIZE="-1">replace { lcall %1 } by { acall %1 } </FONT>
2850 <BR><FONT SIZE="-1">replace { ljmp %1 } by { ajmp %1 }</FONT>
2851 <P>
2852
2853
2854 <P>
2855 The inline-assembler' code is also passed through the peep hole optimizer,
2856 thus the peephole optimizer can also be used as an assembly level
2857 macro expander. The rules themselves are MCU dependent whereas the
2858 rule language infra-structure is MCU independent. Peephole optimization
2859 rules for other MCU can be easily programmed using the rule language.
2860
2861 <P>
2862 The syntax for a rule is as follows ,
2863
2864 <P>
2865 <FONT SIZE="-1">rule := replace [ restart ] '{' &lt;assembly sequence&gt; '&#92;n'
2866 </FONT>
2867 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; '}' by '{' '&#92;n'
2868 </FONT>
2869 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &lt;assembly
2870 sequence&gt; '&#92;n' </FONT>
2871 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; '}' [if &lt;functionName&gt;
2872 ] '&#92;n' </FONT>
2873 <BR><FONT SIZE="-1">&lt;assembly sequence&gt; := assembly instruction (each instruction
2874 including labels must be on a separate line).&nbsp; &nbsp;</FONT>
2875 <P>
2876
2877
2878 <P>
2879 The optimizer will apply to the rules one by one from the top in the
2880 sequence of their appearance, it will terminate when all rules are
2881 exhausted. If the '<I>restart</I>' option is specified, then the optimizer
2882 will start matching the rules again from the top, this option for
2883 a rule is expensive (performance), it is intended to be used in situations
2884 where a transformation will trigger the same rule again. A good example
2885 of this the following rule.
2886
2887 <P>
2888 <FONT SIZE="-1">replace restart { </FONT>
2889 <BR><FONT SIZE="-1">pop %1 </FONT>
2890 <BR><FONT SIZE="-1">push %1 } by { </FONT>
2891 <BR><FONT SIZE="-1">; nop </FONT>
2892 <BR><FONT SIZE="-1">}</FONT>
2893 <P>
2894
2895
2896 <P>
2897 Note that the replace pattern cannot be a blank, but can be a comment
2898 line. Without the '<I>restart</I>' option only the inner most 'pop'
2899 'push' pair would be eliminated. i.e.
2900
2901 <P>
2902 <FONT SIZE="-1">pop ar1 </FONT>
2903 <BR><FONT SIZE="-1">pop ar2 </FONT>
2904 <BR><FONT SIZE="-1">push ar2 </FONT>
2905 <BR><FONT SIZE="-1">push ar1</FONT>
2906 <P>
2907
2908
2909 <P>
2910 would result in
2911
2912 <P>
2913 <FONT SIZE="-1">pop ar1 </FONT>
2914 <BR><FONT SIZE="-1">; nop </FONT>
2915 <BR><FONT SIZE="-1">push ar1</FONT>
2916 <P>
2917
2918
2919 <P>
2920 with the '<I>restart</I>' option the rule will be applied again to
2921 the resulting code and the all the '<I>pop' 'push'</I> pairs will
2922 be eliminated to yield
2923
2924 <P>
2925 <FONT SIZE="-1">; nop </FONT>
2926 <BR><FONT SIZE="-1">; nop</FONT>
2927 <P>
2928
2929
2930 <P>
2931 A conditional function can be attached to a rule. Attaching rules
2932 are somewhat more involved, let me illustrate this with an example.
2933
2934 <P>
2935 <FONT SIZE="-1">replace { </FONT>
2936 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp;ljmp %5 </FONT>
2937 <BR><FONT SIZE="-1">%2:} by { </FONT>
2938 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp;sjmp %5 </FONT>
2939 <BR><FONT SIZE="-1">%2:} if labelInRange</FONT>
2940 <P>
2941
2942
2943 <P>
2944 The optimizer does a look-up of a function name table defined in function
2945 '<I>callFuncByName'</I> in the source file <I>SDCCpeeph.c</I> , with
2946 the name <I>'labelInRange</I>', if it finds a corresponding entry
2947 the function is called. Note there can be no parameters specified
2948 for these functions, in this case the use of <I>'%5</I>' is crucial,
2949 since the function <I>labelInRange</I> expects to find the label in
2950 that particular variable (the hash table containing the variable bindings
2951 is passed as a parameter). If you want to code more such functions
2952 , take a close look at the function <I>labelInRange</I> and the calling
2953 mechanism in source file <I>SDCCpeeph.c</I>. I know this whole thing
2954 is a little kludgey , may be some day we will have some better means.
2955 If you are looking at this file, you will also see the default rules
2956 that are compiled into the compiler, you can your own rules in the
2957 default set there if you get tired of specifying the <I>-peep-file</I>
2958 option.
2959
2960 <P>
2961
2962 <H2><A NAME="SECTION00052000000000000000">
2963 4.2 Pragmas</A>
2964 </H2>
2965
2966 <P>
2967 SDCC supports the following <I>#pragma</I> directives. This directives
2968 are applicable only at a function level.
2969
2970 <P>
2971
2972 <UL>
2973 <LI><B>SAVE</B> - this will save all the current options.
2974 </LI>
2975 <LI><B>RESTORE</B> - will restore the saved options from the last save.
2976 Note that SAVES &amp; RESTOREs cannot be nested. SDCC uses the same buffer
2977 to save the options each time a SAVE is called.
2978 </LI>
2979 <LI><B>NOGCSE</B> - will stop global subexpression elimination.
2980 </LI>
2981 <LI><B>NOINDUCTION</B> - will stop loop induction optimizations.
2982 </LI>
2983 <LI><B>NOJTBOUND</B> - will not generate code for boundary value checking
2984 , when switch statements are turned into jump-tables.
2985 </LI>
2986 <LI><B>NOOVERLAY</B> - the compiler will not overlay the parameters
2987 and local variables of a function.
2988 </LI>
2989 <LI><B>NOLOOPREVERSE</B> - Will not do loop reversal optimization
2990 </LI>
2991 <LI><B>EXCLUDE NONE | {acc[,b[,dpl[,dph]]]</B> - The exclude
2992 pragma disables generation of pair of push/pop instruction in ISR
2993 function (using interrupt keyword). The directive should be placed
2994 immediately before the ISR function definition and it affects ALL
2995 ISR functions following it. To enable the normal register saving for
2996 ISR functions use ``#pragma EXCLUDE none''
2997 </LI>
2998 <LI><B>CALLEE-SAVES function1[,function2[,function3...]]</B>
2999 - The compiler by default uses a caller saves convention for register
3000 saving across function calls, however this can cause unneccessary
3001 register pushing &amp; popping when calling small functions from larger
3002 functions. This option can be used to switch the register saving convention
3003 for the function names specified. The compiler will not save registers
3004 when calling these functions, extra code will be generated at the
3005 entry &amp; exit for these functions to save &amp; restore the registers
3006 used by these functions, this can SUBSTANTIALLY reduce code &amp; improve
3007 run time performance of the generated code. In future the compiler
3008 (with interprocedural analysis) will be able to determine the appropriate
3009 scheme to use for each function call. If -callee-saves command line
3010 option is used, the function names specified in #pragma CALLEE-SAVES
3011 is appended to the list of functions specified inthe command line.
3012 </LI>
3013 </UL>
3014 The pragma's are intended to be used to turn-off certain optimizations
3015 which might cause the compiler to generate extra stack / data space
3016 to store compiler generated temporary variables. This usually happens
3017 in large functions. Pragma directives should be used as shown in the
3018 following example, they are used to control options &amp; optimizations
3019 for a given function; pragmas should be placed <SMALL>BEFORE</SMALL> and/or
3020 <SMALL>AFTER</SMALL> a function, placing pragma's inside a function body
3021 could have unpredictable results.
3022
3023 <P>
3024 <FONT SIZE="-2">eg</FONT>
3025 <P>
3026
3027
3028 <P>
3029 <FONT SIZE="-2">#pragma SAVE &nbsp; /* save the current settings */
3030 </FONT>
3031 <BR><FONT SIZE="-2">#pragma NOGCSE /* turnoff global subexpression elimination
3032 */ </FONT>
3033 <BR><FONT SIZE="-2">#pragma NOINDUCTION /* turn off induction optimizations
3034 */ </FONT>
3035 <BR><FONT SIZE="-2">int foo () </FONT>
3036 <BR><FONT SIZE="-2">{ </FONT>
3037 <BR><FONT SIZE="-2">&nbsp; &nbsp; ... </FONT>
3038 <BR><FONT SIZE="-2">&nbsp; &nbsp; /* large code */ </FONT>
3039 <BR><FONT SIZE="-2">&nbsp; &nbsp; ... </FONT>
3040 <BR><FONT SIZE="-2">} </FONT>
3041 <BR><FONT SIZE="-2">#pragma RESTORE /* turn the optimizations back on
3042 */</FONT>
3043 <P>
3044
3045
3046 <P>
3047 The compiler will generate a warning message when extra space is allocated.
3048 It is strongly recommended that the SAVE and RESTORE pragma's be used
3049 when changing options for a function.
3050
3051 <P>
3052
3053 <H2><A NAME="SECTION00053000000000000000">
3054 4.3 Library Routines</A>
3055 </H2>
3056
3057 <P>
3058 The following library routines are provided for your convenience.
3059
3060 <P>
3061 <B><FONT SIZE="+1">stdio.h</FONT></B> - Contains the following functions printf
3062 &amp; sprintf these routines are developed by <I>Martijn van Balen
3063 &lt;balen@natlab.research.philips.com&gt;. </I>
3064
3065 <P>
3066 <FONT SIZE="-2">%[flags][width][b|B|l|L]type</FONT>
3067 <P>
3068
3069
3070 <P>
3071 <FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; flags: -&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; left justify
3072 output in specified field width </FONT>
3073 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; +&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; prefix
3074 output with +/- sign if output is signed type </FONT>
3075 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; space&nbsp;&nbsp;&nbsp; prefix output
3076 with a blank if it's a signed positive value </FONT>
3077 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; width:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; specifies
3078 minimum number of characters outputted for numbers </FONT>
3079 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; or
3080 strings. </FONT>
3081 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -
3082 For numbers, spaces are added on the left when needed. </FONT>
3083 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
3084 If width starts with a zero character, zeroes and used </FONT>
3085 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
3086 instead of spaces. </FONT>
3087 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; -
3088 For strings, spaces are are added on the left or right (when </FONT>
3089 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
3090 flag '-' is used) when needed. </FONT>
3091 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </FONT>
3092 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; b/B:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; byte argument
3093 (used by d, u, o, x, X) </FONT>
3094 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; l/L:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; long argument
3095 (used by d, u, o, x, X)</FONT>
3096 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; type:&nbsp; d&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; decimal number
3097 </FONT>
3098 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; u&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned
3099 decimal number </FONT>
3100 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; o&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned
3101 octal number </FONT>
3102 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; x&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned
3103 hexadecimal number (0-9, a-f) </FONT>
3104 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; X&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; unsigned
3105 hexadecimal number (0-9, A-F) </FONT>
3106 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; character
3107 </FONT>
3108 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; s&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; string
3109 (generic pointer) </FONT>
3110 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; p&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; generic
3111 pointer (I:data/idata, C:code, X:xdata, P:paged) </FONT>
3112 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; f&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; float
3113 (still to be implemented)</FONT>
3114 <P>
3115
3116
3117 <P>
3118 Also contains a very simple version of printf (<B>printf_small</B>).
3119 This simplified version of printf supports only the following formats.
3120
3121 <P>
3122 <U><FONT SIZE="-2">format&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;output&nbsp;type&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;argument-type</FONT></U>
3123 <BR><FONT SIZE="-2">%d &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;decimal &nbsp;&nbsp;&nbsp;&nbsp;&nbsp; short/int </FONT>
3124 <BR><FONT SIZE="-2">%ld&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;decimal&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;long </FONT>
3125 <BR><FONT SIZE="-2">%hd&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;decimal&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;char </FONT>
3126 <BR><FONT SIZE="-2">%x&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;hexadecimal&nbsp;&nbsp;&nbsp;&nbsp;short/int </FONT>
3127 <BR><FONT SIZE="-2">%lx&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;hexadecimal&nbsp;&nbsp;&nbsp;&nbsp;long </FONT>
3128 <BR><FONT SIZE="-2">%hx&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;hexadecimal&nbsp;&nbsp;&nbsp;&nbsp;char </FONT>
3129 <BR><FONT SIZE="-2">%o&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;octal&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;short/int
3130 </FONT>
3131 <BR><FONT SIZE="-2">%lo&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;octal&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;long </FONT>
3132 <BR><FONT SIZE="-2">%ho&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;octal&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;char </FONT>
3133 <BR><FONT SIZE="-2">%c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;character&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;char </FONT>
3134 <BR><FONT SIZE="-2">%s&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;character&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;_generic pointer</FONT>
3135 <P>
3136
3137
3138 <P>
3139 The routine is <B>very stack intesive</B> , -stack-after-data parameter
3140 should be used when using this routine, the routine also takes about
3141 1K of code space. It also expects an external function named <I>putchar(char
3142 )</I> to be present (this can be changed). When using the %s format
3143 the string / pointer should be cast to a generic pointer. eg.
3144
3145 <P>
3146 <FONT SIZE="-2">printf_small(``my str %s, my int %d&#92;n'',(char
3147 _generic *)mystr,myint);</FONT>
3148 <P>
3149
3150
3151 <P>
3152
3153 <UL>
3154 <LI><B><FONT SIZE="+1">stdarg.h</FONT></B> - contains definition for the following macros
3155 to be used for variable parameter list, note that a function can have
3156 a variable parameter list if and only if it is 'reentrant'
3157
3158 <P>
3159 <FONT SIZE="-1">va_list, va_start, va_arg, va_end.</FONT>
3160 <P>
3161
3162
3163 <P>
3164 </LI>
3165 <LI><B><FONT SIZE="+1">setjmp.h</FONT></B> - contains defintion for ANSI <B>setjmp</B>
3166 &amp; <B>longjmp</B> routines. Note in this case setjmp &amp; longjmp
3167 can be used between functions executing within the same register bank,
3168 if long jmp is executed from a function that is using a different
3169 register bank from the function issuing the setjmp function, the results
3170 may be unpredictable. The jump buffer requires 3 bytes of data (the
3171 stack pointer &amp; a 16 byte return address), and can be placed in any
3172 address space.
3173 </LI>
3174 <LI><B><FONT SIZE="+1">stdlib.h</FONT></B> - contains the following functions.
3175
3176 <P>
3177 <FONT SIZE="-1">atoi, atol.</FONT>
3178 <P>
3179
3180
3181 <P>
3182 </LI>
3183 <LI><B><FONT SIZE="+1">string.h</FONT></B> - contains the following functions.
3184
3185 <P>
3186 <FONT SIZE="-1">strcpy, strncpy, strcat, strncat, strcmp, strncmp,
3187 strchr, strrchr, strspn, strcspn, strpbrk, strstr, strlen, strtok,
3188 memcpy, memcmp, memset.</FONT>
3189 <P>
3190
3191
3192 <P>
3193 </LI>
3194 <LI><B><FONT SIZE="+1">ctype.h</FONT></B> - contains the following routines.
3195
3196 <P>
3197 <FONT SIZE="-1">iscntrl, isdigit, isgraph, islower, isupper, isprint,
3198 ispunct, isspace, isxdigit, isalnum, isalpha.</FONT>
3199 <P>
3200
3201
3202 <P>
3203 </LI>
3204 <LI><B><FONT SIZE="+1">malloc.h</FONT></B> - The malloc routines are developed by Dmitry
3205 S. Obukhov (dso@usa.net). These routines will allocate memory from
3206 the external ram. Here is a description on how to use them (as described
3207 by the author).
3208
3209 <P>
3210 <FONT SIZE="-2">//Example: </FONT>
3211 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp; #define DYNAMIC_MEMORY_SIZE 0x2000
3212 </FONT>
3213 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp; ..... </FONT>
3214 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp; unsigned char xdata dynamic_memory_pool[DYNAMIC_MEMORY_SIZE];
3215 </FONT>
3216 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp; unsigned char xdata * current_buffer;
3217 </FONT>
3218 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp; ..... </FONT>
3219 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp; void main(void) </FONT>
3220 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp; { </FONT>
3221 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... </FONT>
3222 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;//&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; init_dynamic_memory(dynamic_memory_pool,DYNAMIC_MEMORY_SIZE);
3223 </FONT>
3224 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; //Now it's possible to use
3225 malloc. </FONT>
3226 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ... </FONT>
3227 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; current_buffer = malloc(0x100);
3228 </FONT>
3229 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp; //</FONT>
3230 <P>
3231
3232
3233 <P>
3234 </LI>
3235 <LI><B><FONT SIZE="+1">serial.h</FONT></B> - Serial IO routines are also developed by
3236 Dmitry S. Obukhov (dso@usa.net). These routines are interrupt driven
3237 with a 256 byte circular buffer, they also expect external ram to
3238 be present. Please see documentation in file SDCCDIR/sdcc51lib/serial.c.
3239 Note the header file ``serial.h'' MUST be included in the file
3240 containing the 'main' function.
3241 </LI>
3242 <LI><B><FONT SIZE="+1">ser.h</FONT></B> - Alternate serial routine provided by Wolfgang
3243 Esslinger &lt;wolfgang@WiredMinds.com&gt; these routines are more compact
3244 and faster. Please see documentation in file SDCCDIR/sdcc51lib/ser.c
3245 </LI>
3246 <LI><B><FONT SIZE="+1">ser_ir.h</FONT></B> - Another alternate set of serial routines
3247 provided by Josef Wolf &lt;jw@raven.inka.de&gt; , these routines do not
3248 use the external ram.
3249 </LI>
3250 <LI><B><FONT SIZE="+1">reg51.h</FONT></B> - contains register definitions for a standard
3251 8051
3252 </LI>
3253 <LI><B><FONT SIZE="+1">float.h</FONT></B> - contains min, max and other floating point
3254 related stuff.
3255 </LI>
3256 </UL>
3257 All library routines are compiled as -model-small , they are all
3258 non-reentrant, if you plan to use the large model or want to make
3259 these routines reentrant, then they will have to be recompiled with
3260 the appropriate compiler option.
3261
3262 <P>
3263 Have not had time to do the more involved routines like printf, will
3264 get to them shortly.
3265
3266 <P>
3267
3268 <H2><A NAME="SECTION00054000000000000000">
3269 4.4 Interfacing with Assembly Routines</A>
3270 </H2>
3271
3272 <P>
3273
3274 <H2><A NAME="SECTION00055000000000000000">
3275 4.5 Global Registers used for Parameter Passing</A>
3276 </H2>
3277
3278 <P>
3279 By default the compiler uses the global registers ``DPL,DPH,B,ACC''
3280 to pass the first parameter to a routine, the second parameter onwards
3281 is either allocated on the stack (for reentrant routines or -stack-auto
3282 is used) or in the internal / external ram (depending on the memory
3283 model).
3284
3285 <P>
3286
3287 <H3><A NAME="SECTION00055100000000000000">
3288 4.5.1 Assembler Routine(non-reentrant)</A>
3289 </H3>
3290
3291 <P>
3292 In the following example the function <B>cfunc</B> calls an assembler
3293 routine <B>asm_func</B>, which takes two parameters.
3294
3295 <P>
3296 <FONT SIZE="-1">extern int asm_func( unsigned char, unsigned char);</FONT>
3297 <P>
3298
3299
3300 <P>
3301 <FONT SIZE="-1">&nbsp;</FONT>
3302 <BR><FONT SIZE="-1">int c_func (unsigned char i, unsigned char j) </FONT>
3303 <BR><FONT SIZE="-1">{ </FONT>
3304 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return asm_func(i,j); </FONT>
3305 <BR><FONT SIZE="-1">}</FONT>
3306 <BR><FONT SIZE="-2">int main() </FONT>
3307 <BR><FONT SIZE="-2">{ </FONT>
3308 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;return c_func(10,9); </FONT>
3309 <BR><FONT SIZE="-2">}</FONT>
3310 <P>
3311
3312
3313 <P>
3314 The corresponding assembler function is:-
3315
3316 <P>
3317 <FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .globl _asm_func_PARM_2 </FONT>
3318 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .globl _asm_func </FONT>
3319 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .area OSEG </FONT>
3320 <BR><FONT SIZE="-2">_asm_func_PARM_2:&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .ds&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 1 </FONT>
3321 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .area CSEG </FONT>
3322 <BR><FONT SIZE="-2">_asm_func: </FONT>
3323 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp;&nbsp;&nbsp;&nbsp; a,dpl </FONT>
3324 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; add&nbsp;&nbsp;&nbsp;&nbsp; a,_asm_func_PARM_2 </FONT>
3325 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp;&nbsp;&nbsp;&nbsp; dpl,a </FONT>
3326 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp;&nbsp;&nbsp;&nbsp; dpl,#0x00 </FONT>
3327 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ret</FONT>
3328 <P>
3329
3330
3331 <P>
3332 Note here that the return values are placed in 'dpl' - One byte return
3333 value, 'dpl' LSB &amp; 'dph' MSB for two byte values. 'dpl', 'dph' and
3334 'b' for three byte values (generic pointers) and 'dpl','dph','b' &amp;
3335 'acc' for four byte values.
3336
3337 <P>
3338 The parameter naming convention is <B>_&lt;function_name&gt;_PARM_&lt;n&gt;,</B>
3339 where n is the parameter number starting from 1, and counting from
3340 the left. The first parameter is passed in ``dpl'' for One bye
3341 parameter, ``dptr'' if two bytes, ``b,dptr'' for three bytes
3342 and ``acc,b,dptr'' for four bytes, the <TT><B><FONT SIZE="-1">varaible
3343 name for the second parameter will be _&lt;function_name&gt;_PARM_2.</FONT></B></TT>
3344 <P>
3345
3346
3347 <P>
3348 Assemble the assembler routine with the following command.
3349
3350 <P>
3351 asx8051 -losg asmfunc.asm
3352
3353 <P>
3354 Then compile and link the assembler routine to the C source file with
3355 the following command,
3356
3357 <P>
3358 sdcc cfunc.c asmfunc.rel
3359
3360 <P>
3361
3362 <H3><A NAME="SECTION00055200000000000000">
3363 4.5.2 Assembler Routine(reentrant)</A>
3364 </H3>
3365
3366 <P>
3367 In this case the second parameter onwards will be passed on the stack
3368 , the parameters are pushed from right to left i.e. after the call
3369 the left most parameter will be on the top of the stack. Here is an
3370 example.
3371
3372 <P>
3373 <FONT SIZE="-1">extern int asm_func( unsigned char, unsigned char);</FONT>
3374 <P>
3375
3376
3377 <P>
3378 <FONT SIZE="-1">&nbsp;</FONT>
3379 <P>
3380
3381
3382 <P>
3383 <FONT SIZE="-1">int c_func (unsigned char i, unsigned char j) reentrant
3384 </FONT>
3385 <BR><FONT SIZE="-1">{ </FONT>
3386 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; return asm_func(i,j); </FONT>
3387 <BR><FONT SIZE="-1">}</FONT>
3388 <BR><FONT SIZE="-2">int main() </FONT>
3389 <BR><FONT SIZE="-2">{ </FONT>
3390 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;return c_func(10,9); </FONT>
3391 <BR><FONT SIZE="-2">}</FONT>
3392 <P>
3393
3394
3395 <P>
3396 The corresponding assembler routine is.
3397
3398 <P>
3399 <FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; .globl _asm_func </FONT>
3400 <BR><FONT SIZE="-2">_asm_func: </FONT>
3401 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; push&nbsp; _bp </FONT>
3402 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp; _bp,sp </FONT>
3403 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;mov&nbsp; r2,dpl</FONT>
3404 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp; a,_bp </FONT>
3405 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; clr&nbsp; c </FONT>
3406 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; add&nbsp; a,#0xfd </FONT>
3407 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp; r0,a </FONT>
3408 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; add&nbsp; a,#0xfc</FONT>
3409 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp; r1,a </FONT>
3410 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp; a,@r0 </FONT>
3411 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; add&nbsp; a,r2</FONT>
3412 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp; dpl,a </FONT>
3413 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp; dph,#0x00 </FONT>
3414 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; mov&nbsp; sp,_bp </FONT>
3415 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; pop&nbsp; _bp </FONT>
3416 <BR><FONT SIZE="-2">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; ret</FONT>
3417 <P>
3418
3419
3420 <P>
3421 The compiling and linking procedure remains the same, however note
3422 the extra entry &amp; exit linkage required for the assembler code, _bp
3423 is the stack frame pointer and is used to compute the offset into
3424 the stack for parameters and local variables.
3425
3426 <P>
3427
3428 <H2><A NAME="SECTION00056000000000000000">
3429 4.6 External Stack</A>
3430 </H2>
3431
3432 <P>
3433 The external stack is located at the start of the external ram segment
3434 , and is 256 bytes in size. When -xstack option is used to compile
3435 the program, the parameters and local variables of all reentrant functions
3436 are allocated in this area. This option is provided for programs with
3437 large stack space requirements. When used with the -stack-auto option,
3438 all parameters and local variables are allocated on the external stack
3439 (note support libraries will need to be recompiled with the same options).
3440
3441 <P>
3442 The compiler outputs the higher order address byte of the external
3443 ram segment into PORT P2, therefore when using the External Stack
3444 option, this port MAY NOT be used by the application program.
3445
3446 <P>
3447
3448 <H2><A NAME="SECTION00057000000000000000">
3449 4.7 ANSI-Compliance</A>
3450 </H2>
3451
3452 <P>
3453 Deviations from the compliancy.
3454
3455 <P>
3456
3457 <OL>
3458 <LI>functions are not always reentrant.
3459 </LI>
3460 <LI>structures cannot be assigned values directly, cannot be passed as
3461 function parameters or assigned to each other and cannot be a return
3462 value from a function.
3463
3464 <P>
3465 <FONT SIZE="-1">eg</FONT>
3466 <P>
3467
3468
3469 <P>
3470 </LI>
3471 </OL>
3472 <FONT SIZE="-1">struct s { ... }; </FONT>
3473 <BR><FONT SIZE="-1">struct s s1, s2; </FONT>
3474 <BR><FONT SIZE="-1">foo() </FONT>
3475 <BR><FONT SIZE="-1">{ </FONT>
3476 <BR><FONT SIZE="-1">... </FONT>
3477 <BR><FONT SIZE="-1">s1 = s2 ; /* is invalid in SDCC although allowed in ANSI
3478 */ </FONT>
3479 <BR><FONT SIZE="-1">... </FONT>
3480 <BR><FONT SIZE="-1">}</FONT>
3481 <P>
3482
3483
3484 <P>
3485 <FONT SIZE="-1">struct s foo1 (struct s parms) /* is invalid in SDCC although
3486 allowed in ANSI */ </FONT>
3487 <BR><FONT SIZE="-1">{ </FONT>
3488 <BR><FONT SIZE="-1">struct s rets; </FONT>
3489 <BR><FONT SIZE="-1">... </FONT>
3490 <BR><FONT SIZE="-1">return rets;/* is invalid in SDCC although allowed in ANSI
3491 */ </FONT>
3492 <BR><FONT SIZE="-1">}</FONT>
3493 <P>
3494
3495
3496 <P>
3497
3498 <OL>
3499 <LI>'long long' (64 bit integers) not supported.
3500 </LI>
3501 <LI>'double' precision floating point not supported.
3502 </LI>
3503 <LI>integral promotions are suppressed. What does this mean ? The compiler
3504 will not implicitly promote an integer expression to a higher order
3505 integer, exception is an assignment or parameter passing.
3506 </LI>
3507 <LI>No support for <I>setjmp</I> and <I>longjmp</I> (for now).
3508 </LI>
3509 <LI>Old K&amp;R style function declarations are NOT allowed.
3510 </LI>
3511 </OL>
3512 <FONT SIZE="-1">foo( i,j) /* this old style of function declarations
3513 */ </FONT>
3514 <BR><FONT SIZE="-1">int i,j; /* are valid in ANSI .. not valid in SDCC
3515 */ </FONT>
3516 <BR><FONT SIZE="-1">{ </FONT>
3517 <BR><FONT SIZE="-1">... </FONT>
3518 <BR><FONT SIZE="-1">}</FONT>
3519 <P>
3520
3521
3522 <P>
3523
3524 <OL>
3525 <LI>functions declared as pointers must be dereferenced during the call.
3526
3527 <P>
3528 <FONT SIZE="-1">int (*foo)();</FONT>
3529 <P>
3530
3531
3532 <P>
3533 </LI>
3534 </OL>
3535 <FONT SIZE="-1">&nbsp; &nbsp;... </FONT>
3536 <BR><FONT SIZE="-1">&nbsp; &nbsp;/* has to be called like this */ </FONT>
3537 <BR><FONT SIZE="-1">&nbsp; &nbsp;(*foo)();/* ansi standard allows calls to be made
3538 like 'foo()' */</FONT>
3539 <P>
3540
3541
3542 <P>
3543
3544 <H2><A NAME="SECTION00058000000000000000">
3545 4.8 Cyclomatic Complexity</A>
3546 </H2>
3547
3548 <P>
3549 Cyclomatic complexity of a function is defined as the number of independent
3550 paths the program can take during execution of the function. This
3551 is an important number since it defines the number test cases you
3552 have to generate to validate the function. The accepted industry standard
3553 for complexity number is 10, if the cyclomatic complexity reported
3554 by SDCC exceeds 10 you should think about simplification of the function
3555 logic.
3556
3557 <P>
3558 Note that the complexity level is not related to the number of lines
3559 of code in a function. Large functions can have low complexity, and
3560 small functions can have large complexity levels. SDCC uses the following
3561 formula to compute the complexity.
3562
3563 <P>
3564 <FONT SIZE="-1">complexity = (number of edges in control flow graph) - </FONT>
3565 <BR><FONT SIZE="-1">&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp; &nbsp;(number of nodes in control flow graph)
3566 + 2;</FONT>
3567 <P>
3568
3569
3570 <P>
3571 Having said that the industry standard is 10, you should be aware
3572 that in some cases it may unavoidable to have a complexity level of
3573 less than 10. For example if you have switch statement with more than
3574 10 case labels, each case label adds one to the complexity level.
3575 The complexity level is by no means an absolute measure of the algorithmic
3576 complexity of the function, it does however provide a good starting
3577 point for which functions you might look at for further optimization.
3578
3579 <P>
3580
3581 <H1><A NAME="SECTION00060000000000000000">
3582 5 TIPS</A>
3583 </H1>
3584
3585 <P>
3586 Here are a few guide-lines that will help the compiler generate more
3587 efficient code, some of the tips are specific to this compiler others
3588 are generally good programming practice.
3589
3590 <P>
3591
3592 <UL>
3593 <LI>Use the smallest data type to represent your data-value. If it is
3594 known in advance that the value is going to be less than 256 then
3595 use a 'char' instead of a 'short' or 'int'.
3596 </LI>
3597 <LI>Use unsigned when it is known in advance that the value is not going
3598 to be negative. This helps especially if you are doing division or
3599 multiplication.
3600 </LI>
3601 <LI>NEVER jump into a LOOP.
3602 </LI>
3603 <LI>Declare the variables to be local whenever possible, especially loop
3604 control variables (induction).
3605 </LI>
3606 <LI>Since the compiler does not do implicit integral promotion, the programmer
3607 should do an explicit cast when integral promotion is required.
3608 </LI>
3609 <LI>Reducing the size of division , multiplication &amp; modulus operations
3610 can reduce code size substantially. Take the following code for example.
3611
3612 <P>
3613 <FONT SIZE="-1">foobar( unsigned int p1, unsigned char ch)</FONT>
3614 <BR><FONT SIZE="-1">{</FONT>
3615 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;unsigned char ch1 = p1 % ch ;</FONT>
3616 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;....&nbsp;&nbsp;&nbsp;&nbsp;</FONT>
3617 <BR><FONT SIZE="-1">}</FONT>
3618 <P>
3619
3620
3621 <P>
3622 For the modulus operation the variable ch will be promoted to unsigned
3623 int first then the modulus operation will be performed (this will
3624 lead to a call to a support routine). If the code is changed to
3625
3626 <P>
3627 <FONT SIZE="-1">foobar( unsigned int p1, unsigned char ch)</FONT>
3628 <BR><FONT SIZE="-1">{</FONT>
3629 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;unsigned char ch1 = (unsigned char)p1 % ch
3630 ;</FONT>
3631 <BR><FONT SIZE="-1">&nbsp;&nbsp;&nbsp;&nbsp;....&nbsp;&nbsp;&nbsp;&nbsp;</FONT>
3632 <BR><FONT SIZE="-1">}</FONT>
3633 <P>
3634
3635
3636 <P>
3637 It would substantially reduce the code generated (future versions
3638 of the compiler will be smart enough to detect such optimization oppurtunities).
3639
3640 <P>
3641 </LI>
3642 </UL>
3643 <B>Notes on MCS51 memory layout(Trefor@magera.freeserve.co.uk)</B>
3644
3645 <P>
3646 The 8051 family of micro controller have a minimum of 128 bytes of
3647 internal memory which is structured as follows
3648
3649 <P>
3650 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7
3651 to R7
3652
3653 <P>
3654 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
3655
3656 <P>
3657 - Bytes 30-7F - 60 bytes for general purpose use.
3658
3659 <P>
3660 Normally the SDCC compiler will only utilise the first bank of registers,
3661 but it is possible to specify that other banks of registers should
3662 be used in interrupt routines. By default, the compiler will place
3663 the stack after the last bank of used registers, i.e. if the first
3664 2 banks of registers are used, it will position the base of the internal
3665 stack at address 16 (0X10). This implies that as the stack grows,
3666 it will use up the remaining register banks, and the 16 bytes used
3667 by the 128 bit variables, and 60 bytes for general purpose use.
3668
3669 <P>
3670 By default, the compiler uses the 60 general purpose bytes to hold
3671 &#34;near data&#34;. The compiler/optimiser may also declare
3672 some Local Variables in this area to hold local data.
3673
3674 <P>
3675 If any of the 128 bit variables are used, or near data is being used
3676 then care needs to be taken to ensure that the stack does not grow
3677 so much that it starts to over write either your bit variables or
3678 &#34;near data&#34;. There is no runtime checking to prevent
3679 this from happening.
3680
3681 <P>
3682 The amount of stack being used is affected by the use of the &#34;internal
3683 stack&#34; to save registers before a subroutine call is made,
3684 - -stack-auto will declare parameters and local variables on the
3685 stack - the number of nested subroutines.
3686
3687 <P>
3688 If you detect that the stack is over writing you data, then the following
3689 can be done. -xstack will cause an external stack to be used for
3690 saving registers and (if -stack-auto is being used) storing parameters
3691 and local variables. However this will produce more and code which
3692 will be slower to execute.
3693
3694 <P>
3695 -stack-loc will allow you specify the start of the stack, i.e. you
3696 could start it after any data in the general purpose area. However
3697 this may waste the memory not used by the register banks and if the
3698 size of the &#34;near data&#34; increases, it may creep
3699 into the bottom of the stack.
3700
3701 <P>
3702 -stack-after-data, similar to the -stack-loc, but it automatically
3703 places the stack after the end of the &#34;near data&#34;.
3704 Again this could waste any spare register space.
3705
3706 <P>
3707 -data-loc allows you to specify the start address of the near data.
3708 This could be used to move the &#34;near data&#34; further
3709 away from the stack giving it more room to grow. This will only work
3710 if no bit variables are being used and the stack can grow to use the
3711 bit variable space.
3712
3713 <P>
3714 Conclusion.
3715
3716 <P>
3717 If you find that the stack is over writing your bit variables or &#34;near
3718 data&#34; then the approach which best utilised the internal
3719 memory is to position the &#34;near data&#34; after the
3720 last bank of used registers or, if you use bit variables, after the
3721 last bit variable by using the -data-loc, e.g. if two register banks
3722 are being used and no data variables, -data-loc 16, and - use the
3723 -stack-after-data option.
3724
3725 <P>
3726 If bit variables are being used, another method would be to try and
3727 squeeze the data area in the unused register banks if it will fit,
3728 and start the stack after the last bit variable.
3729
3730 <P>
3731
3732 <H1><A NAME="SECTION00070000000000000000">
3733 6 Retargetting for other MCUs.</A>
3734 </H1>
3735
3736 <P>
3737 The issues for retargetting the compiler are far too numerous to be
3738 covered by this document. What follows is a brief description of each
3739 of the seven phases of the compiler and its MCU dependency.
3740
3741 <P>
3742
3743 <OL>
3744 <LI>Parsing the source and building the annotated parse tree. This phase
3745 is largely MCU independent (except for the language extensions). Syntax
3746 &amp; semantic checks are also done in this phase , along with some initial
3747 optimizations like back patching labels and the pattern matching optimizations
3748 like bit-rotation etc.
3749 </LI>
3750 <LI>The second phase involves generating an intermediate code which can
3751 be easy manipulated during the later phases. This phase is entirely
3752 MCU independent. The intermediate code generation assumes the target
3753 machine has unlimited number of registers, and designates them with
3754 the name iTemp. The compiler can be made to dump a human readable
3755 form of the code generated by using the -dumpraw option.
3756 </LI>
3757 <LI>This phase does the bulk of the standard optimizations and is also
3758 MCU independent. This phase can be broken down into several sub-phases.
3759
3760 <P>
3761
3762 <UL>
3763 <LI>Break down intermediate code (iCode) into basic blocks.
3764 </LI>
3765 <LI>Do control flow &amp; data flow analysis on the basic blocks.
3766 </LI>
3767 <LI>Do local common subexpression elimination, then global subexpression
3768 elimination
3769 </LI>
3770 <LI>dead code elimination
3771 </LI>
3772 <LI>loop optimizations
3773 </LI>
3774 <LI>if loop optimizations caused any changes then do 'global subexpression
3775 elimination' and 'dead code elimination' again.
3776 </LI>
3777 </UL>
3778 </LI>
3779 <LI>This phase determines the live-ranges; by live range I mean those
3780 iTemp variables defined by the compiler that still survive after all
3781 the optimizations. Live range analysis is essential for register allocation,
3782 since these computation determines which of these iTemps will be assigned
3783 to registers, and for how long.
3784 </LI>
3785 <LI>Phase five is register allocation. There are two parts to this process.
3786
3787 <P>
3788
3789 <OL>
3790 <LI>The first part I call 'register packing' (for lack of a better term).
3791 In this case several MCU specific expression folding is done to reduce
3792 register pressure.
3793 </LI>
3794 <LI>The second part is more MCU independent and deals with allocating
3795 registers to the remaining live ranges. A lot of MCU specific code
3796 does creep into this phase because of the limited number of index
3797 registers available in the 8051.
3798 </LI>
3799 </OL>
3800 </LI>
3801 <LI>The Code generation phase is (unhappily), entirely MCU dependent and
3802 very little (if any at all) of this code can be reused for other MCU.
3803 However the scheme for allocating a homogenized assembler operand
3804 for each iCode operand may be reused.
3805 </LI>
3806 <LI>As mentioned in the optimization section the peep-hole optimizer is
3807 rule based system, which can reprogrammed for other MCUs.
3808 </LI>
3809 </OL>
3810
3811 <P>
3812
3813 <H1><A NAME="SECTION00080000000000000000">
3814 7 SDCDB - Source Level Debugger</A>
3815 </H1>
3816
3817 <P>
3818 SDCC is distributed with a source level debugger. The debugger uses
3819 a command line interface, the command repertoire of the debugger has
3820 been kept as close to gdb ( the GNU debugger) as possible. The configuration
3821 and build process is part of the standard compiler installation, which
3822 also builds and installs the debugger in the target directory specified
3823 during configuration. The debugger allows you debug BOTH at the C
3824 source and at the ASM source level.
3825
3826 <P>
3827
3828 <H2><A NAME="SECTION00081000000000000000">
3829 7.1 Compiling for Debugging</A>
3830 </H2>
3831
3832 <P>
3833 The <I>-debug</I> option must be specified for all files for which
3834 debug information is to be generated. The complier generates a <I>.cdb</I>
3835 file for each of these files. The linker updates the <I>.cdb</I> file
3836 with the address information. This .cdb is used by the debugger.
3837
3838 <P>
3839
3840 <H2><A NAME="SECTION00082000000000000000">
3841 7.2 How the Debugger Works</A>
3842 </H2>
3843
3844 <P>
3845 When the <I>-debug</I> option is specified the compiler generates
3846 extra symbol information some of which are put into the the assembler
3847 source and some are put into the .cdb file, the linker updates the
3848 .cdb file with the address information for the symbols. The debugger
3849 reads the symbolic information generated by the compiler &amp; the address
3850 information generated by the linker. It uses the SIMULATOR (Daniel's
3851 S51) to execute the program, the program execution is controlled by
3852 the debugger. When a command is issued for the debugger, it translates
3853 it into appropriate commands for the simulator.
3854
3855 <P>
3856
3857 <H2><A NAME="SECTION00083000000000000000">
3858 7.3 Starting the Debugger</A>
3859 </H2>
3860
3861 <P>
3862 The debugger can be started using the following command line. (Assume
3863 the file you are debugging has
3864
3865 <P>
3866 the file name foo).
3867
3868 <P>
3869 &gt;sdcdb foo
3870
3871 <P>
3872 The debugger will look for the following files.
3873
3874 <P>
3875
3876 <OL>
3877 <LI>foo.c - the source file.
3878 </LI>
3879 <LI>foo.cdb - the debugger symbol information file.
3880 </LI>
3881 <LI>foo.ihx - the intel hex format object file.
3882 </LI>
3883 </OL>
3884
3885 <P>
3886
3887 <H2><A NAME="SECTION00084000000000000000">
3888 7.4 Command Line Options.</A>
3889 </H2>
3890
3891 <P>
3892
3893 <UL>
3894 <LI>-directory=&lt;source file directory&gt; this option can used to specify
3895 the directory search list. The debugger will look into the directory
3896 list specified for source , cdb &amp; ihx files. The items in the directory
3897 list must be separated by ':' , e.g. if the source files can be in
3898 the directories /home/src1 and /home/src2, the -directory option
3899 should be -directory=/home/src1:/home/src2. Note there can be no
3900 spaces in the option.
3901 </LI>
3902 <LI>-cd &lt;directory&gt; - change to the &lt;directory&gt;.
3903 </LI>
3904 <LI>-fullname - used by GUI front ends.
3905 </LI>
3906 <LI>-cpu &lt;cpu-type&gt; - this argument is passed to the simulator please
3907 see the simulator docs for details.
3908 </LI>
3909 <LI>-X &lt;Clock frequency &gt; this options is passed to the simulator please
3910 see simulator docs for details.
3911 </LI>
3912 <LI>-s &lt;serial port file&gt; passed to simulator see simulator docs for details.
3913 </LI>
3914 <LI>-S &lt;serial in,out&gt; passed to simulator see simulator docs for details.
3915 </LI>
3916 </UL>
3917
3918 <P>
3919
3920 <H2><A NAME="SECTION00085000000000000000">
3921 7.5 Debugger Commands.</A>
3922 </H2>
3923
3924 <P>
3925 As mention earlier the command interface for the debugger has been
3926 deliberately kept as close the GNU debugger gdb , as possible, this
3927 will help int integration with existing graphical user interfaces
3928 (like ddd, xxgdb or xemacs) existing for the GNU debugger.
3929
3930 <P>
3931
3932 <H3><A NAME="SECTION00085100000000000000">
3933 7.5.1 break [line | file:line | function | file:function]</A>
3934 </H3>
3935
3936 <P>
3937 Set breakpoint at specified line or function.
3938
3939 <P>
3940 sdcdb&gt;break 100
3941 <BR>
3942 sdcdb&gt;break foo.c:100
3943 <BR>
3944 sdcdb&gt;break funcfoo
3945 <BR>
3946 sdcdb&gt;break foo.c:funcfoo
3947
3948 <P>
3949
3950 <H3><A NAME="SECTION00085200000000000000">
3951 7.5.2 clear [line | file:line | function | file:function ]</A>
3952 </H3>
3953
3954 <P>
3955 Clear breakpoint at specified line or function.
3956
3957 <P>
3958 sdcdb&gt;clear 100
3959 <BR>
3960 sdcdb&gt;clear foo.c:100
3961 <BR>
3962 sdcdb&gt;clear funcfoo
3963 <BR>
3964 sdcdb&gt;clear foo.c:funcfoo
3965
3966 <P>
3967
3968 <H3><A NAME="SECTION00085300000000000000">
3969 7.5.3 continue</A>
3970 </H3>
3971
3972 <P>
3973 Continue program being debugged, after breakpoint.
3974
3975 <P>
3976
3977 <H3><A NAME="SECTION00085400000000000000">
3978 7.5.4 finish</A>
3979 </H3>
3980
3981 <P>
3982 Execute till the end of the current function.
3983
3984 <P>
3985
3986 <H3><A NAME="SECTION00085500000000000000">
3987 7.5.5 delete [n]</A>
3988 </H3>
3989
3990 <P>
3991 Delete breakpoint number 'n'. If used without any option clear ALL
3992 user defined break points.
3993
3994 <P>
3995
3996 <H3><A NAME="SECTION00085600000000000000">
3997 7.5.6 info [break | stack | frame | registers ]</A>
3998 </H3>
3999
4000 <P>
4001
4002 <UL>
4003 <LI>info break - list all breakpoints
4004 </LI>
4005 <LI>info stack - show the function call stack.
4006 </LI>
4007 <LI>info frame - show information about the current execution frame.
4008 </LI>
4009 <LI>info registers - show content of all registers.
4010 </LI>
4011 </UL>
4012
4013 <P>
4014
4015 <H3><A NAME="SECTION00085700000000000000">
4016 7.5.7 step</A>
4017 </H3>
4018
4019 <P>
4020 Step program until it reaches a different source line.
4021
4022 <P>
4023
4024 <H3><A NAME="SECTION00085800000000000000">
4025 7.5.8 next</A>
4026 </H3>
4027
4028 <P>
4029 Step program, proceeding through subroutine calls.
4030
4031 <P>
4032
4033 <H3><A NAME="SECTION00085900000000000000">
4034 7.5.9 run</A>
4035 </H3>
4036
4037 <P>
4038 Start debugged program.
4039
4040 <P>
4041
4042 <H3><A NAME="SECTION000851000000000000000">
4043 7.5.10 ptype variable </A>
4044 </H3>
4045
4046 <P>
4047 Print type information of the variable.
4048
4049 <P>
4050
4051 <H3><A NAME="SECTION000851100000000000000">
4052 7.5.11 print variable</A>
4053 </H3>
4054
4055 <P>
4056 print value of variable.
4057
4058 <P>
4059
4060 <H3><A NAME="SECTION000851200000000000000">
4061 7.5.12 file filename</A>
4062 </H3>
4063
4064 <P>
4065 load the given file name. Note this is an alternate method of loading
4066 file for debugging.
4067
4068 <P>
4069
4070 <H3><A NAME="SECTION000851300000000000000">
4071 7.5.13 frame</A>
4072 </H3>
4073
4074 <P>
4075 print information about current frame.
4076
4077 <P>
4078
4079 <H3><A NAME="SECTION000851400000000000000">
4080 7.5.14 set srcmode</A>
4081 </H3>
4082
4083 <P>
4084 Toggle between C source &amp; assembly source.
4085
4086 <P>
4087
4088 <H3><A NAME="SECTION000851500000000000000">
4089 7.5.15 ! simulator command</A>
4090 </H3>
4091
4092 <P>
4093 Send the string following '!' to the simulator, the simulator response
4094 is displayed. Note the debugger does not interpret the command being
4095 sent to the simulator, so if a command like 'go' is sent the debugger
4096 can loose its execution context and may display incorrect values.
4097
4098 <P>
4099
4100 <H3><A NAME="SECTION000851600000000000000">
4101 7.5.16 quit.</A>
4102 </H3>
4103
4104 <P>
4105 &#34;Watch me now. Iam going Down. My name is Bobby Brown&#34;
4106
4107 <P>
4108
4109 <H2><A NAME="SECTION00086000000000000000">
4110 7.6 Interfacing with XEmacs.</A>
4111 </H2>
4112
4113 <P>
4114 Two files are (in emacs lisp) are provided for the interfacing with
4115 XEmacs, <I>sdcdb.el</I> and <I>sdcdbsrc.el</I>. These two files can
4116 be found in the $(prefix)/bin directory after the installation is
4117 complete. These files need to be loaded into XEmacs for the interface
4118 to work, this can be done at XEmacs startup time by inserting the
4119 following into your <I>'.xemacs'</I> file (which can be found in your
4120 HOME directory) <I>(load-file sdcdbsrc.el)</I> [ .xemacs is a lisp
4121 file so the () around the command is REQUIRED), the files can also
4122 be loaded dynamically while XEmacs is running, set the environment
4123 variable <I>'EMACSLOADPATH'</I> to the installation bin directory
4124 [$(prefix)/bin], then enter the following command <I>ESC-x
4125 load-file sdcdbsrc.</I> To start the interface enter the following command
4126 <I>ESC-x sdcdbsrc</I> , you will prompted to enter the file name to
4127 be debugged.
4128
4129 <P>
4130 The command line options that are passed to the simulator directly
4131 are bound to default values in the file <I>sdcdbsrc.el</I> the variables
4132 are listed below these values maybe changed as required.
4133
4134 <P>
4135
4136 <UL>
4137 <LI>sdcdbsrc-cpu-type '51
4138 </LI>
4139 <LI>sdcdbsrc-frequency '11059200
4140 </LI>
4141 <LI>sdcdbsrc-serial nil
4142 </LI>
4143 </UL>
4144 The following is a list of key mapping for the debugger interface.
4145
4146 <P>
4147 &nbsp;
4148 <BR><FONT SIZE="-2">;; Current Listing :: </FONT>
4149 <BR><FONT SIZE="-2">;;key&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;binding&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Comment
4150 </FONT>
4151 <BR><FONT SIZE="-2">;;--&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;----&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;----
4152 </FONT>
4153 <BR><FONT SIZE="-2">;; </FONT>
4154 <BR><FONT SIZE="-2">;; n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdb-next-from-src&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4155 next command </FONT>
4156 <BR><FONT SIZE="-2">;; b&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdb-back-from-src&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4157 back command </FONT>
4158 <BR><FONT SIZE="-2">;; c&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdb-cont-from-src&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4159 continue command</FONT>
4160 <BR><FONT SIZE="-2">;; s&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdb-step-from-src&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4161 step command </FONT>
4162 <BR><FONT SIZE="-2">;; ?&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdb-whatis-c-sexp&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4163 ptypecommand for data at </FONT>
4164 <BR><FONT SIZE="-2">;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
4165 buffer point </FONT>
4166 <BR><FONT SIZE="-2">;; x&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdbsrc-delete&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4167 Delete all breakpoints if no arg </FONT>
4168 <BR><FONT SIZE="-2">;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;given
4169 or delete arg (C-u arg x) </FONT>
4170 <BR><FONT SIZE="-2">;; m&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdbsrc-frame&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4171 Display current frame if no arg, </FONT>
4172 <BR><FONT SIZE="-2">;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;given
4173 or display frame arg </FONT>
4174 <BR><FONT SIZE="-2">;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;buffer
4175 point </FONT>
4176 <BR><FONT SIZE="-2">;; !&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdbsrc-goto-sdcdb&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Goto
4177 the SDCDB output buffer </FONT>
4178 <BR><FONT SIZE="-2">;; p&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdb-print-c-sexp&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4179 print command for data at </FONT>
4180 <BR><FONT SIZE="-2">;;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
4181 buffer point </FONT>
4182 <BR><FONT SIZE="-2">;; g&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdbsrc-goto-sdcdb&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Goto
4183 the SDCDB output buffer </FONT>
4184 <BR><FONT SIZE="-2">;; t&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdbsrc-mode&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Toggles
4185 Sdcdbsrc mode (turns it off) </FONT>
4186 <BR><FONT SIZE="-2">;; </FONT>
4187 <BR><FONT SIZE="-2">;; C-c C-f&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdb-finish-from-src&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;SDCDB
4188 finish command </FONT>
4189 <BR><FONT SIZE="-2">;; </FONT>
4190 <BR><FONT SIZE="-2">;; C-x SPC&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdb-break&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Set
4191 break for line with point </FONT>
4192 <BR><FONT SIZE="-2">;; ESC t&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdbsrc-mode&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Toggle
4193 Sdcdbsrc mode </FONT>
4194 <BR><FONT SIZE="-2">;; ESC m&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; sdcdbsrc-srcmode&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
4195 Toggle list mode </FONT>
4196 <BR><FONT SIZE="-2">;; </FONT>
4197 <BR>
4198 <P>
4199
4200
4201 <P>
4202
4203 <H1><A NAME="SECTION00090000000000000000">
4204 8 Other Processors</A>
4205 </H1>
4206
4207 <P>
4208
4209 <H2><A NAME="SECTION00091000000000000000">
4210 8.1 The Z80 and gbz80 port</A>
4211 </H2>
4212
4213 <P>
4214 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like
4215 gbz80. The port is incomplete - long support is incomplete (mul, div
4216 and mod are unimplimented), and both float and bitfield support is
4217 missing, but apart from that the code generated is correct.
4218
4219 <P>
4220 As always, the code is the authoritave reference - see z80/ralloc.c
4221 and z80/gen.c. The stack frame is similar to that generated by the
4222 IAR Z80 compiler. IX is used as the base pointer, HL is used as a
4223 temporary register, and BC and DE are available for holding varibles.
4224 IY is currently unusued. Return values are stored in HL. One bad side
4225 effect of using IX as the base pointer is that a functions stack frame
4226 is limited to 127 bytes - this will be fixed in a later version.
4227
4228 <P>
4229
4230 <H1><A NAME="SECTION000100000000000000000">
4231 9 Support</A>
4232 </H1>
4233
4234 <P>
4235 SDCC has grown to be large project, the compiler alone (without the
4236 Assembler Package, Preprocessor) is about 40,000 lines of code (blank
4237 stripped). The open source nature of this project is a key to its
4238 continued growth and support. You gain the benefit and support of
4239 many active software developers and end users. Is SDCC perfect? No,
4240 that's why we need your help. The developers take pride in fixing
4241 reported bugs. You can help by reporting the bugs and helping other
4242 SDCC users. There are lots of ways to contribute, and we encourage
4243 you to take part in making SDCC a great software package.
4244
4245 <P>
4246
4247 <H2><A NAME="SECTION000101000000000000000">
4248 9.1 Reporting Bugs</A>
4249 </H2>
4250
4251 <P>
4252 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net'
4253 or 'devel-sdcc@sdcc.sourceforge.net'. Bugs will be fixed ASAP. When
4254 reporting a bug, it is very useful to include a small test program
4255 which reproduces the problem. If you can isolate the problem by looking
4256 at the generated assembly code, this can be very helpful. Compiling
4257 your program with the -dumpall option can sometimes be useful in
4258 locating optimization problems.
4259
4260 <P>
4261
4262 <H2><A NAME="SECTION000102000000000000000">
4263 9.2 Acknowledgments</A>
4264 </H2>
4265
4266 <P>
4267 Sandeep Dutta(sandeep.dutta@usa.net) - SDCC, the compiler, MCS51 code
4268 generator, Debugger, AVR port
4269 <BR>
4270 Alan Baldwin (baldwin@shop-pdp.kent.edu) - Initial version of ASXXXX
4271 &amp; ASLINK.
4272 <BR>
4273 John Hartman (jhartman@compuserve.com) - Porting ASXXX &amp; ASLINK for
4274 8051
4275 <BR>
4276 Dmitry S. Obukhov (dso@usa.net) - malloc &amp; serial i/o routines.
4277 <BR>
4278 Daniel Drotos &lt;drdani@mazsola.iit.uni-miskolc.hu&gt; - for his Freeware
4279 simulator
4280 <BR>
4281 Malini Dutta(malini_dutta@hotmail.com) - my wife for her patience
4282 and support.
4283 <BR>
4284 Unknown - for the GNU C - preprocessor.
4285 <BR>
4286 Michael Hope - The Z80 and Z80GB port, 186 development
4287 <BR>
4288 Kevin Vigor - The DS390 port.
4289 <BR>
4290 Johan Knol - DS390/TINI libs, lots of fixes and enhancements.
4291 <BR>
4292 Scott Datallo - PIC port.
4293 <BR>(Thanks to all the other volunteer developers who have helped with
4294 coding, testing, web-page creation, distribution sets, etc. You know
4295 who you are :-)
4296 <BR>
4297 <P>
4298 This document initially written by Sandeep Dutta
4299
4300 <P>
4301 All product names mentioned herein may be trademarks of their respective
4302 companies.
4303
4304 <P>
4305 <A NAME="1227"></A>
4306
4307 <H1><A NAME="SECTION000110000000000000000">
4308 About this document ...</A>
4309 </H1>
4310  <STRONG>SDCC Compiler User Guide</STRONG><P>
4311 This document was generated using the
4312 <A HREF="http://www-dsed.llnl.gov/files/programs/unix/latex2html/manual/"><STRONG>LaTeX</STRONG>2<tt>HTML</tt></A> translator Version 2K.1beta (1.47)
4313 <P>
4314 Copyright &#169; 1993, 1994, 1995, 1996,
4315 <A HREF="http://cbl.leeds.ac.uk/nikos/personal.html">Nikos Drakos</A>,
4316 Computer Based Learning Unit, University of Leeds.
4317 <BR>
4318 Copyright &#169; 1997, 1998, 1999,
4319 <A HREF="http://www.maths.mq.edu.au/~ross/">Ross Moore</A>,
4320 Mathematics Department, Macquarie University, Sydney.
4321 <P>
4322 The command line arguments were: <BR>
4323  <STRONG>latex2html</STRONG> <TT>-no_subdir -split 0 -show_section_numbers /tmp/lyx_tmpdir14474Rxoof/lyx_tmpbuf1447IsYCoR/SDCCUdoc.tex</TT>
4324 <P>
4325 The translation was initiated by Karl Bongers on 2001-07-04
4326 <BR><HR><H4>Footnotes</H4>
4327 <DL>
4328 <DT><A NAME="foot456">... anyway</A><A NAME="foot456"
4329  HREF="SDCCUdoc.html#tex2html1"><SUP>1</SUP></A>
4330 <DD>possible exception: if a function is called ONLY from 'interrupt'
4331 functions using a particular bank, it can be declared with the same
4332 'using' attribute as the calling 'interrupt' functions. For instance,
4333 if you have several ISRs using bank one, and all of them call memcpy(),
4334 it might make sense to create a specialized version of memcpy() 'using
4335 1', since this would prevent the ISR from having to save bank zero
4336 to the stack on entry and switch to bank zero before calling the function
4337
4338
4339 </DL><HR>
4340 <!--Navigation Panel-->
4341 <IMG WIDTH="81" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="next_inactive"
4342  SRC="file:/usr/share/latex2html/icons/nx_grp_g.png">
4343 <IMG WIDTH="26" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="up"
4344  SRC="file:/usr/share/latex2html/icons/up_g.png">
4345 <IMG WIDTH="63" HEIGHT="24" ALIGN="BOTTOM" BORDER="0" ALT="previous"
4346  SRC="file:/usr/share/latex2html/icons/prev_g.png">
4347 <BR>
4348 <!--End of Navigation Panel-->
4349 <ADDRESS>
4350 Karl Bongers
4351 2001-07-04
4352 </ADDRESS>
4353 </BODY>
4354 </HTML>