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