git.gag.com Git - fw/sdcc/blob - doc/sdccman.lyx

   1 #LyX 1.2 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 220
   3 \textclass article
   4 \begin_preamble
   5 \usepackage[colorlinks=true,linkcolor=blue]{hyperref}
   6 \end_preamble
   7 \language english
   8 \inputencoding default
   9 \fontscheme pslatex
  10 \graphics default
  11 \paperfontsize default
  12 \spacing single
  13 \papersize Default
  14 \paperpackage a4
  15 \use_geometry 0
  16 \use_amsmath 0
  17 \use_natbib 0
  18 \use_numerical_citations 0
  19 \paperorientation portrait
  20 \secnumdepth 3
  21 \tocdepth 3
  22 \paragraph_separation indent
  23 \defskip medskip
  24 \quotes_language swedish
  25 \quotes_times 2
  26 \papercolumns 1
  27 \papersides 1
  28 \paperpagestyle fancy
  29
  30 \layout Comment
  31
  32 Please note: double dashed longoptions (e.g.
  33  --version) need three dashes in this document to be visable in html and
  34  pdf output.
  35 \layout Title
  36
  37 SDCC Compiler User Guide
  38 \layout Standard
  39
  40
  41 \begin_inset LatexCommand \tableofcontents{}
  42
  43 \end_inset
  44
  45
  46 \layout Section
  47 \pagebreak_top
  48 Introduction
  49 \layout Subsection
  50
  51 About SDCC
  52 \layout Standard
  53
  54
  55 \series bold
  56 SDCC
  57 \series default
  58  is a Freeware, retargettable, optimizing ANSI-C compiler by
  59 \series bold
  60 Sandeep Dutta
  61 \series default
  62  designed for 8 bit Microprocessors.
  63  The current version targets Intel MCS51 based Microprocessors(8051,8052,
  64  etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant.
  65  It can be retargetted for other microprocessors, support for PIC, AVR and
  66  186 is under development.
  67  The entire source code for the compiler is distributed under GPL.
  68  SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
  69  SDCC has extensive language extensions suitable for utilizing various microcont
  70 rollers and underlying hardware effectively.
  71
  72 \newline
  73
  74 \newline
  75 In addition to the MCU specific optimizations SDCC also does a host of standard
  76  optimizations like:
  77 \layout Itemize
  78
  79 global sub expression elimination,
  80 \layout Itemize
  81
  82 loop optimizations (loop invariant, strength reduction of induction variables
  83  and loop reversing),
  84 \layout Itemize
  85
  86 constant folding & propagation,
  87 \layout Itemize
  88
  89 copy propagation,
  90 \layout Itemize
  91
  92 dead code elimination
  93 \layout Itemize
  94
  95 jumptables for
  96 \emph on
  97 switch
  98 \emph default
  99  statements.
 100 \layout Standard
 101
 102 For the back-end SDCC uses a global register allocation scheme which should
 103  be well suited for other 8 bit MCUs.
 104
 105 \newline
 106
 107 \newline
 108 The peep hole optimizer uses a rule based substitution mechanism which is
 109  MCU independent.
 110
 111 \newline
 112
 113 \newline
 114 Supported data-types are:
 115 \layout Itemize
 116
 117 char (8 bits, 1 byte),
 118 \layout Itemize
 119
 120 short and int (16 bits, 2 bytes),
 121 \layout Itemize
 122
 123 long (32 bit, 4 bytes)
 124 \layout Itemize
 125
 126 float (4 byte IEEE).
 127
 128 \layout Standard
 129
 130 The compiler also allows
 131 \emph on
 132 inline assembler code
 133 \emph default
 134  to be embedded anywhere in a function.
 135  In addition, routines developed in assembly can also be called.
 136 \newline
 137
 138 \newline
 139 SDCC also provides an option (--cyclomatic) to report the relative complexity
 140  of a function.
 141  These functions can then be further optimized, or hand coded in assembly
 142  if needed.
 143
 144 \newline
 145
 146 \newline
 147 SDCC also comes with a companion source level debugger SDCDB, the debugger
 148  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 149
 150 \newline
 151
 152 \newline
 153 The latest version can be downloaded from
 154 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 155
 156 \end_inset
 157
 158
 159 \series bold
 160 .
 161 \layout Subsection
 162
 163 Open Source
 164 \layout Standard
 165
 166 All packages used in this compiler system are
 167 \emph on
 168 opensource
 169 \emph default
 170  and
 171 \emph on
 172 freeware
 173 \emph default
 174 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 175  etc) is distributed with the package.
 176  This documentation is maintained using a freeware word processor (LyX).
 177 \newline
 178 This program is free software; you can redistribute it and/or modify it
 179  under the terms of the GNU General Public License
 180 \begin_inset LatexCommand \index{GNU General Public License}
 181
 182 \end_inset
 183
 184
 185 \begin_inset LatexCommand \index{GPL}
 186
 187 \end_inset
 188
 189  as published by the Free Software Foundation; either version 2, or (at
 190  your option) any later version.
 191  This program is distributed in the hope that it will be useful, but WITHOUT
 192  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 193  FOR A PARTICULAR PURPOSE.
 194  See the GNU General Public License for more details.
 195  You should have received a copy of the GNU General Public License along
 196  with this program; if not, write to the Free Software Foundation, 59 Temple
 197  Place - Suite 330, Boston, MA 02111-1307, USA.
 198  In other words, you are welcome to use, share and improve this program.
 199  You are forbidden to forbid anyone else to use, share and improve what
 200  you give them.
 201  Help stamp out software-hoarding!
 202 \layout Subsection
 203
 204 Typographic conventions
 205 \layout Standard
 206
 207 Throughout this manual, we will use the following convention.
 208  Commands you have to type in are printed in
 209 \family sans
 210 \series bold
 211 "sans serif"
 212 \series default
 213 .
 214
 215 \family default
 216  Code samples are printed in
 217 \family typewriter
 218 typewriter font.
 219
 220 \family default
 221  Interesting items and new terms are printed in
 222 \emph on
 223 italic.
 224 \layout Subsection
 225
 226 Compatibility with previous versions
 227 \layout Standard
 228
 229 This version has numerous bug fixes compared with the previous version.
 230  But we also introduced some incompatibilities with older versions.
 231  Not just for the fun of it, but to make the compiler more stable, efficient
 232  and ANSI compliant.
 233
 234 \newline
 235
 236 \layout Itemize
 237
 238 short is now equivalent to int (16 bits), it used to be equivalent to char
 239  (8 bits) which is not ANSI compliant
 240 \layout Itemize
 241
 242 the default directory for gcc-builds where include, library and documention
 243  files are stored is now in /usr/local/share
 244 \layout Itemize
 245
 246 char type parameters to vararg functions are casted to int unless explicitly
 247  casted, e.g.:
 248 \newline
 249
 250 \family typewriter
 251 \SpecialChar ~
 252 \SpecialChar ~
 253 char a=3;
 254 \newline
 255 \SpecialChar ~
 256 \SpecialChar ~
 257 printf ("%d %c
 258 \backslash
 259 n", a, (char)a);
 260 \family default
 261
 262 \newline
 263  will push a as an int and as a char resp.
 264 \layout Itemize
 265
 266 option ---regextend has been removed
 267 \layout Itemize
 268
 269 option ---noregparms has been removed
 270 \layout Itemize
 271
 272 option ---stack-after-data has been removed
 273 \layout Standard
 274
 275
 276 \emph on
 277 <pending: more incompatibilities?>
 278 \layout Subsection
 279
 280 System Requirements
 281 \layout Standard
 282
 283 What do you need before you start installation of SDCC? A computer, and
 284  a desire to compute.
 285  The preferred method of installation is to compile SDCC from source using
 286  GNU gcc and make.
 287  For Windows some pre-compiled binary distributions are available for your
 288  convenience.
 289  You should have some experience with command line tools and compiler use.
 290 \layout Subsection
 291
 292 Other Resources
 293 \layout Standard
 294
 295 The SDCC home page at
 296 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 297
 298 \end_inset
 299
 300  is a great place to find distribution sets.
 301  You can also find links to the user mailing lists that offer help or discuss
 302  SDCC with other SDCC users.
 303  Web links to other SDCC related sites can also be found here.
 304  This document can be found in the DOC directory of the source package as
 305  a text or HTML file.
 306  Some of the other tools (simulator and assembler) included with SDCC contain
 307  their own documentation and can be found in the source distribution.
 308  If you want the latest unreleased software, the complete source package
 309  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 310 \layout Subsection
 311
 312 Wishes for the future
 313 \layout Standard
 314
 315 There are (and always will be) some things that could be done.
 316  Here are some I can think of:
 317 \newline
 318
 319 \layout Standard
 320
 321
 322 \family typewriter
 323 char KernelFunction3(char p) at 0x340;
 324 \newline
 325
 326 \newline
 327
 328 \family default
 329 If you can think of some more, please send them to the list.
 330 \newline
 331
 332 \layout Section
 333
 334 Installation
 335 \begin_inset LatexCommand \index{Installation}
 336
 337 \end_inset
 338
 339
 340 \layout Subsection
 341
 342 Configure Options
 343 \begin_inset LatexCommand \index{Configure Options}
 344
 345 \end_inset
 346
 347
 348 \layout Standard
 349
 350 The install paths, search paths and other options are defined when running
 351  'configure'.
 352  The defaults can be overriden by:
 353 \layout List
 354 \labelwidthstring 00.00.0000
 355
 356 ---prefix see tabel below
 357 \layout List
 358 \labelwidthstring 00.00.0000
 359
 360 ---exec_prefix see tabel below
 361 \layout List
 362 \labelwidthstring 00.00.0000
 363
 364 ---bindir see tabel below
 365 \layout List
 366 \labelwidthstring 00.00.0000
 367
 368 ---datadir see tabel below
 369 \layout List
 370 \labelwidthstring 00.00.0000
 371
 372 docdir environment variable, see tabel below
 373 \layout List
 374 \labelwidthstring 00.00.0000
 375
 376 include_dir_suffix environment variable, see tabel below
 377 \layout List
 378 \labelwidthstring 00.00.0000
 379
 380 lib_dir_suffix environment variable, see tabel below
 381 \layout List
 382 \labelwidthstring 00.00.0000
 383
 384 sdccconf_h_dir_separator environment variable, either / or
 385 \backslash
 386
 387 \backslash
 388  makes sense here.
 389  This character will only be used in sdccconf.h; don't forget it's a C-header,
 390  therefore a double-backslash is needed there.
 391 \layout List
 392 \labelwidthstring 00.00.0000
 393
 394 ---disable-mcs51-port Excludes the Intel mcs51 port
 395 \layout List
 396 \labelwidthstring 00.00.0000
 397
 398 ---disable-gbz80-port Excludes the Gameboy gbz80 port
 399 \layout List
 400 \labelwidthstring 00.00.0000
 401
 402 ---disable-z80-port Excludes the z80 port
 403 \layout List
 404 \labelwidthstring 00.00.0000
 405
 406 ---disable-avr-port Excludes the AVR port
 407 \layout List
 408 \labelwidthstring 00.00.0000
 409
 410 ---disable-ds390-port Excludes the DS390 port
 411 \layout List
 412 \labelwidthstring 00.00.0000
 413
 414 ---disable-pic-port Excludes the PIC port
 415 \layout List
 416 \labelwidthstring 00.00.0000
 417
 418 ---disable-xa51-port Excludes the XA51 port
 419 \layout List
 420 \labelwidthstring 00.00.0000
 421
 422 ---disable-ucsim Disables configuring and building of ucsim
 423 \layout List
 424 \labelwidthstring 00.00.0000
 425
 426 ---disable-device-lib-build Disables automatically building device libraries
 427 \layout List
 428 \labelwidthstring 00.00.0000
 429
 430 ---disable-packihx Disables building packihx
 431 \layout List
 432 \labelwidthstring 00.00.0000
 433
 434 ---enable-libgc Use the Bohem memory allocator.
 435  Lower runtime footprint.
 436 \layout Standard
 437
 438 Furthermore the environment variables CC, CFLAGS, ...
 439  the tools and their arguments can be influenced.
 440  Please see `configure ---help` and the man/info pages of `configure` for
 441  details.
 442 \newline
 443
 444 \newline
 445 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 446  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 447 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 448  At the moment it's not possible to change the default settings (it was
 449  simply never required.
 450 \newline
 451
 452 \newline
 453 These configure options are compiled into the binaries, and can only be
 454  changed by rerunning 'configure' and recompiling SDCC.
 455  The configure options are written in
 456 \emph on
 457 italics
 458 \emph default
 459  to distinguish them from run time environment variables (see section search
 460  paths).
 461 \newline
 462
 463 \newline
 464 The settings for
 465 \begin_inset Quotes sld
 466 \end_inset
 467
 468 Win32 builds
 469 \begin_inset Quotes srd
 470 \end_inset
 471
 472  are used by the SDCC team to build the official Win32 binaries.
 473  The SDCC team uses Mingw32 to build the official Windows binaries, because
 474  it's
 475 \layout Enumerate
 476
 477 open source,
 478 \layout Enumerate
 479
 480 a gcc compiler and last but not least
 481 \layout Enumerate
 482
 483 the binaries can be built by cross compiling on Sourceforge's compile farm.
 484 \layout Standard
 485
 486 See the examples, how to pass the Win32 settings to 'configure'.
 487  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 488  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 489  for Win32.
 490 \newline
 491
 492 \newline
 493 These defaults are:
 494 \newline
 495
 496 \newline
 497
 498 \begin_inset  Tabular
 499 <lyxtabular version="3" rows="8" columns="3">
 500 <features>
 501 <column alignment="left" valignment="top" leftline="true" width="0in">
 502 <column alignment="left" valignment="top" leftline="true" width="0in">
 503 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
 504 <row topline="true" bottomline="true">
 505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 506 \begin_inset Text
 507
 508 \layout Standard
 509
 510 Variable
 511 \end_inset
 512 </cell>
 513 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 514 \begin_inset Text
 515
 516 \layout Standard
 517
 518 default
 519 \end_inset
 520 </cell>
 521 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 522 \begin_inset Text
 523
 524 \layout Standard
 525
 526 Win32 builds
 527 \end_inset
 528 </cell>
 529 </row>
 530 <row topline="true">
 531 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 532 \begin_inset Text
 533
 534 \layout Standard
 535
 536
 537 \emph on
 538 PREFIX
 539 \end_inset
 540 </cell>
 541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 542 \begin_inset Text
 543
 544 \layout Standard
 545
 546 /usr/local
 547 \end_inset
 548 </cell>
 549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 550 \begin_inset Text
 551
 552 \layout Standard
 553
 554
 555 \backslash
 556 sdcc
 557 \end_inset
 558 </cell>
 559 </row>
 560 <row topline="true">
 561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 562 \begin_inset Text
 563
 564 \layout Standard
 565
 566
 567 \emph on
 568 EXEC_PREFIX
 569 \end_inset
 570 </cell>
 571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 572 \begin_inset Text
 573
 574 \layout Standard
 575
 576
 577 \emph on
 578 $PREFIX
 579 \end_inset
 580 </cell>
 581 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 582 \begin_inset Text
 583
 584 \layout Standard
 585
 586
 587 \emph on
 588 $PREFIX
 589 \end_inset
 590 </cell>
 591 </row>
 592 <row topline="true">
 593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 594 \begin_inset Text
 595
 596 \layout Standard
 597
 598
 599 \emph on
 600 BINDIR
 601 \end_inset
 602 </cell>
 603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 604 \begin_inset Text
 605
 606 \layout Standard
 607
 608
 609 \emph on
 610 $EXECPREFIX
 611 \emph default
 612 /bin
 613 \end_inset
 614 </cell>
 615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 616 \begin_inset Text
 617
 618 \layout Standard
 619
 620
 621 \emph on
 622 $EXECPREFIX
 623 \emph default
 624
 625 \backslash
 626 bin
 627 \end_inset
 628 </cell>
 629 </row>
 630 <row topline="true">
 631 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 632 \begin_inset Text
 633
 634 \layout Standard
 635
 636
 637 \emph on
 638 DATADIR
 639 \end_inset
 640 </cell>
 641 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 642 \begin_inset Text
 643
 644 \layout Standard
 645
 646
 647 \emph on
 648 $PREFIX
 649 \emph default
 650 /share
 651 \end_inset
 652 </cell>
 653 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 654 \begin_inset Text
 655
 656 \layout Standard
 657
 658
 659 \emph on
 660 $PREFIX
 661 \end_inset
 662 </cell>
 663 </row>
 664 <row topline="true">
 665 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 666 \begin_inset Text
 667
 668 \layout Standard
 669
 670
 671 \emph on
 672 DOCDIR
 673 \end_inset
 674 </cell>
 675 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 676 \begin_inset Text
 677
 678 \layout Standard
 679
 680
 681 \emph on
 682 $DATADIR
 683 \emph default
 684 /sdcc/doc
 685 \end_inset
 686 </cell>
 687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 688 \begin_inset Text
 689
 690 \layout Standard
 691
 692
 693 \emph on
 694 $DATADIR
 695 \emph default
 696
 697 \backslash
 698 doc
 699 \end_inset
 700 </cell>
 701 </row>
 702 <row topline="true">
 703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 704 \begin_inset Text
 705
 706 \layout Standard
 707
 708
 709 \emph on
 710 INCLUDE_DIR_SUFFIX
 711 \end_inset
 712 </cell>
 713 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 714 \begin_inset Text
 715
 716 \layout Standard
 717
 718 sdcc/include
 719 \end_inset
 720 </cell>
 721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 722 \begin_inset Text
 723
 724 \layout Standard
 725
 726 include
 727 \end_inset
 728 </cell>
 729 </row>
 730 <row topline="true" bottomline="true">
 731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 732 \begin_inset Text
 733
 734 \layout Standard
 735
 736
 737 \emph on
 738 LIB_DIR_SUFFIX
 739 \end_inset
 740 </cell>
 741 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 742 \begin_inset Text
 743
 744 \layout Standard
 745
 746 sdcc/lib
 747 \end_inset
 748 </cell>
 749 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 750 \begin_inset Text
 751
 752 \layout Standard
 753
 754 lib
 755 \end_inset
 756 </cell>
 757 </row>
 758 </lyxtabular>
 759
 760 \end_inset
 761
 762
 763 \newline
 764
 765 \newline
 766
 767 \newline
 768 'configure' also computes relative paths.
 769  This is needed for full relocatability of a binary package and to complete
 770  search paths (see section search paths below):
 771 \newline
 772
 773 \newline
 774
 775 \begin_inset  Tabular
 776 <lyxtabular version="3" rows="4" columns="3">
 777 <features>
 778 <column alignment="left" valignment="top" leftline="true" width="0in">
 779 <column alignment="left" valignment="top" leftline="true" width="0in">
 780 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
 781 <row topline="true" bottomline="true">
 782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 783 \begin_inset Text
 784
 785 \layout Standard
 786
 787 Variable (computed)
 788 \end_inset
 789 </cell>
 790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 791 \begin_inset Text
 792
 793 \layout Standard
 794
 795 default
 796 \end_inset
 797 </cell>
 798 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 799 \begin_inset Text
 800
 801 \layout Standard
 802
 803 Win32 builds
 804 \end_inset
 805 </cell>
 806 </row>
 807 <row topline="true" bottomline="true">
 808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 809 \begin_inset Text
 810
 811 \layout Standard
 812
 813
 814 \emph on
 815 BIN2DATA_DIR
 816 \end_inset
 817 </cell>
 818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 819 \begin_inset Text
 820
 821 \layout Standard
 822
 823 ../share
 824 \end_inset
 825 </cell>
 826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 827 \begin_inset Text
 828
 829 \layout Standard
 830
 831 ..
 832 \backslash
 833
 834 \end_inset
 835 </cell>
 836 </row>
 837 <row bottomline="true">
 838 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 839 \begin_inset Text
 840
 841 \layout Standard
 842
 843
 844 \emph on
 845 PREFIX2BIN_DIR
 846 \end_inset
 847 </cell>
 848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 849 \begin_inset Text
 850
 851 \layout Standard
 852
 853 bin
 854 \end_inset
 855 </cell>
 856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 857 \begin_inset Text
 858
 859 \layout Standard
 860
 861 bin
 862 \end_inset
 863 </cell>
 864 </row>
 865 <row bottomline="true">
 866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 867 \begin_inset Text
 868
 869 \layout Standard
 870
 871
 872 \emph on
 873 PREFIX2DATA_DIR
 874 \end_inset
 875 </cell>
 876 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 877 \begin_inset Text
 878
 879 \layout Standard
 880
 881 share/sdcc
 882 \end_inset
 883 </cell>
 884 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 885 \begin_inset Text
 886
 887 \layout Standard
 888
 889 \end_inset
 890 </cell>
 891 </row>
 892 </lyxtabular>
 893
 894 \end_inset
 895
 896
 897 \newline
 898
 899 \newline
 900 Examples:
 901 \layout LyX-Code
 902
 903 ./configure
 904 \layout LyX-Code
 905
 906 ./configure ---prefix=
 907 \begin_inset Quotes srd
 908 \end_inset
 909
 910 /usr/bin
 911 \begin_inset Quotes srd
 912 \end_inset
 913
 914  ---datadir=
 915 \begin_inset Quotes srd
 916 \end_inset
 917
 918 /usr/share
 919 \begin_inset Quotes srd
 920 \end_inset
 921
 922
 923 \layout LyX-Code
 924
 925 ./configure ---disable-avr-port ---disable-xa51-port
 926 \layout Standard
 927
 928 To crosscompile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw3
 929 2'):
 930 \layout LyX-Code
 931
 932 ./configure
 933 \backslash
 934
 935 \layout LyX-Code
 936
 937   CC=
 938 \begin_inset Quotes srd
 939 \end_inset
 940
 941 i586-mingw32msvc-gcc
 942 \begin_inset Quotes srd
 943 \end_inset
 944
 945  CXX=
 946 \begin_inset Quotes srd
 947 \end_inset
 948
 949 i586-mingw32msvc-g++
 950 \begin_inset Quotes srd
 951 \end_inset
 952
 953
 954 \backslash
 955
 956 \layout LyX-Code
 957
 958   RANLIB=
 959 \begin_inset Quotes srd
 960 \end_inset
 961
 962 i586-mingw32msvc-ranlib
 963 \begin_inset Quotes srd
 964 \end_inset
 965
 966
 967 \backslash
 968
 969 \layout LyX-Code
 970
 971   STRIP=
 972 \begin_inset Quotes srd
 973 \end_inset
 974
 975 i586-mingw32msvc-strip
 976 \begin_inset Quotes srd
 977 \end_inset
 978
 979
 980 \backslash
 981
 982 \layout LyX-Code
 983
 984   ---prefix=
 985 \begin_inset Quotes srd
 986 \end_inset
 987
 988 /sdcc
 989 \begin_inset Quotes srd
 990 \end_inset
 991
 992
 993 \backslash
 994
 995 \layout LyX-Code
 996
 997   ---datadir=
 998 \begin_inset Quotes srd
 999 \end_inset
1000
1001 /sdcc
1002 \begin_inset Quotes srd
1003 \end_inset
1004
1005
1006 \backslash
1007
1008 \layout LyX-Code
1009
1010   docdir=
1011 \begin_inset Quotes srd
1012 \end_inset
1013
1014 /sdcc/doc
1015 \begin_inset Quotes srd
1016 \end_inset
1017
1018
1019 \backslash
1020
1021 \layout LyX-Code
1022
1023   include_dir_suffix=
1024 \begin_inset Quotes srd
1025 \end_inset
1026
1027 include
1028 \begin_inset Quotes srd
1029 \end_inset
1030
1031
1032 \backslash
1033
1034 \layout LyX-Code
1035
1036   lib_dir_suffix=
1037 \begin_inset Quotes srd
1038 \end_inset
1039
1040 lib
1041 \begin_inset Quotes srd
1042 \end_inset
1043
1044
1045 \backslash
1046
1047 \layout LyX-Code
1048
1049   sdccconf_h_dir_separator=
1050 \begin_inset Quotes srd
1051 \end_inset
1052
1053
1054 \backslash
1055
1056 \backslash
1057
1058 \backslash
1059
1060 \backslash
1061
1062 \begin_inset Quotes srd
1063 \end_inset
1064
1065
1066 \backslash
1067
1068 \layout LyX-Code
1069
1070   ---disable-device-lib-build
1071 \backslash
1072
1073 \layout LyX-Code
1074
1075   ---disable-ucsim
1076 \backslash
1077
1078 \layout LyX-Code
1079
1080   ---host=i586-mingw32msvc ---build=unknown-unknown-linux-gnu
1081 \layout Standard
1082
1083 To
1084 \begin_inset Quotes sld
1085 \end_inset
1086
1087 cross
1088 \begin_inset Quotes srd
1089 \end_inset
1090
1091 compile on Cygwin for Mingw32(see also sdcc/support/scripts/sdcc_cygwin_mingw32)
1092 :
1093 \layout LyX-Code
1094
1095 ./configure -C
1096 \backslash
1097
1098 \layout LyX-Code
1099
1100   CFLAGS=
1101 \begin_inset Quotes srd
1102 \end_inset
1103
1104 -mno-cygwin -O2
1105 \begin_inset Quotes srd
1106 \end_inset
1107
1108
1109 \backslash
1110
1111 \layout LyX-Code
1112
1113   LDFLAGS=
1114 \begin_inset Quotes srd
1115 \end_inset
1116
1117 -mno-cygwin
1118 \begin_inset Quotes srd
1119 \end_inset
1120
1121
1122 \backslash
1123
1124 \layout LyX-Code
1125
1126   ---prefix=
1127 \begin_inset Quotes srd
1128 \end_inset
1129
1130 /sdcc
1131 \begin_inset Quotes srd
1132 \end_inset
1133
1134
1135 \backslash
1136
1137 \layout LyX-Code
1138
1139   ---datadir=
1140 \begin_inset Quotes srd
1141 \end_inset
1142
1143 /sdcc
1144 \begin_inset Quotes srd
1145 \end_inset
1146
1147
1148 \backslash
1149
1150 \layout LyX-Code
1151
1152   docdir=
1153 \begin_inset Quotes srd
1154 \end_inset
1155
1156 /sdcc/doc
1157 \begin_inset Quotes srd
1158 \end_inset
1159
1160
1161 \backslash
1162
1163 \layout LyX-Code
1164
1165   include_dir_suffix=
1166 \begin_inset Quotes srd
1167 \end_inset
1168
1169 include
1170 \begin_inset Quotes srd
1171 \end_inset
1172
1173
1174 \backslash
1175
1176 \layout LyX-Code
1177
1178   lib_dir_suffix=
1179 \begin_inset Quotes srd
1180 \end_inset
1181
1182 lib
1183 \begin_inset Quotes srd
1184 \end_inset
1185
1186
1187 \backslash
1188
1189 \layout LyX-Code
1190
1191   sdccconf_h_dir_separator=
1192 \begin_inset Quotes srd
1193 \end_inset
1194
1195
1196 \backslash
1197
1198 \backslash
1199
1200 \backslash
1201
1202 \backslash
1203
1204 \begin_inset Quotes srd
1205 \end_inset
1206
1207
1208 \backslash
1209
1210 \layout LyX-Code
1211
1212   ---disable-ucsim
1213 \layout Standard
1214
1215 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1216  The option '--C' turns on caching, which gives a little bit extra speed.
1217  However if options are changed, it can be necessary to delete the config.cache
1218  file.
1219 \layout Subsection
1220
1221 Install paths
1222 \begin_inset LatexCommand \index{Install paths}
1223
1224 \end_inset
1225
1226
1227 \layout Standard
1228
1229 1.
1230  Binary files (preprocessor, assembler and linker)
1231 \layout Standard
1232
1233
1234 \begin_inset  Tabular
1235 <lyxtabular version="3" rows="2" columns="3">
1236 <features>
1237 <column alignment="left" valignment="top" leftline="true" width="0in">
1238 <column alignment="left" valignment="top" leftline="true" width="0in">
1239 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
1240 <row topline="true" bottomline="true">
1241 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1242 \begin_inset Text
1243
1244 \layout Standard
1245
1246 Path
1247 \end_inset
1248 </cell>
1249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1250 \begin_inset Text
1251
1252 \layout Standard
1253
1254 default
1255 \end_inset
1256 </cell>
1257 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1258 \begin_inset Text
1259
1260 \layout Standard
1261
1262 Win32 builds
1263 \end_inset
1264 </cell>
1265 </row>
1266 <row topline="true" bottomline="true">
1267 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1268 \begin_inset Text
1269
1270 \layout Standard
1271
1272
1273 \emph on
1274 $EXEC_PREFIX
1275 \end_inset
1276 </cell>
1277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1278 \begin_inset Text
1279
1280 \layout Standard
1281
1282 /usr/local/bin
1283 \end_inset
1284 </cell>
1285 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1286 \begin_inset Text
1287
1288 \layout Standard
1289
1290
1291 \backslash
1292 sdcc
1293 \backslash
1294 bin
1295 \end_inset
1296 </cell>
1297 </row>
1298 </lyxtabular>
1299
1300 \end_inset
1301
1302
1303 \newline
1304
1305 \newline
1306 2.
1307  Include files
1308 \layout Standard
1309
1310
1311 \begin_inset  Tabular
1312 <lyxtabular version="3" rows="2" columns="3">
1313 <features>
1314 <column alignment="block" valignment="top" leftline="true" width="1.6in">
1315 <column alignment="left" valignment="top" leftline="true" width="0in">
1316 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
1317 <row topline="true" bottomline="true">
1318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1319 \begin_inset Text
1320
1321 \layout Standard
1322
1323 Path
1324 \end_inset
1325 </cell>
1326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1327 \begin_inset Text
1328
1329 \layout Standard
1330
1331 default
1332 \end_inset
1333 </cell>
1334 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1335 \begin_inset Text
1336
1337 \layout Standard
1338
1339 Win32 builds
1340 \end_inset
1341 </cell>
1342 </row>
1343 <row topline="true" bottomline="true">
1344 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1345 \begin_inset Text
1346
1347 \layout Standard
1348
1349
1350 \emph on
1351 $DATADIR/
1352 \newline
1353 $INCLUDE_DIR_SUFFIX
1354 \end_inset
1355 </cell>
1356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1357 \begin_inset Text
1358
1359 \layout Standard
1360
1361 /usr/local/share/sdcc/include
1362 \end_inset
1363 </cell>
1364 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1365 \begin_inset Text
1366
1367 \layout Standard
1368
1369
1370 \backslash
1371 sdcc
1372 \backslash
1373 include
1374 \end_inset
1375 </cell>
1376 </row>
1377 </lyxtabular>
1378
1379 \end_inset
1380
1381
1382 \newline
1383
1384 \newline
1385 3.
1386  Library files (the
1387 \shape italic
1388 model
1389 \shape default
1390  is auto-appended by the compiler, e.g.
1391  small, large, z80, ds390 etc.)
1392 \layout Standard
1393
1394
1395 \begin_inset  Tabular
1396 <lyxtabular version="3" rows="2" columns="3">
1397 <features>
1398 <column alignment="left" valignment="top" leftline="true" width="0in">
1399 <column alignment="left" valignment="top" leftline="true" width="0in">
1400 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
1401 <row topline="true" bottomline="true">
1402 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1403 \begin_inset Text
1404
1405 \layout Standard
1406
1407 Path
1408 \end_inset
1409 </cell>
1410 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1411 \begin_inset Text
1412
1413 \layout Standard
1414
1415 default
1416 \end_inset
1417 </cell>
1418 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1419 \begin_inset Text
1420
1421 \layout Standard
1422
1423 Win32 builds
1424 \end_inset
1425 </cell>
1426 </row>
1427 <row topline="true" bottomline="true">
1428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1429 \begin_inset Text
1430
1431 \layout Standard
1432
1433
1434 \emph on
1435 $DATADIR/$LIB_DIR_SUFFIX
1436 \end_inset
1437 </cell>
1438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1439 \begin_inset Text
1440
1441 \layout Standard
1442
1443 /usr/local/share/sdcc/lib
1444 \end_inset
1445 </cell>
1446 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1447 \begin_inset Text
1448
1449 \layout Standard
1450
1451
1452 \backslash
1453 sdcc
1454 \backslash
1455 lib
1456 \end_inset
1457 </cell>
1458 </row>
1459 </lyxtabular>
1460
1461 \end_inset
1462
1463
1464 \newline
1465
1466 \newline
1467 4.
1468  Documentation
1469 \layout Standard
1470
1471
1472 \begin_inset  Tabular
1473 <lyxtabular version="3" rows="2" columns="3">
1474 <features>
1475 <column alignment="left" valignment="top" leftline="true" width="0in">
1476 <column alignment="left" valignment="top" leftline="true" width="0in">
1477 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
1478 <row topline="true" bottomline="true">
1479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1480 \begin_inset Text
1481
1482 \layout Standard
1483
1484 Path
1485 \end_inset
1486 </cell>
1487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1488 \begin_inset Text
1489
1490 \layout Standard
1491
1492 default
1493 \end_inset
1494 </cell>
1495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1496 \begin_inset Text
1497
1498 \layout Standard
1499
1500 Win32 builds
1501 \end_inset
1502 </cell>
1503 </row>
1504 <row topline="true" bottomline="true">
1505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1506 \begin_inset Text
1507
1508 \layout Standard
1509
1510
1511 \emph on
1512 $DOCDIR
1513 \end_inset
1514 </cell>
1515 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1516 \begin_inset Text
1517
1518 \layout Standard
1519
1520 /usr/local/share/sdcc/doc
1521 \end_inset
1522 </cell>
1523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1524 \begin_inset Text
1525
1526 \layout Standard
1527
1528
1529 \backslash
1530 sdcc
1531 \backslash
1532 doc
1533 \end_inset
1534 </cell>
1535 </row>
1536 </lyxtabular>
1537
1538 \end_inset
1539
1540
1541 \newline
1542
1543 \newline
1544 The install paths can still be changed during `make install` with e.g.:
1545 \layout LyX-Code
1546
1547 make install prefix=$(HOME)/local/sdcc
1548 \layout Standard
1549
1550 Of course this doesn't change the search paths compiled into the binaries.
1551 \layout Subsection
1552
1553 Search Paths
1554 \begin_inset LatexCommand \index{Search Paths}
1555
1556 \end_inset
1557
1558
1559 \layout Standard
1560
1561 Some search paths or parts of them are determined by configure variables
1562  (in
1563 \emph on
1564 italics
1565 \emph default
1566 , see section above).
1567  Further search paths are determined by environment variables during runtime.
1568
1569 \newline
1570 The paths searched when running the compiler are as follows (the first catch
1571  wins):
1572 \newline
1573
1574 \newline
1575 1.
1576  Binary files (preprocessor, assembler and linker)
1577 \newline
1578
1579 \begin_inset  Tabular
1580 <lyxtabular version="3" rows="4" columns="3">
1581 <features>
1582 <column alignment="left" valignment="top" leftline="true" width="0in">
1583 <column alignment="left" valignment="top" leftline="true" width="0in">
1584 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
1585 <row topline="true" bottomline="true">
1586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1587 \begin_inset Text
1588
1589 \layout Standard
1590
1591 Search path
1592 \end_inset
1593 </cell>
1594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1595 \begin_inset Text
1596
1597 \layout Standard
1598
1599 default
1600 \end_inset
1601 </cell>
1602 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1603 \begin_inset Text
1604
1605 \layout Standard
1606
1607 Win32 builds
1608 \end_inset
1609 </cell>
1610 </row>
1611 <row topline="true">
1612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1613 \begin_inset Text
1614
1615 \layout Standard
1616
1617 $SDCC_HOME/
1618 \emph on
1619 $PPREFIX2BIN_DIR
1620 \end_inset
1621 </cell>
1622 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1623 \begin_inset Text
1624
1625 \layout Standard
1626
1627 $SDCC_HOME/bin
1628 \end_inset
1629 </cell>
1630 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1631 \begin_inset Text
1632
1633 \layout Standard
1634
1635 $SDCC_HOME
1636 \backslash
1637 bin
1638 \end_inset
1639 </cell>
1640 </row>
1641 <row topline="true">
1642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1643 \begin_inset Text
1644
1645 \layout Standard
1646
1647 Path of argv[0] (if available)
1648 \end_inset
1649 </cell>
1650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1651 \begin_inset Text
1652
1653 \layout Standard
1654
1655 Path of argv[0]
1656 \end_inset
1657 </cell>
1658 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1659 \begin_inset Text
1660
1661 \layout Standard
1662
1663 Path of argv[0]
1664 \end_inset
1665 </cell>
1666 </row>
1667 <row topline="true" bottomline="true">
1668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1669 \begin_inset Text
1670
1671 \layout Standard
1672
1673 $PATH
1674 \end_inset
1675 </cell>
1676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1677 \begin_inset Text
1678
1679 \layout Standard
1680
1681 $PATH
1682 \end_inset
1683 </cell>
1684 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1685 \begin_inset Text
1686
1687 \layout Standard
1688
1689 $PATH
1690 \end_inset
1691 </cell>
1692 </row>
1693 </lyxtabular>
1694
1695 \end_inset
1696
1697
1698 \newline
1699
1700 \newline
1701 2.
1702  Include files
1703 \newline
1704
1705 \begin_inset  Tabular
1706 <lyxtabular version="3" rows="6" columns="3">
1707 <features>
1708 <column alignment="block" valignment="top" leftline="true" width="1.5in">
1709 <column alignment="block" valignment="top" leftline="true" width="1.5in">
1710 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0in">
1711 <row topline="true" bottomline="true">
1712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1713 \begin_inset Text
1714
1715 \layout Standard
1716
1717 Search path
1718 \end_inset
1719 </cell>
1720 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1721 \begin_inset Text
1722
1723 \layout Standard
1724
1725 default
1726 \end_inset
1727 </cell>
1728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1729 \begin_inset Text
1730
1731 \layout Standard
1732
1733 Win32 builds
1734 \end_inset
1735 </cell>
1736 </row>
1737 <row topline="true">
1738 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1739 \begin_inset Text
1740
1741 \layout Standard
1742
1743 ---I dir
1744 \end_inset
1745 </cell>
1746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1747 \begin_inset Text
1748
1749 \layout Standard
1750
1751 ---I dir
1752 \end_inset
1753 </cell>
1754 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1755 \begin_inset Text
1756
1757 \layout Standard
1758
1759 ---I dir
1760 \end_inset
1761 </cell>
1762 </row>
1763 <row topline="true">
1764 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1765 \begin_inset Text
1766
1767 \layout Standard
1768
1769 $SDCC_INCLUDE
1770 \end_inset
1771 </cell>
1772 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1773 \begin_inset Text
1774
1775 \layout Standard
1776
1777 $SDCC_INCLUDE
1778 \end_inset
1779 </cell>
1780 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1781 \begin_inset Text
1782
1783 \layout Standard
1784
1785 $SDCC_INCLUDE
1786 \end_inset
1787 </cell>
1788 </row>
1789 <row topline="true">
1790 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1791 \begin_inset Text
1792
1793 \layout Standard
1794
1795 $SDCC_HOME/
1796 \newline
1797
1798 \emph on
1799 $PREFIX2DATA_DIR/
1800 \newline
1801 $INCLUDE_DIR_SUFFIX
1802 \end_inset
1803 </cell>
1804 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1805 \begin_inset Text
1806
1807 \layout Standard
1808
1809 $SDCC_ HOME/
1810 \newline
1811 share/sdcc/
1812 \newline
1813 include
1814 \end_inset
1815 </cell>
1816 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1817 \begin_inset Text
1818
1819 \layout Standard
1820
1821 $SDCC_HOME
1822 \backslash
1823 include
1824 \end_inset
1825 </cell>
1826 </row>
1827 <row topline="true">
1828 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1829 \begin_inset Text
1830
1831 \layout Standard
1832
1833 path(argv[0])/
1834 \newline
1835
1836 \emph on
1837 $BIN2DATADIR/
1838 \emph default
1839
1840 \newline
1841
1842 \emph on
1843 $INCLUDE_DIR_SUFFIX
1844 \end_inset
1845 </cell>
1846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1847 \begin_inset Text
1848
1849 \layout Standard
1850
1851 path(argv[0])/
1852 \newline
1853 ../sdcc/include
1854 \newline
1855 \SpecialChar ~
1856 \SpecialChar ~
1857 \SpecialChar ~
1858 \SpecialChar ~
1859 \SpecialChar ~
1860 \SpecialChar ~
1861 \SpecialChar ~
1862 \SpecialChar ~
1863 \SpecialChar ~
1864 \SpecialChar ~
1865 \SpecialChar ~
1866 \SpecialChar ~
1867 \SpecialChar ~
1868 \SpecialChar ~
1869 \SpecialChar ~
1870 \SpecialChar ~
1871 \SpecialChar ~
1872 \SpecialChar ~
1873 \SpecialChar ~
1874 \SpecialChar ~
1875 \SpecialChar ~
1876 \SpecialChar ~
1877 \SpecialChar ~
1878 \SpecialChar ~
1879 \SpecialChar ~
1880 \SpecialChar ~
1881 \SpecialChar ~
1882 \SpecialChar ~
1883 \SpecialChar ~
1884 \SpecialChar ~
1885 \SpecialChar ~
1886 \SpecialChar ~
1887 \SpecialChar ~
1888 \SpecialChar ~
1889 \SpecialChar ~
1890 \SpecialChar ~
1891 \SpecialChar ~
1892 \SpecialChar ~
1893
1894 \end_inset
1895 </cell>
1896 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1897 \begin_inset Text
1898
1899 \layout Standard
1900
1901 path(argv[0])
1902 \backslash
1903 ..
1904 \backslash
1905 include
1906 \end_inset
1907 </cell>
1908 </row>
1909 <row topline="true" bottomline="true">
1910 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1911 \begin_inset Text
1912
1913 \layout Standard
1914
1915
1916 \emph on
1917 $DATADIR/
1918 \emph default
1919
1920 \newline
1921
1922 \emph on
1923 $INCLUDE_DIR_SUFFIX
1924 \end_inset
1925 </cell>
1926 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1927 \begin_inset Text
1928
1929 \layout Standard
1930
1931 /usr/local/share/sdcc/
1932 \newline
1933 include
1934 \end_inset
1935 </cell>
1936 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1937 \begin_inset Text
1938
1939 \layout Standard
1940
1941 (not on Win32)
1942 \end_inset
1943 </cell>
1944 </row>
1945 </lyxtabular>
1946
1947 \end_inset
1948
1949
1950 \newline
1951
1952 \newline
1953  The option ---nostdinc disables the last two search paths.
1954 \newline
1955
1956 \newline
1957 3.
1958  Library files
1959 \newline
1960 With the exception of
1961 \begin_inset Quotes sld
1962 \end_inset
1963
1964 ---L dir
1965 \begin_inset Quotes srd
1966 \end_inset
1967
1968  the
1969 \shape italic
1970 model
1971 \shape default
1972  is auto-appended by the compiler (e.g.
1973  small, large, z80, ds390 etc.).
1974
1975 \newline
1976
1977 \begin_inset  Tabular
1978 <lyxtabular version="3" rows="6" columns="3">
1979 <features>
1980 <column alignment="block" valignment="top" leftline="true" width="1.7in">
1981 <column alignment="left" valignment="top" leftline="true" width="1.2in">
1982 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
1983 <row topline="true" bottomline="true">
1984 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1985 \begin_inset Text
1986
1987 \layout Standard
1988
1989 Search path
1990 \end_inset
1991 </cell>
1992 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
1993 \begin_inset Text
1994
1995 \layout Standard
1996
1997 default
1998 \end_inset
1999 </cell>
2000 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2001 \begin_inset Text
2002
2003 \layout Standard
2004
2005 Win32 builds
2006 \end_inset
2007 </cell>
2008 </row>
2009 <row topline="true">
2010 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2011 \begin_inset Text
2012
2013 \layout Standard
2014
2015 ---L dir
2016 \end_inset
2017 </cell>
2018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2019 \begin_inset Text
2020
2021 \layout Standard
2022
2023 ---L dir
2024 \end_inset
2025 </cell>
2026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2027 \begin_inset Text
2028
2029 \layout Standard
2030
2031 ---L dir
2032 \end_inset
2033 </cell>
2034 </row>
2035 <row topline="true">
2036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2037 \begin_inset Text
2038
2039 \layout Standard
2040
2041 $SDCC_LIB/
2042 \newline
2043
2044 \emph on
2045 <model>
2046 \end_inset
2047 </cell>
2048 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2049 \begin_inset Text
2050
2051 \layout Standard
2052
2053 $SDCC_LIB/
2054 \newline
2055
2056 \emph on
2057 <model>
2058 \end_inset
2059 </cell>
2060 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2061 \begin_inset Text
2062
2063 \layout Standard
2064
2065 $SDCC_LIB
2066 \backslash
2067
2068 \newline
2069
2070 \emph on
2071 <model>
2072 \end_inset
2073 </cell>
2074 </row>
2075 <row topline="true">
2076 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2077 \begin_inset Text
2078
2079 \layout Standard
2080
2081 $SDCC_HOME/
2082 \newline
2083
2084 \emph on
2085 $PREFIX2DATA_DIR/
2086 \newline
2087 $LIB_DIR_SUFFIX/<model>
2088 \end_inset
2089 </cell>
2090 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2091 \begin_inset Text
2092
2093 \layout Standard
2094
2095 $SDCC_HOME/
2096 \newline
2097 share/sdcc/
2098 \newline
2099 lib/
2100 \emph on
2101 <model>
2102 \end_inset
2103 </cell>
2104 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2105 \begin_inset Text
2106
2107 \layout Standard
2108
2109 $SDCC_HOME
2110 \backslash
2111 lib
2112 \backslash
2113
2114 \emph on
2115
2116 \newline
2117 <model>
2118 \end_inset
2119 </cell>
2120 </row>
2121 <row topline="true">
2122 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2123 \begin_inset Text
2124
2125 \layout Standard
2126
2127 path(argv[0])/
2128 \newline
2129
2130 \emph on
2131 $BIN2DATADIR/
2132 \emph default
2133
2134 \newline
2135
2136 \emph on
2137 $LIB_DIR_SUFFIX/<model>
2138 \end_inset
2139 </cell>
2140 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2141 \begin_inset Text
2142
2143 \layout Standard
2144
2145 path(argv[0])/
2146 \newline
2147 ../sdcc/lib/
2148 \emph on
2149 <model>
2150 \newline
2151 \SpecialChar ~
2152 \SpecialChar ~
2153 \SpecialChar ~
2154 \SpecialChar ~
2155 \SpecialChar ~
2156 \SpecialChar ~
2157 \SpecialChar ~
2158 \SpecialChar ~
2159 \SpecialChar ~
2160 \SpecialChar ~
2161 \SpecialChar ~
2162 \SpecialChar ~
2163 \SpecialChar ~
2164 \SpecialChar ~
2165 \SpecialChar ~
2166 \SpecialChar ~
2167 \SpecialChar ~
2168 \SpecialChar ~
2169 \SpecialChar ~
2170 \SpecialChar ~
2171 \SpecialChar ~
2172 \SpecialChar ~
2173 \SpecialChar ~
2174 \SpecialChar ~
2175 \SpecialChar ~
2176 \SpecialChar ~
2177 \SpecialChar ~
2178 \SpecialChar ~
2179 \SpecialChar ~
2180 \SpecialChar ~
2181 \SpecialChar ~
2182 \SpecialChar ~
2183 \SpecialChar ~
2184 \SpecialChar ~
2185 \SpecialChar ~
2186 \SpecialChar ~
2187 \SpecialChar ~
2188 \SpecialChar ~
2189 \SpecialChar ~
2190
2191 \end_inset
2192 </cell>
2193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2194 \begin_inset Text
2195
2196 \layout Standard
2197
2198 path(argv[0])
2199 \backslash
2200
2201 \newline
2202 ..
2203 \backslash
2204 lib
2205 \backslash
2206
2207 \emph on
2208 <model>
2209 \newline
2210 \SpecialChar ~
2211 \SpecialChar ~
2212 \SpecialChar ~
2213 \SpecialChar ~
2214 \SpecialChar ~
2215 \SpecialChar ~
2216 \SpecialChar ~
2217 \SpecialChar ~
2218 \SpecialChar ~
2219 \SpecialChar ~
2220 \SpecialChar ~
2221 \SpecialChar ~
2222 \SpecialChar ~
2223 \SpecialChar ~
2224 \SpecialChar ~
2225 \SpecialChar ~
2226 \SpecialChar ~
2227 \SpecialChar ~
2228 \SpecialChar ~
2229 \SpecialChar ~
2230 \SpecialChar ~
2231 \SpecialChar ~
2232 \SpecialChar ~
2233 \SpecialChar ~
2234 \SpecialChar ~
2235 \SpecialChar ~
2236 \SpecialChar ~
2237 \SpecialChar ~
2238 \SpecialChar ~
2239 \SpecialChar ~
2240 \SpecialChar ~
2241 \SpecialChar ~
2242 \SpecialChar ~
2243 \SpecialChar ~
2244 \SpecialChar ~
2245
2246 \end_inset
2247 </cell>
2248 </row>
2249 <row topline="true" bottomline="true">
2250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2251 \begin_inset Text
2252
2253 \layout Standard
2254
2255
2256 \emph on
2257 $DATADIR/
2258 \newline
2259 $LIB_DIR_SUFFIX/<model>
2260 \end_inset
2261 </cell>
2262 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2263 \begin_inset Text
2264
2265 \layout Standard
2266
2267 /usr/local/share/sdcc/
2268 \newline
2269 lib/
2270 \emph on
2271 <model>
2272 \end_inset
2273 </cell>
2274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2275 \begin_inset Text
2276
2277 \layout Standard
2278
2279 (not on Win32)
2280 \end_inset
2281 </cell>
2282 </row>
2283 </lyxtabular>
2284
2285 \end_inset
2286
2287
2288 \layout Comment
2289
2290 Don't delete any of the stray spaces in the table above without checking
2291  the HTML output (last line)!
2292 \layout Standard
2293
2294 \SpecialChar ~
2295
2296 \newline
2297 The option ---nostdlib disables the last two search paths.
2298 \layout Subsection
2299
2300 Building SDCC
2301 \begin_inset LatexCommand \index{Building SDCC}
2302
2303 \end_inset
2304
2305
2306 \layout Subsubsection
2307
2308 Building SDCC on Linux
2309 \layout Enumerate
2310
2311
2312 \series medium
2313 Download the source package
2314 \series default
2315  either from the SDCC CVS repository or from the
2316 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
2317
2318 \end_inset
2319
2320
2321 \series medium
2322 , it will be named something like sdcc
2323 \series default
2324 .src
2325 \series medium
2326 .t
2327 \series default
2328 ar.
2329 \series medium
2330 gz.
2331 \layout Enumerate
2332
2333
2334 \series medium
2335 Bring up a command line terminal, such as xterm.
2336 \layout Enumerate
2337
2338
2339 \series medium
2340 Unpack the file using a command like:
2341 \family sans
2342 \series bold
2343 "tar -xzf sdcc.src.tar.gz
2344 \family default
2345 \series default
2346 "
2347 \series medium
2348 , this will create a sub-directory called sdcc with all of the sources.
2349 \layout Enumerate
2350
2351 Change directory into the main SDCC directory, for example type:
2352 \family sans
2353 \series bold
2354 "cd sdcc
2355 \series default
2356 ".
2357 \layout Enumerate
2358
2359
2360 \series medium
2361 Type
2362 \family sans
2363 \series bold
2364 "./configure
2365 \family default
2366 \series default
2367 ".
2368  This configures the package for compilation on your system.
2369 \layout Enumerate
2370
2371
2372 \series medium
2373 Type
2374 \family sans
2375 \series bold
2376 "make
2377 \family default
2378 \series default
2379 "
2380 \series medium
2381 .
2382
2383 \series default
2384  All of the source packages will compile, this can take a while.
2385 \layout Enumerate
2386
2387
2388 \series medium
2389 Type
2390 \family sans
2391 \series bold
2392 "make install"
2393 \family default
2394 \series default
2395  as root
2396 \series medium
2397 .
2398
2399 \series default
2400  This copies the binary executables, the include files, the libraries and
2401  the documentation to the install directories.
2402 \layout Subsubsection
2403
2404 Building SDCC on OSX 2.x
2405 \layout Standard
2406
2407 Follow the instruction for Linux.
2408 \newline
2409
2410 \newline
2411 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
2412 )) fails to compile SDCC.
2413  Fortunately there's also gcc 2.9.x installed, which works fine.
2414  This compiler can be selected by running 'configure' with:
2415 \layout LyX-Code
2416
2417 ./configure CC=gcc2 CXX=g++2
2418 \layout Subsubsection
2419
2420 Crosscompiling SDCC on Linux for Windows
2421 \layout Standard
2422
2423 With the Mingw32 gcc crosscompiler it's easy to compile SDCC for Win32.
2424  See section 'Configure Options'.
2425 \layout Subsubsection
2426
2427 Building SDCC on Windows
2428 \layout Standard
2429
2430 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
2431  built on Windows.
2432  They use Unix-sockets, which are not available on Win32.
2433 \layout Subsubsection
2434
2435 Windows Install Using a Binary Package
2436 \layout Enumerate
2437
2438 Download the binary package and unpack it using your favorite unpacking
2439  tool (gunzip, WinZip, etc).
2440  This should unpack to a group of sub-directories.
2441  An example directory structure after unpacking the mingw32 package is:
2442  c:
2443 \backslash
2444 sdcc
2445 \backslash
2446 bin for the executables, c:
2447 \backslash
2448 sdcc
2449 \backslash
2450 include and c:
2451 \backslash
2452 sdcc
2453 \backslash
2454 lib for the include and libraries.
2455 \layout Enumerate
2456
2457 Adjust your environment variable PATH to include the location of the bin
2458  directory or start sdcc using the full path.
2459 \layout Subsubsection
2460
2461 Building SDCC using Cygwin and Mingw32
2462 \layout Standard
2463
2464 For building and installing a Cygwin executable follow the instructions
2465  for Linux.
2466 \newline
2467
2468 \newline
2469 On Cygwin a
2470 \begin_inset Quotes sld
2471 \end_inset
2472
2473 native
2474 \begin_inset Quotes srd
2475 \end_inset
2476
2477  Win32-binary can be built, which will not need the Cygwin-DLL.
2478  For the necessary 'configure' options see section 'configure options' or
2479  the script 'sdcc/support/scripts/sdcc_cygwinmingw32'.
2480 \newline
2481
2482 \newline
2483 In order to install Cygwin on Windows download setup.exe from
2484 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
2485
2486 \end_inset
2487
2488 .
2489  Run it, set the
2490 \begin_inset Quotes sld
2491 \end_inset
2492
2493 default text file type
2494 \begin_inset Quotes srd
2495 \end_inset
2496
2497  to
2498 \begin_inset Quotes sld
2499 \end_inset
2500
2501 unix
2502 \begin_inset Quotes srd
2503 \end_inset
2504
2505  and download/install at least the following packages.
2506  Some packages are selected by default, others will be automatically selected
2507  because of dependencies with the manually selected packages.
2508  Never deselect these packages!
2509 \layout Itemize
2510
2511 flex
2512 \layout Itemize
2513
2514 bison
2515 \layout Itemize
2516
2517 gcc ; version 3.x is fine, no need to use the old 2.9x
2518 \layout Itemize
2519
2520 binutils ; selected with gcc
2521 \layout Itemize
2522
2523 make
2524 \layout Itemize
2525
2526 rxvt ; a nice console, which makes life much easier under windoze (see below)
2527 \layout Itemize
2528
2529 man ; not really needed for building SDCC, but you'll miss it sooner or
2530  later
2531 \layout Itemize
2532
2533 less ; not really needed for building SDCC, but you'll miss it sooner or
2534  later
2535 \layout Itemize
2536
2537 cvs ; only if you use CVS access
2538 \layout Standard
2539
2540 If you want to develop something you'll need:
2541 \layout Itemize
2542
2543 python ; for the regression tests
2544 \layout Itemize
2545
2546 gdb ; the gnu debugger, together with the nice GUI
2547 \begin_inset Quotes sld
2548 \end_inset
2549
2550 insight
2551 \begin_inset Quotes srd
2552 \end_inset
2553
2554
2555 \layout Itemize
2556
2557 openssh ; to access the CF or commit changes
2558 \layout Itemize
2559
2560 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
2561  use autoconf-stable!
2562 \layout Standard
2563
2564 rxvt is a nice console with history.
2565  Replace in your cygwin.bat the line
2566 \layout LyX-Code
2567
2568 bash --login -i
2569 \layout Standard
2570
2571 with (one line):
2572 \layout LyX-Code
2573
2574 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
2575 \layout LyX-Code
2576
2577      -bg black -fg white -geometry 100x65 -e bash --login
2578 \layout Standard
2579
2580 Text selected with the mouse is automatically copied to the clipboard, pasting
2581  works with shift-insert.
2582 \newline
2583
2584 \newline
2585 The other good tip is to make sure you have no //c/-style paths anywhere,
2586  use /cygdrive/c/ instead.
2587  Using // invokes a network lookup which is very slow.
2588  If you think
2589 \begin_inset Quotes sld
2590 \end_inset
2591
2592 cygdrive
2593 \begin_inset Quotes srd
2594 \end_inset
2595
2596  is too long, you can change it with e.g.
2597 \layout LyX-Code
2598
2599 mount -s -u -c /mnt
2600 \layout Standard
2601
2602 SDCC sources use the unix line ending LF.
2603  Life is much easier, if you store the source tree on a drive, which is
2604  mount in binary mode.
2605  And use an editor which can handle LF-only line endings.
2606  Make sure not to commit files with windows line endings.
2607 \layout Subsubsection
2608
2609 Windows Install Using Microsoft Visual C++ 6.0/NET
2610 \layout Standard
2611
2612
2613 \series medium
2614 Download the source package
2615 \series default
2616  either from the SDCC CVS repository or from the
2617 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
2618
2619 \end_inset
2620
2621
2622 \series medium
2623 , it will be named something like sdcc
2624 \series default
2625 .src
2626 \series medium
2627 .tgz.
2628
2629 \series default
2630  SDCC is distributed with all the projects, workspaces, and files you need
2631  to build it using Visual C++ 6.0/NET.
2632  The workspace name is 'sdcc.dsw'.
2633  Please note that as it is now, all the executables are created in a folder
2634  called sdcc
2635 \backslash
2636 bin_vc.
2637  Once built you need to copy the executables from sdcc
2638 \backslash
2639 bin_vc to sdcc
2640 \backslash
2641 bin before runnng SDCC.
2642
2643 \newline
2644
2645 \newline
2646 In order to build SDCC with Visual C++ 6.0/NET you need win32 executables
2647  of bison.exe, flex.exe, and gawk.exe.
2648  One good place to get them is
2649 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
2650
2651 \end_inset
2652
2653
2654 \newline
2655
2656 \newline
2657 Download the file UnxUtils
2658 \begin_inset LatexCommand \index{UnxUtils}
2659
2660 \end_inset
2661
2662 .zip.
2663  Now you have to install the utilities and setup Visual C++ so it can locate
2664  the required programs.
2665  Here there are two alternatives (choose one!):
2666 \layout Enumerate
2667
2668 The easy way:
2669 \newline
2670
2671 \newline
2672 a) Extract UnxUtils.zip to your C:
2673 \backslash
2674  hard disk PRESERVING the original paths, otherwise bison won't work.
2675  (If you are using WinZip make certain that 'Use folder names' is selected)
2676 \newline
2677
2678 \newline
2679 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
2680  in 'Show directories for:' select 'Executable files', and in the directories
2681  window add a new path: 'C:
2682 \backslash
2683 user
2684 \backslash
2685 local
2686 \backslash
2687 wbin', click ok.
2688 \newline
2689
2690 \newline
2691 (As a side effect, you get a bunch of Unix utilities that could be useful,
2692  such as diff and patch.)
2693 \layout Enumerate
2694
2695 A more compact way:
2696 \newline
2697
2698 \newline
2699 This one avoids extracting a bunch of files you may not use, but requires
2700  some extra work:
2701 \newline
2702
2703 \newline
2704 a) Create a directory were to put the tools needed, or use a directory already
2705  present.
2706  Say for example 'C:
2707 \backslash
2708 util'.
2709 \newline
2710
2711 \newline
2712 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
2713  to such directory WITHOUT preserving the original paths.
2714  (If you are using WinZip make certain that 'Use folder names' is not selected)
2715 \newline
2716
2717 \newline
2718 c) Rename bison.exe to '_bison.exe'.
2719 \newline
2720
2721 \newline
2722 d) Create a batch file 'bison.bat' in 'C:
2723 \backslash
2724 util
2725 \backslash
2726 ' and add these lines:
2727 \newline
2728 \SpecialChar ~
2729 \SpecialChar ~
2730 set BISON_SIMPLE=C:
2731 \backslash
2732 util
2733 \backslash
2734 bison.simple
2735 \newline
2736 \SpecialChar ~
2737 \SpecialChar ~
2738 set BISON_HAIRY=C:
2739 \backslash
2740 util
2741 \backslash
2742 bison.hairy
2743 \newline
2744 \SpecialChar ~
2745 \SpecialChar ~
2746 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
2747 \newline
2748
2749 \newline
2750 Steps 'c' and 'd' are needed because bison requires by default that the
2751  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
2752  '/usr/local/share/' I think.
2753  So it is necessary to tell bison where those files are located if they
2754  are not in such directory.
2755  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
2756 \newline
2757
2758 \newline
2759 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
2760  in 'Show directories for:' select 'Executable files', and in the directories
2761  window add a new path: 'c:
2762 \backslash
2763 util', click ok.
2764  Note that you can use any other path instead of 'c:
2765 \backslash
2766 util', even the path where the Visual C++ tools are, probably: 'C:
2767 \backslash
2768 Program Files
2769 \backslash
2770 Microsoft Visual Studio
2771 \backslash
2772 Common
2773 \backslash
2774 Tools'.
2775  So you don't have to execute step 'e' :)
2776 \layout Standard
2777
2778 That is it.
2779  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
2780  the executables from sdcc
2781 \backslash
2782 bin_vc to sdcc
2783 \backslash
2784 bin, and you can compile using sdcc.
2785 \layout Subsubsection
2786
2787 Windows Install Using Borland
2788 \layout Enumerate
2789
2790 From the sdcc directory, run the command "make -f Makefile.bcc".
2791  This should regenerate all the .exe files in the bin directory except for
2792  sdcdb.exe (which currently doesn't build under Borland C++).
2793 \layout Enumerate
2794
2795 If you modify any source files and need to rebuild, be aware that the dependanci
2796 es may not be correctly calculated.
2797  The safest option is to delete all .obj files and run the build again.
2798  From a Cygwin BASH prompt, this can easily be done with the commmand:
2799 \newline
2800
2801 \newline
2802
2803 \family sans
2804 \series bold
2805 find .
2806
2807 \backslash
2808 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
2809 \backslash
2810 ) -print -exec rm {}
2811 \backslash
2812 ;
2813 \family default
2814 \series default
2815
2816 \newline
2817
2818 \newline
2819 or on Windows NT/2000/XP from the command prompt with the commmand:
2820 \newline
2821
2822 \family sans
2823 \series bold
2824
2825 \newline
2826 del /s *.obj *.lib *.rul
2827 \family default
2828 \series default
2829  from the sdcc directory.
2830 \layout Subsection
2831
2832 Building the Documentation
2833 \layout Standard
2834
2835 ...
2836  coming soon
2837 \layout Subsection
2838
2839 Testing out the SDCC Compiler
2840 \layout Standard
2841
2842 The first thing you should do after installing your SDCC compiler is to
2843  see if it runs.
2844  Type
2845 \family sans
2846 \series bold
2847 "sdcc ---version"
2848 \begin_inset LatexCommand \index{version}
2849
2850 \end_inset
2851
2852
2853 \family default
2854 \series default
2855  at the prompt, and the program should run and tell you the version.
2856  If it doesn't run, or gives a message about not finding sdcc program, then
2857  you need to check over your installation.
2858  Make sure that the sdcc bin directory is in your executable search path
2859  defined by the PATH environment setting (see the Trouble-shooting section
2860  for suggestions).
2861  Make sure that the sdcc program is in the bin folder, if not perhaps something
2862  did not install correctly.
2863 \newline
2864
2865 \newline
2866
2867 \series medium
2868 SDCC
2869 \series default
2870 is commonly installed as described in section
2871 \begin_inset Quotes sld
2872 \end_inset
2873
2874 Install and search paths
2875 \begin_inset Quotes srd
2876 \end_inset
2877
2878
2879 \newline
2880
2881 \newline
2882
2883 \series medium
2884 Make sure the compiler works on a very simple example.
2885  Type in the following test.c program using your favorite
2886 \series default
2887 ascii
2888 \series medium
2889 editor:
2890 \series default
2891
2892 \newline
2893
2894 \family typewriter
2895
2896 \newline
2897 char test;
2898 \newline
2899
2900 \newline
2901 void main(void) {
2902 \newline
2903 \SpecialChar ~
2904 \SpecialChar ~
2905 \SpecialChar ~
2906 \SpecialChar ~
2907 test=0;
2908 \newline
2909 }
2910 \family default
2911
2912 \newline
2913
2914 \emph on
2915
2916 \newline
2917
2918 \series medium
2919 \emph default
2920 Compile this using the following command:
2921 \family sans
2922 \series bold
2923 "sdcc -c test.c".
2924
2925 \family default
2926 \series default
2927
2928 \series medium
2929 If all goes well, the compiler will generate a test.asm and test.rel file.
2930  Congratulations, you've just compiled your first program with SDCC.
2931  We used the -c option to tell SDCC not to link the generated code, just
2932  to keep things simple for this step.
2933 \series default
2934
2935 \newline
2936
2937 \newline
2938
2939 \series medium
2940 The next step is to try it with the linker.
2941  Type in
2942 \family sans
2943 \series bold
2944 "sdcc test.c
2945 \family default
2946 \series default
2947 "
2948 \series medium
2949 .
2950  If all goes well the compiler will link with the libraries and produce
2951  a test.ihx output file.
2952  If this step fails
2953 \series default
2954
2955 \series medium
2956 (no test.ihx, and the linker generates warnings), then the problem is most
2957  likely that sdcc cannot find the
2958 \series default
2959 /
2960 \series medium
2961 usr/local/share/sdcc/lib directory
2962 \series default
2963
2964 \series medium
2965 (see the Install trouble-shooting section for suggestions).
2966 \series default
2967
2968 \newline
2969
2970 \newline
2971
2972 \series medium
2973 The final test is to ensure sdcc can use the
2974 \series default
2975 standard
2976 \series medium
2977  header files and libraries.
2978  Edit test.c and change it to the following:
2979 \series default
2980
2981 \newline
2982
2983 \newline
2984
2985 \family typewriter
2986 #include <string.h>
2987 \newline
2988
2989 \newline
2990 char str1[10];
2991 \newline
2992
2993 \newline
2994 void main(void) {
2995 \newline
2996 \SpecialChar ~
2997 \SpecialChar ~
2998 strcpy(str1, "testing");
2999 \newline
3000 }
3001 \newline
3002
3003 \newline
3004
3005 \family default
3006 \series medium
3007 Compile this by typing
3008 \family sans
3009 \series bold
3010 "sdcc test.c"
3011 \family default
3012 \series medium
3013 .
3014  This should generate a test.ihx output file, and it should give no warnings
3015  such as not finding the string.h file.
3016  If it cannot find the string.h file, then the problem is that sdcc cannot
3017  find the /usr/local/share/sdcc/include directory
3018 \series default
3019
3020 \series medium
3021 (see the Install trouble-shooting section for suggestions).
3022 \layout Subsection
3023
3024 Install Trouble-shooting
3025 \begin_inset LatexCommand \index{Install Trouble-shooting}
3026
3027 \end_inset
3028
3029
3030 \layout Subsubsection
3031
3032 SDCC does not build correctly.
3033 \layout Standard
3034
3035 A thing to try is starting from scratch by unpacking the .tgz source package
3036  again in an empty directory.
3037  Configure it like:
3038 \newline
3039
3040 \newline
3041
3042 \family sans
3043 \series bold
3044 ./configure 2>&1 | tee configure.log
3045 \family default
3046 \series default
3047
3048 \newline
3049
3050 \newline
3051 and build it like:
3052 \newline
3053
3054 \newline
3055
3056 \family sans
3057 \series bold
3058 make 2>&1 | tee make.log
3059 \family default
3060 \series default
3061
3062 \newline
3063
3064 \newline
3065 If anything goes wrong, you can review the log files to locate the problem.
3066  Or a relevant part of this can be attached to an email that could be helpful
3067  when requesting help from the mailing list.
3068 \layout Subsubsection
3069
3070 What the
3071 \begin_inset Quotes sld
3072 \end_inset
3073
3074 ./configure
3075 \begin_inset Quotes srd
3076 \end_inset
3077
3078  does
3079 \layout Standard
3080
3081 The
3082 \begin_inset Quotes sld
3083 \end_inset
3084
3085 ./configure
3086 \begin_inset Quotes srd
3087 \end_inset
3088
3089  command is a script that analyzes your system and performs some configuration
3090  to ensure the source package compiles on your system.
3091  It will take a few minutes to run, and will compile a few tests to determine
3092  what compiler features are installed.
3093 \layout Subsubsection
3094
3095 What the
3096 \begin_inset Quotes sld
3097 \end_inset
3098
3099 make
3100 \begin_inset Quotes srd
3101 \end_inset
3102
3103  does.
3104 \layout Standard
3105
3106 This runs the GNU make tool, which automatically compiles all the source
3107  packages into the final installed binary executables.
3108 \layout Subsubsection
3109
3110 What the
3111 \begin_inset Quotes sld
3112 \end_inset
3113
3114 make install
3115 \begin_inset Quotes erd
3116 \end_inset
3117
3118  command does.
3119 \layout Standard
3120
3121 This will install the compiler, other executables libraries and include
3122  files in to the appropriate directories.
3123  See section
3124 \begin_inset Quotes sld
3125 \end_inset
3126
3127 Install and Search PATHS
3128 \begin_inset Quotes srd
3129 \end_inset
3130
3131 .
3132 \newline
3133 On most systems you will need super-user privilages to do this.
3134 \layout Subsection
3135
3136 Components of SDCC
3137 \layout Standard
3138
3139 SDCC is not just a compiler, but a collection of tools by various developers.
3140  These include linkers, assemblers, simulators and other components.
3141  Here is a summary of some of the components.
3142  Note that the included simulator and assembler have separate documentation
3143  which you can find in the source package in their respective directories.
3144  As SDCC grows to include support for other processors, other packages from
3145  various developers are included and may have their own sets of documentation.
3146 \newline
3147
3148 \newline
3149 You might want to look at the files which are installed in <installdir>.
3150  At the time of this writing, we find the following programs for gcc-builds:
3151 \newline
3152
3153 \newline
3154 In <installdir>/bin:
3155 \layout Itemize
3156
3157 sdcc - The compiler.
3158 \layout Itemize
3159
3160 sdcpp - The C preprocessor.
3161 \layout Itemize
3162
3163 asx8051 - The assembler for 8051 type processors.
3164 \layout Itemize
3165
3166 as-z80
3167 \series bold
3168 ,
3169 \series default
3170 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
3171 \layout Itemize
3172
3173 aslink -The linker for 8051 type processors.
3174 \layout Itemize
3175
3176 link-z80
3177 \series bold
3178 ,
3179 \series default
3180 link-gbz80 - The Z80 and GameBoy Z80 linkers.
3181 \layout Itemize
3182
3183 s51 - The ucSim 8051 simulator.
3184 \layout Itemize
3185
3186 sdcdb - The source debugger.
3187 \layout Itemize
3188
3189 packihx - A tool to pack (compress) Intel hex files.
3190 \layout Standard
3191
3192 In <installdir>/share/sdcc/include
3193 \layout Itemize
3194
3195 the include files
3196 \layout Standard
3197
3198 In <installdir>/share/sdcc/lib
3199 \layout Itemize
3200
3201 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
3202  relocatables.
3203 \layout Standard
3204
3205 In <installdir>/share/sdcc/doc
3206 \layout Itemize
3207
3208 the documentation
3209 \layout Standard
3210
3211 As development for other processors proceeds, this list will expand to include
3212  executables to support processors like AVR, PIC, etc.
3213 \layout Subsubsection
3214
3215 sdcc - The Compiler
3216 \layout Standard
3217
3218 This is the actual compiler, it in turn uses the c-preprocessor and invokes
3219  the assembler and linkage editor.
3220 \layout Subsubsection
3221
3222 sdcpp - The C-Preprocessor
3223 \layout Standard
3224
3225 The preprocessor is a modified version of the GNU preprocessor.
3226  The C preprocessor is used to pull in #include sources, process #ifdef
3227  statements, #defines and so on.
3228 \layout Subsubsection
3229
3230 asx8051, as-z80, as-gbz80, aslink, link-z80, link-gbz80 - The Assemblers
3231  and Linkage Editors
3232 \layout Standard
3233
3234 This is retargettable assembler & linkage editor, it was developed by Alan
3235  Baldwin.
3236  John Hartman created the version for 8051, and I (Sandeep) have made some
3237  enhancements and bug fixes for it to work properly with the SDCC.
3238 \layout Subsubsection
3239
3240 s51 - The Simulator
3241 \begin_inset LatexCommand \index{s51 - The Simulator}
3242
3243 \end_inset
3244
3245
3246 \layout Standard
3247
3248 S51 is a freeware, opensource simulator developed by Daniel Drotos (
3249 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
3250
3251 \end_inset
3252
3253 ).
3254  The simulator is built as part of the build process.
3255  For more information visit Daniel's website at:
3256 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
3257
3258 \end_inset
3259
3260 .
3261  It currently support the core mcs51, the Dallas DS80C390 and the Philips
3262  XA51 family.
3263 \layout Subsubsection
3264
3265 sdcdb - Source Level Debugger
3266 \layout Standard
3267
3268
3269 \family typewriter
3270 \shape italic
3271 <todo: is this thing still alive?>
3272 \newline
3273
3274 \newline
3275
3276 \family default
3277 \shape default
3278 Sdcdb is the companion source level debugger.
3279  The current version of the debugger uses Daniel's Simulator S51, but can
3280  be easily changed to use other simulators.
3281 \layout Section
3282
3283 Using SDCC
3284 \layout Subsection
3285
3286 Compiling
3287 \layout Subsubsection
3288
3289 Single Source File Projects
3290 \layout Standard
3291
3292 For single source file 8051 projects the process is very simple.
3293  Compile your programs with the following command
3294 \family sans
3295 \series bold
3296 "sdcc sourcefile.c".
3297
3298 \family default
3299 \series default
3300  This will compile, assemble and link your source file.
3301  Output files are as follows
3302 \newline
3303
3304 \newline
3305 sourcefile.asm
3306 \begin_inset LatexCommand \index{.asm}
3307
3308 \end_inset
3309
3310  - Assembler source file created by the compiler
3311 \newline
3312 sourcefile.lst
3313 \begin_inset LatexCommand \index{.lst}
3314
3315 \end_inset
3316
3317  - Assembler listing file created by the Assembler
3318 \newline
3319 sourcefile.rst
3320 \begin_inset LatexCommand \index{.rst}
3321
3322 \end_inset
3323
3324  - Assembler listing file updated with linkedit information, created by
3325  linkage editor
3326 \newline
3327 sourcefile.sym
3328 \begin_inset LatexCommand \index{.sym}
3329
3330 \end_inset
3331
3332  - symbol listing for the sourcefile, created by the assembler
3333 \newline
3334 sourcefile.rel
3335 \begin_inset LatexCommand \index{.rel}
3336
3337 \end_inset
3338
3339  - Object file created by the assembler, input to Linkage editor
3340 \newline
3341 sourcefile.map
3342 \begin_inset LatexCommand \index{.map}
3343
3344 \end_inset
3345
3346  - The memory map for the load module, created by the Linker
3347 \newline
3348 sourcefile.mem
3349 \begin_inset LatexCommand \index{.mem}
3350
3351 \end_inset
3352
3353  - A file with a summary of the memory ussage
3354 \newline
3355 sourcefile.ihx
3356 \begin_inset LatexCommand \index{.ihx}
3357
3358 \end_inset
3359
3360  - The load module in Intel hex format (you can select the Motorola S19
3361  format with ---out-fmt-s19)
3362 \newline
3363 sourcefile.adb
3364 \begin_inset LatexCommand \index{.adb}
3365
3366 \end_inset
3367
3368  - An intermediate file containing debug information needed to create the
3369  .cdb file (with ---debug)
3370 \newline
3371 sourcefile.cdb
3372 \begin_inset LatexCommand \index{.cdb}
3373
3374 \end_inset
3375
3376  - An optional file (with ---debug) containing debug information
3377 \newline
3378 sourcefile.
3379  - (no extension)
3380 \begin_inset LatexCommand \index{. (no extension)}
3381
3382 \end_inset
3383
3384  An optional AOMF51 file containing debug information (with ---debug)
3385 \newline
3386 sourcefile.dump*
3387 \begin_inset LatexCommand \index{.dump*}
3388
3389 \end_inset
3390
3391  - Dump file to debug the compiler it self (with ---dumpall) (see section
3392
3393 \begin_inset Quotes sld
3394 \end_inset
3395
3396 Anatomy of the compiler
3397 \begin_inset Quotes srd
3398 \end_inset
3399
3400 ).
3401 \layout Subsubsection
3402
3403 Projects with Multiple Source Files
3404 \layout Standard
3405
3406 SDCC can compile only ONE file at a time.
3407  Let us for example assume that you have a project containing the following
3408  files:
3409 \newline
3410
3411 \newline
3412 foo1.c (contains some functions)
3413 \newline
3414 foo2.c (contains some more functions)
3415 \newline
3416 foomain.c (contains more functions and the function main)
3417 \newline
3418
3419 \size footnotesize
3420
3421 \newline
3422
3423 \size default
3424 The first two files will need to be compiled separately with the commands:
3425 \size footnotesize
3426
3427 \size default
3428
3429 \newline
3430
3431 \newline
3432
3433 \family sans
3434 \series bold
3435 sdcc\SpecialChar ~
3436 -c\SpecialChar ~
3437 foo1.c
3438 \family default
3439 \series default
3440 \size footnotesize
3441
3442 \newline
3443
3444 \family sans
3445 \series bold
3446 \size default
3447 sdcc\SpecialChar ~
3448 -c\SpecialChar ~
3449 foo2.c
3450 \family default
3451 \series default
3452
3453 \newline
3454
3455 \newline
3456 Then compile the source file containing the
3457 \emph on
3458 main()
3459 \emph default
3460  function and link the files together with the following command:
3461 \newline
3462
3463 \newline
3464
3465 \family sans
3466 \series bold
3467 sdcc\SpecialChar ~
3468 foomain.c\SpecialChar ~
3469 foo1.rel\SpecialChar ~
3470 foo2.rel
3471 \family default
3472 \series default
3473
3474 \newline
3475
3476 \newline
3477 Alternatively,
3478 \emph on
3479 foomain.c
3480 \emph default
3481 can be separately compiled as well:
3482 \family sans
3483 \series bold
3484
3485 \newline
3486
3487 \newline
3488 sdcc\SpecialChar ~
3489 -c\SpecialChar ~
3490 foomain.c
3491 \newline
3492 sdcc foomain.rel foo1.rel foo2.rel
3493 \newline
3494
3495 \newline
3496
3497 \family default
3498 \series default
3499 The file containing the
3500 \emph on
3501 main()
3502 \emph default
3503  function
3504 \emph on
3505
3506 \emph default
3507 \noun on
3508 must
3509 \noun default
3510  be the
3511 \noun on
3512 first
3513 \noun default
3514  file specified in the command line, since the linkage editor processes
3515  file in the order they are presented to it.
3516 \layout Subsubsection
3517
3518 Projects with Additional Libraries
3519 \begin_inset LatexCommand \index{Libraries}
3520
3521 \end_inset
3522
3523
3524 \layout Standard
3525
3526 Some reusable routines may be compiled into a library, see the documentation
3527  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
3528  for how to create a
3529 \emph on
3530 .lib
3531 \begin_inset LatexCommand \index{.lib}
3532
3533 \end_inset
3534
3535
3536 \emph default
3537  library file.
3538  Libraries created in this manner can be included in the command line.
3539  Make sure you include the -L <library-path> option to tell the linker where
3540  to look for these files if they are not in the current directory.
3541  Here is an example, assuming you have the source file
3542 \emph on
3543 foomain.c
3544 \emph default
3545  and a library
3546 \emph on
3547  foolib.lib
3548 \emph default
3549  in the directory
3550 \emph on
3551 mylib
3552 \emph default
3553  (if that is not the same as your current project):
3554 \newline
3555
3556 \newline
3557
3558 \family sans
3559 \series bold
3560 sdcc foomain.c foolib.lib -L mylib
3561 \newline
3562
3563 \newline
3564
3565 \family default
3566 \series default
3567 Note here that
3568 \emph on
3569  mylib
3570 \emph default
3571  must be an absolute path name.
3572 \newline
3573
3574 \newline
3575 The most efficient way to use libraries is to keep seperate modules in seperate
3576  source files.
3577  The lib file now should name all the modules.rel files.
3578  For an example see the standard library file
3579 \emph on
3580 libsdcc.lib
3581 \emph default
3582  in the directory <installdir>/share/lib/small.
3583 \layout Subsection
3584
3585 Command Line Options
3586 \begin_inset LatexCommand \index{Command Line Options}
3587
3588 \end_inset
3589
3590
3591 \layout Subsubsection
3592
3593 Processor Selection Options
3594 \begin_inset LatexCommand \index{Processor Selection Options}
3595
3596 \end_inset
3597
3598
3599 \layout List
3600 \labelwidthstring 00.00.0000
3601
3602
3603 \series bold
3604 -mmcs51
3605 \begin_inset LatexCommand \index{-mmcs51}
3606
3607 \end_inset
3608
3609
3610 \series default
3611  Generate code for the MCS51 (8051) family of processors.
3612  This is the default processor target.
3613 \layout List
3614 \labelwidthstring 00.00.0000
3615
3616
3617 \series bold
3618 -mds390
3619 \begin_inset LatexCommand \index{-mds390}
3620
3621 \end_inset
3622
3623
3624 \series default
3625  Generate code for the DS80C390 processor.
3626 \layout List
3627 \labelwidthstring 00.00.0000
3628
3629
3630 \series bold
3631 -mz80
3632 \begin_inset LatexCommand \index{-mz80}
3633
3634 \end_inset
3635
3636
3637 \series default
3638  Generate code for the Z80 family of processors.
3639 \layout List
3640 \labelwidthstring 00.00.0000
3641
3642
3643 \series bold
3644 -mgbz80
3645 \begin_inset LatexCommand \index{-mgbz80}
3646
3647 \end_inset
3648
3649
3650 \series default
3651  Generate code for the GameBoy Z80 processor.
3652 \layout List
3653 \labelwidthstring 00.00.0000
3654
3655
3656 \series bold
3657 -mavr
3658 \begin_inset LatexCommand \index{-mavr}
3659
3660 \end_inset
3661
3662
3663 \series default
3664  Generate code for the Atmel AVR processor (In development, not complete).
3665 \layout List
3666 \labelwidthstring 00.00.0000
3667
3668
3669 \series bold
3670 -mpic14
3671 \begin_inset LatexCommand \index{-mpic14}
3672
3673 \end_inset
3674
3675
3676 \series default
3677  Generate code for the PIC 14-bit processors (In development, not complete).
3678 \layout List
3679 \labelwidthstring 00.00.0000
3680
3681
3682 \series bold
3683 -mtlcs900h
3684 \series default
3685  Generate code for the Toshiba TLCS-900H processor (In development, not
3686  complete).
3687 \layout List
3688 \labelwidthstring 00.00.0000
3689
3690
3691 \series bold
3692 -mxa51
3693 \begin_inset LatexCommand \index{-mxa51}
3694
3695 \end_inset
3696
3697
3698 \series default
3699  Generate code for the Philips XA51 processor (In development, not complete).
3700 \layout Subsubsection
3701
3702 Preprocessor Options
3703 \begin_inset LatexCommand \index{Options Preprocessor}
3704
3705 \end_inset
3706
3707
3708 \begin_inset LatexCommand \index{Preprocessor Options}
3709
3710 \end_inset
3711
3712
3713 \layout List
3714 \labelwidthstring 00.00.0000
3715
3716
3717 \series bold
3718 -I<path>
3719 \begin_inset LatexCommand \index{-I<path>}
3720
3721 \end_inset
3722
3723
3724 \series default
3725  The additional location where the pre processor will look for <..h> or
3726 \begin_inset Quotes eld
3727 \end_inset
3728
3729 ..h
3730 \begin_inset Quotes erd
3731 \end_inset
3732
3733  files.
3734 \layout List
3735 \labelwidthstring 00.00.0000
3736
3737
3738 \series bold
3739 -D<macro[=value]>
3740 \begin_inset LatexCommand \index{-D<macro[=value]>}
3741
3742 \end_inset
3743
3744
3745 \series default
3746  Command line definition of macros.
3747  Passed to the pre processor.
3748 \layout List
3749 \labelwidthstring 00.00.0000
3750
3751
3752 \series bold
3753 -M
3754 \begin_inset LatexCommand \index{-M}
3755
3756 \end_inset
3757
3758
3759 \series default
3760  Tell the preprocessor to output a rule suitable for make describing the
3761  dependencies of each object file.
3762  For each source file, the preprocessor outputs one make-rule whose target
3763  is the object file name for that source file and whose dependencies are
3764  all the files `#include'd in it.
3765  This rule may be a single line or may be continued with `
3766 \backslash
3767 '-newline if it is long.
3768  The list of rules is printed on standard output instead of the preprocessed
3769  C program.
3770  `-M' implies `-E'.
3771 \layout List
3772 \labelwidthstring 00.00.0000
3773
3774
3775 \series bold
3776 -C
3777 \begin_inset LatexCommand \index{-C}
3778
3779 \end_inset
3780
3781
3782 \series default
3783  Tell the preprocessor not to discard comments.
3784  Used with the `-E' option.
3785 \layout List
3786 \labelwidthstring 00.00.0000
3787
3788
3789 \series bold
3790 -MM
3791 \begin_inset LatexCommand \index{-MM}
3792
3793 \end_inset
3794
3795
3796 \size large
3797 \bar under
3798
3799 \series default
3800 \size default
3801 \bar default
3802 Like `-M' but the output mentions only the user header files included with
3803  `#include
3804 \begin_inset Quotes eld
3805 \end_inset
3806
3807 file"'.
3808  System header files included with `#include <file>' are omitted.
3809 \layout List
3810 \labelwidthstring 00.00.0000
3811
3812
3813 \series bold
3814 -Aquestion(answer)
3815 \begin_inset LatexCommand \index{-Aquestion(answer)}
3816
3817 \end_inset
3818
3819
3820 \series default
3821  Assert the answer answer for question, in case it is tested with a preprocessor
3822  conditional such as `#if #question(answer)'.
3823  `-A-' disables the standard assertions that normally describe the target
3824  machine.
3825 \layout List
3826 \labelwidthstring 00.00.0000
3827
3828
3829 \series bold
3830 -Aquestion
3831 \series default
3832  (answer) Assert the answer answer for question, in case it is tested with
3833  a preprocessor conditional such as `#if #question(answer)'.
3834  `-A-' disables the standard assertions that normally describe the target
3835  machine.
3836 \layout List
3837 \labelwidthstring 00.00.0000
3838
3839
3840 \series bold
3841 -Umacro
3842 \begin_inset LatexCommand \index{-Umacro}
3843
3844 \end_inset
3845
3846
3847 \series default
3848  Undefine macro macro.
3849  `-U' options are evaluated after all `-D' options, but before any `-include'
3850  and `-imacros' options.
3851 \layout List
3852 \labelwidthstring 00.00.0000
3853
3854
3855 \series bold
3856 -dM
3857 \begin_inset LatexCommand \index{-dM}
3858
3859 \end_inset
3860
3861
3862 \series default
3863  Tell the preprocessor to output only a list of the macro definitions that
3864  are in effect at the end of preprocessing.
3865  Used with the `-E' option.
3866 \layout List
3867 \labelwidthstring 00.00.0000
3868
3869
3870 \series bold
3871 -dD
3872 \begin_inset LatexCommand \index{-dD}
3873
3874 \end_inset
3875
3876
3877 \series default
3878  Tell the preprocessor to pass all macro definitions into the output, in
3879  their proper sequence in the rest of the output.
3880 \layout List
3881 \labelwidthstring 00.00.0000
3882
3883
3884 \series bold
3885 -dN
3886 \begin_inset LatexCommand \index{-dN}
3887
3888 \end_inset
3889
3890
3891 \size large
3892 \bar under
3893
3894 \series default
3895 \size default
3896 \bar default
3897 Like `-dD' except that the macro arguments and contents are omitted.
3898  Only `#define name' is included in the output.
3899 \layout Subsubsection
3900
3901 Linker Options
3902 \begin_inset LatexCommand \index{Options Linker}
3903
3904 \end_inset
3905
3906
3907 \begin_inset LatexCommand \index{Linker Options}
3908
3909 \end_inset
3910
3911
3912 \layout List
3913 \labelwidthstring 00.00.0000
3914
3915
3916 \series bold
3917 -L\SpecialChar ~
3918 ---lib-path
3919 \begin_inset LatexCommand \index{-L ---lib-path}
3920
3921 \end_inset
3922
3923
3924 \bar under
3925
3926 \series default
3927 \bar default
3928 <absolute path to additional libraries> This option is passed to the linkage
3929  editor's additional libraries search path.
3930  The path name must be absolute.
3931  Additional library files may be specified in the command line.
3932  See section Compiling programs for more details.
3933 \layout List
3934 \labelwidthstring 00.00.0000
3935
3936
3937 \series bold
3938 ---xram-loc
3939 \series default
3940
3941 \begin_inset LatexCommand \index{---xram-loc}
3942
3943 \end_inset
3944
3945 <Value> The start location of the external ram, default value is 0.
3946  The value entered can be in Hexadecimal or Decimal format, e.g.: ---xram-loc
3947  0x8000 or ---xram-loc 32768.
3948 \layout List
3949 \labelwidthstring 00.00.0000
3950
3951
3952 \series bold
3953 ---code-loc
3954 \series default
3955
3956 \begin_inset LatexCommand \index{---code-loc}
3957
3958 \end_inset
3959
3960 <Value> The start location of the code segment, default value 0.
3961  Note when this option is used the interrupt vector table is also relocated
3962  to the given address.
3963  The value entered can be in Hexadecimal or Decimal format, e.g.: ---code-loc
3964  0x8000 or ---code-loc 32768.
3965 \layout List
3966 \labelwidthstring 00.00.0000
3967
3968
3969 \series bold
3970 ---stack-loc
3971 \series default
3972
3973 \begin_inset LatexCommand \index{---stack-loc}
3974
3975 \end_inset
3976
3977 <Value> By default the stack is placed after the data segment.
3978  Using this option the stack can be placed anywhere in the internal memory
3979  space of the 8051.
3980  The value entered can be in Hexadecimal or Decimal format, e.g.
3981  ---stack-loc 0x20 or ---stack-loc 32.
3982  Since the sp register is incremented before a push or call, the initial
3983  sp will be set to one byte prior the provided value.
3984  The provided value should not overlap any other memory areas such as used
3985  register banks or the data segment and with enough space for the current
3986  application.
3987 \layout List
3988 \labelwidthstring 00.00.0000
3989
3990
3991 \series bold
3992 ---data-loc
3993 \series default
3994
3995 \begin_inset LatexCommand \index{---data-loc}
3996
3997 \end_inset
3998
3999 <Value> The start location of the internal ram data segment.
4000  The value entered can be in Hexadecimal or Decimal format, eg.
4001  ---data-loc 0x20 or ---data-loc 32.
4002  (By default, the start location of the internal ram data segment  is set
4003  as low as possible in memory, taking into account the used register banks
4004  and the bit segment at address 0x20.
4005  For example if register banks 0 and 1 are used without bit variables, the
4006  data segment will be set, if ---data-loc is not used, to location 0x10.)
4007 \layout List
4008 \labelwidthstring 00.00.0000
4009
4010
4011 \series bold
4012 ---idata-loc
4013 \series default
4014
4015 \begin_inset LatexCommand \index{---idata-loc}
4016
4017 \end_inset
4018
4019 <Value> The start location of the indirectly addressable internal ram, default
4020  value is 0x80.
4021  The value entered can be in Hexadecimal or Decimal format, eg.
4022  ---idata-loc 0x88 or ---idata-loc 136.
4023 \layout List
4024 \labelwidthstring 00.00.0000
4025
4026
4027 \series bold
4028 ---out-fmt-ihx
4029 \begin_inset LatexCommand \index{---out-fmt-ihx}
4030
4031 \end_inset
4032
4033
4034 \bar under
4035
4036 \series default
4037 \bar default
4038 The linker output (final object code) is in Intel Hex format.
4039  (This is the default option).
4040 \layout List
4041 \labelwidthstring 00.00.0000
4042
4043
4044 \series bold
4045 ---out-fmt-s19
4046 \begin_inset LatexCommand \index{---out-fmt-s19}
4047
4048 \end_inset
4049
4050
4051 \bar under
4052
4053 \series default
4054 \bar default
4055 The linker output (final object code) is in Motorola S19 format.
4056 \layout Subsubsection
4057
4058 MCS51 Options
4059 \begin_inset LatexCommand \index{Options MCS51}
4060
4061 \end_inset
4062
4063
4064 \begin_inset LatexCommand \index{MCS51 Options}
4065
4066 \end_inset
4067
4068
4069 \layout List
4070 \labelwidthstring 00.00.0000
4071
4072
4073 \series bold
4074 ---model-large
4075 \begin_inset LatexCommand \index{---model-large}
4076
4077 \end_inset
4078
4079
4080 \series default
4081  Generate code for Large model programs see section Memory Models for more
4082  details.
4083  If this option is used all source files in the project should be compiled
4084  with this option.
4085  In addition the standard library routines are compiled with small model,
4086  they will need to be recompiled.
4087 \layout List
4088 \labelwidthstring 00.00.0000
4089
4090
4091 \series bold
4092 ---model-small
4093 \begin_inset LatexCommand \index{---model-small}
4094
4095 \end_inset
4096
4097
4098 \series default
4099 \size large
4100 \emph on
4101
4102 \size default
4103 \emph default
4104 Generate code for Small Model programs see section Memory Models for more
4105  details.
4106  This is the default model.
4107 \layout Subsubsection
4108
4109 DS390 Options
4110 \begin_inset LatexCommand \index{Options DS390}
4111
4112 \end_inset
4113
4114
4115 \begin_inset LatexCommand \index{DS390 Options}
4116
4117 \end_inset
4118
4119
4120 \layout List
4121 \labelwidthstring 00.00.0000
4122
4123
4124 \series bold
4125 ---model-flat24
4126 \series default
4127
4128 \begin_inset LatexCommand \index{---model-flat24}
4129
4130 \end_inset
4131
4132
4133 \size large
4134 \emph on
4135
4136 \size default
4137 \emph default
4138 Generate 24-bit flat mode code.
4139  This is the one and only that the ds390 code generator supports right now
4140  and is default when using
4141 \emph on
4142 -mds390
4143 \emph default
4144 .
4145  See section Memory Models for more details.
4146 \layout List
4147 \labelwidthstring 00.00.0000
4148
4149
4150 \series bold
4151 ---stack-10bit
4152 \series default
4153
4154 \begin_inset LatexCommand \index{--stack-10bit}
4155
4156 \end_inset
4157
4158  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
4159  This is the one and only that the ds390 code generator supports right now
4160  and is default when using
4161 \emph on
4162 -mds390
4163 \emph default
4164 .
4165  In this mode, the stack is located in the lower 1K of the internal RAM,
4166  which is mapped to 0x400000.
4167  Note that the support is incomplete, since it still uses a single byte
4168  as the stack pointer.
4169  This means that only the lower 256 bytes of the potential 1K stack space
4170  will actually be used.
4171  However, this does allow you to reclaim the precious 256 bytes of low RAM
4172  for use for the DATA and IDATA segments.
4173  The compiler will not generate any code to put the processor into 10 bit
4174  stack mode.
4175  It is important to ensure that the processor is in this mode before calling
4176  any re-entrant functions compiled with this option.
4177  In principle, this should work with the
4178 \emph on
4179 ---stack-auto
4180 \emph default
4181  option, but that has not been tested.
4182  It is incompatible with the
4183 \emph on
4184 ---xstack
4185 \emph default
4186  option.
4187  It also only makes sense if the processor is in 24 bit contiguous addressing
4188  mode (see the
4189 \emph on
4190 ---model-flat24 option
4191 \emph default
4192 ).
4193 \layout Subsubsection
4194
4195 Optimization Options
4196 \begin_inset LatexCommand \index{Options Optimization}
4197
4198 \end_inset
4199
4200
4201 \begin_inset LatexCommand \index{Optimization Options}
4202
4203 \end_inset
4204
4205
4206 \layout List
4207 \labelwidthstring 00.00.0000
4208
4209
4210 \series bold
4211 ---nogcse
4212 \begin_inset LatexCommand \index{---nogcse}
4213
4214 \end_inset
4215
4216
4217 \series default
4218  Will not do global subexpression elimination, this option may be used when
4219  the compiler creates undesirably large stack/data spaces to store compiler
4220  temporaries.
4221  A warning message will be generated when this happens and the compiler
4222  will indicate the number of extra bytes it allocated.
4223  It recommended that this option NOT be used, #pragma\SpecialChar ~
4224 NOGCSE can be used
4225  to turn off global subexpression elimination for a given function only.
4226 \layout List
4227 \labelwidthstring 00.00.0000
4228
4229
4230 \series bold
4231 ---noinvariant
4232 \begin_inset LatexCommand \index{---noinvariant}
4233
4234 \end_inset
4235
4236
4237 \series default
4238  Will not do loop invariant optimizations, this may be turned off for reasons
4239  explained for the previous option.
4240  For more details of loop optimizations performed see section Loop Invariants.It
4241  recommended that this option NOT be used, #pragma\SpecialChar ~
4242 NOINVARIANT can be used
4243  to turn off invariant optimizations for a given function only.
4244 \layout List
4245 \labelwidthstring 00.00.0000
4246
4247
4248 \series bold
4249 ---noinduction
4250 \begin_inset LatexCommand \index{---noinduction}
4251
4252 \end_inset
4253
4254
4255 \series default
4256  Will not do loop induction optimizations, see section strength reduction
4257  for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
4258 NOINDUCT
4259 ION can be used to turn off induction optimizations for a given function
4260  only.
4261 \layout List
4262 \labelwidthstring 00.00.0000
4263
4264
4265 \series bold
4266 ---nojtbound
4267 \begin_inset LatexCommand \index{---nojtbound}
4268
4269 \end_inset
4270
4271
4272 \size large
4273 \bar under
4274
4275 \series default
4276 \size default
4277 \bar default
4278  Will not generate boundary condition check when switch statements are implement
4279 ed using jump-tables.
4280  See section Switch Statements for more details.
4281  It is recommended that this option is NOT used, #pragma\SpecialChar ~
4282 NOJTBOUND can be
4283  used to turn off boundary checking for jump tables for a given function
4284  only.
4285 \layout List
4286 \labelwidthstring 00.00.0000
4287
4288
4289 \series bold
4290 ---noloopreverse
4291 \begin_inset LatexCommand \index{---noloopreverse}
4292
4293 \end_inset
4294
4295
4296 \series default
4297 \size large
4298
4299 \size default
4300 Will not do loop reversal optimization.
4301 \layout List
4302 \labelwidthstring 00.00.0000
4303
4304 ---
4305 \series bold
4306 nolabelopt
4307 \series default
4308
4309 \begin_inset LatexCommand \index{---nolabelopt }
4310
4311 \end_inset
4312
4313 Will not optimize labels (makes the dumpfiles more readable).
4314 \layout List
4315 \labelwidthstring 00.00.0000
4316
4317
4318 \series bold
4319 ---no-xinit-opt
4320 \begin_inset LatexCommand \index{---no-xinit-opt}
4321
4322 \end_inset
4323
4324
4325 \series default
4326  Will not memcpy initialized data in far space from code space.
4327  This saves a few bytes in code space if you don't have initialized data.
4328 \layout Subsubsection
4329
4330 Other Options
4331 \begin_inset LatexCommand \index{Options other}
4332
4333 \end_inset
4334
4335
4336 \begin_inset LatexCommand \index{Other Options}
4337
4338 \end_inset
4339
4340
4341 \layout List
4342 \labelwidthstring 00.00.0000
4343
4344
4345 \series bold
4346 -c\SpecialChar ~
4347 ---compile-only
4348 \begin_inset LatexCommand \index{---compile-only}
4349
4350 \end_inset
4351
4352
4353 \begin_inset LatexCommand \index{-c ---compile-only}
4354
4355 \end_inset
4356
4357
4358 \series default
4359  will compile and assemble the source, but will not call the linkage editor.
4360 \layout List
4361 \labelwidthstring 00.00.0000
4362
4363
4364 \series bold
4365 --c1mode
4366 \begin_inset LatexCommand \index{--c1mode}
4367
4368 \end_inset
4369
4370
4371 \series default
4372  reads the preprocessed source from standard input and compiles it.
4373  The file name for the assembler output must be specified using the -o option.
4374 \layout List
4375 \labelwidthstring 00.00.0000
4376
4377
4378 \series bold
4379 -E
4380 \begin_inset LatexCommand \index{-E}
4381
4382 \end_inset
4383
4384
4385 \series default
4386  Run only the C preprocessor.
4387  Preprocess all the C source files specified and output the results to standard
4388  output.
4389 \layout List
4390 \labelwidthstring 00.00.0000
4391
4392
4393 \series bold
4394 -o\SpecialChar ~
4395 <path/file>
4396 \begin_inset LatexCommand \index{-o <path/file>}
4397
4398 \end_inset
4399
4400
4401 \series default
4402 The output path resp.
4403  file where everything will be placed.
4404  If the parameter is a path, it must have a trailing slash (or backslash
4405  for the Windows binaries) to be recognized as a path.
4406
4407 \layout List
4408 \labelwidthstring 00.00.0000
4409
4410
4411 \series bold
4412 ---stack-auto
4413 \begin_inset LatexCommand \index{---stack-auto}
4414
4415 \end_inset
4416
4417
4418 \series default
4419 \size large
4420 \emph on
4421
4422 \size default
4423 \emph default
4424 All functions in the source file will be compiled as
4425 \emph on
4426 reentrant
4427 \emph default
4428 , i.e.
4429  the parameters and local variables will be allocated on the stack.
4430  see section Parameters and Local Variables for more details.
4431  If this option is used all source files in the project should be compiled
4432  with this option.
4433
4434 \layout List
4435 \labelwidthstring 00.00.0000
4436
4437
4438 \series bold
4439 ---xstack
4440 \begin_inset LatexCommand \index{---xstack}
4441
4442 \end_inset
4443
4444
4445 \series default
4446  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
4447  variables and passing parameters.
4448  See section on external stack for more details.
4449 \layout List
4450 \labelwidthstring 00.00.0000
4451
4452
4453 \series bold
4454 ---callee-saves
4455 \begin_inset LatexCommand \index{---callee-saves}
4456
4457 \end_inset
4458
4459  function1[,function2][,function3]....
4460
4461 \series default
4462  The compiler by default uses a caller saves convention for register saving
4463  across function calls, however this can cause unneccessary register pushing
4464  & popping when calling small functions from larger functions.
4465  This option can be used to switch the register saving convention for the
4466  function names specified.
4467  The compiler will not save registers when calling these functions, no extra
4468  code will be generated at the entry & exit for these functions to save
4469  & restore the registers used by these functions, this can SUBSTANTIALLY
4470  reduce code & improve run time performance of the generated code.
4471  In the future the compiler (with interprocedural analysis) will be able
4472  to determine the appropriate scheme to use for each function call.
4473  DO NOT use this option for built-in functions such as _muluint..., if this
4474  option is used for a library function the appropriate library function
4475  needs to be recompiled with the same option.
4476  If the project consists of multiple source files then all the source file
4477  should be compiled with the same ---callee-saves option string.
4478  Also see #pragma\SpecialChar ~
4479 CALLEE-SAVES
4480 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
4481
4482 \end_inset
4483
4484 .
4485 \layout List
4486 \labelwidthstring 00.00.0000
4487
4488
4489 \series bold
4490 ---debug
4491 \begin_inset LatexCommand \index{---debug}
4492
4493 \end_inset
4494
4495
4496 \bar under
4497
4498 \series default
4499 \bar default
4500 When this option is used the compiler will generate debug information, that
4501  can be used with the SDCDB.
4502  The debug information is collected in a file with .cdb extension.
4503  For more information see documentation for SDCDB.
4504 \layout List
4505 \labelwidthstring 00.00.0000
4506
4507
4508 \series bold
4509 ---peep-file
4510 \series default
4511
4512 \begin_inset LatexCommand \index{---peep-file}
4513
4514 \end_inset
4515
4516 <filename> This option can be used to use additional rules to be used by
4517  the peep hole optimizer.
4518  See section Peep Hole optimizations for details on how to write these rules.
4519 \layout List
4520 \labelwidthstring 00.00.0000
4521
4522
4523 \series bold
4524 -S
4525 \begin_inset LatexCommand \index{-S}
4526
4527 \end_inset
4528
4529
4530 \size large
4531 \bar under
4532
4533 \series default
4534 \size default
4535 \bar default
4536 Stop after the stage of compilation proper; do not assemble.
4537  The output is an assembler code file for the input file specified.
4538 \layout List
4539 \labelwidthstring 00.00.0000
4540
4541
4542 \series bold
4543 -Wa_asmOption[,asmOption]
4544 \series default
4545
4546 \begin_inset LatexCommand \index{-Wa\_asmOption[,asmOption]}
4547
4548 \end_inset
4549
4550 ...
4551  Pass the asmOption to the assembler.
4552 \layout List
4553 \labelwidthstring 00.00.0000
4554
4555
4556 \series bold
4557 -Wl_linkOption[,linkOption]
4558 \series default
4559
4560 \begin_inset LatexCommand \index{-Wl\_linkOption[,linkOption]}
4561
4562 \end_inset
4563
4564 ...
4565  Pass the linkOption to the linker.
4566 \layout List
4567 \labelwidthstring 00.00.0000
4568
4569
4570 \series bold
4571 ---int-long-reent
4572 \begin_inset LatexCommand \index{---int-long-reent}
4573
4574 \end_inset
4575
4576
4577 \series default
4578  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
4579  Note by default these libraries are compiled as non-reentrant.
4580  See section Installation for more details.
4581 \layout List
4582 \labelwidthstring 00.00.0000
4583
4584
4585 \series bold
4586 ---cyclomatic
4587 \begin_inset LatexCommand \index{---cyclomatic}
4588
4589 \end_inset
4590
4591
4592 \bar under
4593
4594 \series default
4595 \bar default
4596 This option will cause the compiler to generate an information message for
4597  each function in the source file.
4598  The message contains some
4599 \emph on
4600 important
4601 \emph default
4602  information about the function.
4603  The number of edges and nodes the compiler detected in the control flow
4604  graph of the function, and most importantly the
4605 \emph on
4606 cyclomatic complexity
4607 \begin_inset LatexCommand \index{cyclomatic complexity}
4608
4609 \end_inset
4610
4611
4612 \emph default
4613  see section on Cyclomatic Complexity for more details.
4614 \layout List
4615 \labelwidthstring 00.00.0000
4616
4617
4618 \series bold
4619 ---float-reent
4620 \begin_inset LatexCommand \index{---float-reent}
4621
4622 \end_inset
4623
4624
4625 \bar under
4626
4627 \series default
4628 \bar default
4629  Floating point library is compiled as reentrant
4630 \begin_inset LatexCommand \index{ reentrant}
4631
4632 \end_inset
4633
4634 .See section Installation for more details.
4635 \layout List
4636 \labelwidthstring 00.00.0000
4637
4638
4639 \series bold
4640 ---nooverlay
4641 \begin_inset LatexCommand \index{---nooverlay}
4642
4643 \end_inset
4644
4645
4646 \series default
4647   The compiler will not overlay parameters and local variables of any function,
4648  see section Parameters and local variables for more details.
4649 \layout List
4650 \labelwidthstring 00.00.0000
4651
4652
4653 \series bold
4654 ---main-return
4655 \begin_inset LatexCommand \index{---main-return}
4656
4657 \end_inset
4658
4659
4660 \series default
4661  This option can be used when the code generated is called by a monitor
4662  program.
4663  The compiler will generate a 'ret' upon return from the 'main'
4664 \begin_inset LatexCommand \index{main return}
4665
4666 \end_inset
4667
4668  function.
4669  The default option is to lock up i.e.
4670  generate a 'ljmp '.
4671 \layout List
4672 \labelwidthstring 00.00.0000
4673
4674
4675 \series bold
4676 ---no-peep
4677 \begin_inset LatexCommand \index{---no-peep}
4678
4679 \end_inset
4680
4681
4682 \series default
4683   Disable peep-hole optimization.
4684 \layout List
4685 \labelwidthstring 00.00.0000
4686
4687
4688 \series bold
4689 ---peep-asm
4690 \begin_inset LatexCommand \index{---peep-asm}
4691
4692 \end_inset
4693
4694
4695 \series default
4696   Pass the inline assembler code through the peep hole optimizer.
4697  This can cause unexpected changes to inline assembler code, please go through
4698  the peephole optimizer
4699 \begin_inset LatexCommand \index{Peephole optimizer}
4700
4701 \end_inset
4702
4703  rules defined in the source file tree '<target>/peeph.def' before using
4704  this option.
4705 \layout List
4706 \labelwidthstring 00.00.0000
4707
4708
4709 \series bold
4710 ---iram-size
4711 \series default
4712 <Value>
4713 \begin_inset LatexCommand \index{---iram-size<Value>}
4714
4715 \end_inset
4716
4717  Causes the linker to check if the internal ram usage is within limits of
4718  the given value.
4719 \layout List
4720 \labelwidthstring 00.00.0000
4721
4722
4723 \series bold
4724 ---xram-size
4725 \series default
4726 <Value>
4727 \begin_inset LatexCommand \index{---xram-size<Value>}
4728
4729 \end_inset
4730
4731  Causes the linker to check if the external ram usage is within limits of
4732  the given value.
4733 \layout List
4734 \labelwidthstring 00.00.0000
4735
4736
4737 \series bold
4738 ---code-size
4739 \series default
4740 <Value>
4741 \begin_inset LatexCommand \index{---code-size<Value>}
4742
4743 \end_inset
4744
4745  Causes the linker to check if the code usage is within limits of the given
4746  value.
4747 \layout List
4748 \labelwidthstring 00.00.0000
4749
4750
4751 \series bold
4752 ---nostdincl
4753 \begin_inset LatexCommand \index{---nostdincl}
4754
4755 \end_inset
4756
4757
4758 \series default
4759  This will prevent the compiler from passing on the default include path
4760  to the preprocessor.
4761 \layout List
4762 \labelwidthstring 00.00.0000
4763
4764
4765 \series bold
4766 ---nostdlib
4767 \begin_inset LatexCommand \index{---nostdlib}
4768
4769 \end_inset
4770
4771
4772 \series default
4773  This will prevent the compiler from passing on the default library path
4774  to the linker.
4775 \layout List
4776 \labelwidthstring 00.00.0000
4777
4778
4779 \series bold
4780 ---verbose
4781 \begin_inset LatexCommand \index{---verbose}
4782
4783 \end_inset
4784
4785
4786 \series default
4787  Shows the various actions the compiler is performing.
4788 \layout List
4789 \labelwidthstring 00.00.0000
4790
4791
4792 \series bold
4793 -V
4794 \begin_inset LatexCommand \index{-V}
4795
4796 \end_inset
4797
4798
4799 \series default
4800  Shows the actual commands the compiler is executing.
4801 \layout List
4802 \labelwidthstring 00.00.0000
4803
4804
4805 \series bold
4806 ---no-c-code-in-asm
4807 \begin_inset LatexCommand \index{---no-c-code-in-asm}
4808
4809 \end_inset
4810
4811
4812 \series default
4813  Hides your ugly and inefficient c-code from the asm file, so you can always
4814  blame the compiler :).
4815 \layout List
4816 \labelwidthstring 00.00.0000
4817
4818
4819 \series bold
4820 ---i-code-in-asm
4821 \begin_inset LatexCommand \index{---i-code-in-asm}
4822
4823 \end_inset
4824
4825
4826 \series default
4827  Include i-codes in the asm file.
4828  Sounds like noise but is most helpfull for debugging the compiler itself.
4829 \layout List
4830 \labelwidthstring 00.00.0000
4831
4832
4833 \series bold
4834 ---less-pedantic
4835 \begin_inset LatexCommand \index{---less-pedantic}
4836
4837 \end_inset
4838
4839
4840 \series default
4841  Disable some of the more pedantic warnings (jwk burps: please be more specific
4842  here, please!)
4843 \layout List
4844 \labelwidthstring 00.00.0000
4845
4846
4847 \series bold
4848 ---print-search-dirs
4849 \begin_inset LatexCommand \index{---print-search-dirs}
4850
4851 \end_inset
4852
4853
4854 \series default
4855  Display the directories in the compiler's search path
4856 \layout Subsubsection
4857
4858 Intermediate Dump Options
4859 \begin_inset LatexCommand \index{Options Intermediate Dump}
4860
4861 \end_inset
4862
4863
4864 \begin_inset LatexCommand \index{Intermediate Dump Options}
4865
4866 \end_inset
4867
4868
4869 \layout Standard
4870
4871 The following options are provided for the purpose of retargetting and debugging
4872  the compiler.
4873  These provided a means to dump the intermediate code (iCode
4874 \begin_inset LatexCommand \index{iCode}
4875
4876 \end_inset
4877
4878 ) generated by the compiler in human readable form at various stages of
4879  the compilation process.
4880
4881 \layout List
4882 \labelwidthstring 00.00.0000
4883
4884
4885 \series bold
4886 ---dumpraw
4887 \begin_inset LatexCommand \index{---dumpraw}
4888
4889 \end_inset
4890
4891
4892 \series default
4893  This option will cause the compiler to dump the intermediate code into
4894  a file of named
4895 \emph on
4896 <source filename>.dumpraw
4897 \emph default
4898  just after the intermediate code has been generated for a function, i.e.
4899  before any optimizations are done.
4900  The basic blocks
4901 \begin_inset LatexCommand \index{basic blocks}
4902
4903 \end_inset
4904
4905  at this stage ordered in the depth first number, so they may not be in
4906  sequence of execution.
4907 \layout List
4908 \labelwidthstring 00.00.0000
4909
4910
4911 \series bold
4912 ---dumpgcse
4913 \begin_inset LatexCommand \index{---dumpgcse}
4914
4915 \end_inset
4916
4917
4918 \series default
4919  Will create a dump of iCode's, after global subexpression elimination
4920 \begin_inset LatexCommand \index{global subexpression elimination}
4921
4922 \end_inset
4923
4924 , into a file named
4925 \emph on
4926 <source filename>.dumpgcse.
4927 \layout List
4928 \labelwidthstring 00.00.0000
4929
4930
4931 \series bold
4932 ---dumpdeadcode
4933 \begin_inset LatexCommand \index{---dumpdeadcode}
4934
4935 \end_inset
4936
4937
4938 \series default
4939  Will create a dump of iCode's, after deadcode elimination
4940 \begin_inset LatexCommand \index{deadcode elimination}
4941
4942 \end_inset
4943
4944 , into a file named
4945 \emph on
4946 <source filename>.dumpdeadcode.
4947 \layout List
4948 \labelwidthstring 00.00.0000
4949
4950
4951 \series bold
4952 ---dumploop
4953 \begin_inset LatexCommand \index{---dumploop}
4954
4955 \end_inset
4956
4957
4958 \series default
4959 \size large
4960
4961 \size default
4962 Will create a dump of iCode's, after loop optimizations
4963 \begin_inset LatexCommand \index{loop optimizations}
4964
4965 \end_inset
4966
4967 , into a file named
4968 \emph on
4969 <source filename>.dumploop.
4970 \layout List
4971 \labelwidthstring 00.00.0000
4972
4973
4974 \series bold
4975 ---dumprange
4976 \begin_inset LatexCommand \index{---dumprange}
4977
4978 \end_inset
4979
4980
4981 \series default
4982 \size large
4983
4984 \size default
4985 Will create a dump of iCode's, after live range analysis
4986 \begin_inset LatexCommand \index{live range analysis}
4987
4988 \end_inset
4989
4990 , into a file named
4991 \emph on
4992 <source filename>.dumprange.
4993 \layout List
4994 \labelwidthstring 00.00.0000
4995
4996
4997 \series bold
4998 ---dumlrange
4999 \begin_inset LatexCommand \index{---dumlrange}
5000
5001 \end_inset
5002
5003
5004 \series default
5005  Will dump the life ranges
5006 \begin_inset LatexCommand \index{life ranges}
5007
5008 \end_inset
5009
5010  for all symbols.
5011 \layout List
5012 \labelwidthstring 00.00.0000
5013
5014
5015 \series bold
5016 ---dumpregassign
5017 \begin_inset LatexCommand \index{---dumpregassign}
5018
5019 \end_inset
5020
5021
5022 \bar under
5023
5024 \series default
5025 \bar default
5026 Will create a dump of iCode's, after register assignment
5027 \begin_inset LatexCommand \index{register assignment}
5028
5029 \end_inset
5030
5031 , into a file named
5032 \emph on
5033 <source filename>.dumprassgn.
5034 \layout List
5035 \labelwidthstring 00.00.0000
5036
5037
5038 \series bold
5039 ---dumplrange
5040 \begin_inset LatexCommand \index{---dumplrange}
5041
5042 \end_inset
5043
5044
5045 \series default
5046  Will create a dump of the live ranges of iTemp's
5047 \layout List
5048 \labelwidthstring 00.00.0000
5049
5050
5051 \series bold
5052 ---dumpall
5053 \begin_inset LatexCommand \index{---dumpall}
5054
5055 \end_inset
5056
5057
5058 \size large
5059 \bar under
5060
5061 \series default
5062 \size default
5063 \bar default
5064 Will cause all the above mentioned dumps to be created.
5065 \layout Subsection
5066
5067 Environment variables
5068 \begin_inset LatexCommand \index{Environment variables}
5069
5070 \end_inset
5071
5072
5073 \layout Standard
5074
5075 SDCC recognizes the following environment variables:
5076 \layout List
5077 \labelwidthstring 00.00.0000
5078
5079
5080 \series bold
5081 SDCC_LEAVE_SIGNALS
5082 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
5083
5084 \end_inset
5085
5086
5087 \series default
5088  SDCC installs a signal handler
5089 \begin_inset LatexCommand \index{ signal handler}
5090
5091 \end_inset
5092
5093  to be able to delete temporary files after an user break (^C) or an exception.
5094  If this environment variable is set, SDCC won't install the signal handler
5095  in order to be able to debug SDCC.
5096 \layout List
5097 \labelwidthstring 00.00.0000
5098
5099
5100 \series bold
5101 TMP
5102 \begin_inset LatexCommand \index{TMP}
5103
5104 \end_inset
5105
5106 ,\SpecialChar ~
5107 TEMP
5108 \begin_inset LatexCommand \index{TEMP}
5109
5110 \end_inset
5111
5112 ,\SpecialChar ~
5113 TMPDIR
5114 \begin_inset LatexCommand \index{TMPDIR}
5115
5116 \end_inset
5117
5118
5119 \series default
5120  Path, where temporary files will be created.
5121  The order of the variables is the search order.
5122  In a standard *nix environment these variables are not set, and there's
5123  no need to set them.
5124  On Windows it's recommended to set one of them.
5125 \layout List
5126 \labelwidthstring 00.00.0000
5127
5128
5129 \series bold
5130 SDCC_HOME
5131 \begin_inset LatexCommand \index{SDCC\_HOME}
5132
5133 \end_inset
5134
5135
5136 \series default
5137  Path, see
5138 \begin_inset Quotes sld
5139 \end_inset
5140
5141 2.3 Install and search paths
5142 \begin_inset Quotes srd
5143 \end_inset
5144
5145 .
5146 \layout List
5147 \labelwidthstring 00.00.0000
5148
5149
5150 \series bold
5151 SDCC_INCLUDE
5152 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
5153
5154 \end_inset
5155
5156
5157 \series default
5158  Path, see
5159 \begin_inset Quotes sld
5160 \end_inset
5161
5162 2.3 Install and search paths
5163 \begin_inset Quotes srd
5164 \end_inset
5165
5166 .
5167 \layout List
5168 \labelwidthstring 00.00.0000
5169
5170
5171 \series bold
5172 SDCC_LIB
5173 \begin_inset LatexCommand \index{SDCC\_LIB}
5174
5175 \end_inset
5176
5177
5178 \series default
5179  Path, see
5180 \begin_inset Quotes sld
5181 \end_inset
5182
5183 2.3 Install and search paths
5184 \begin_inset Quotes srd
5185 \end_inset
5186
5187 .
5188 \layout Standard
5189
5190 There are some more environment variables recognized by SDCC, but these
5191  are solely used for debugging purposes.
5192  They can change or disappear very quickly, and will never be documentated.
5193 \layout Subsection
5194
5195 MCS51/DS390 Storage Class
5196 \begin_inset LatexCommand \index{Storage Class}
5197
5198 \end_inset
5199
5200  Language Extensions
5201 \layout Standard
5202
5203 In addition to the ANSI storage classes SDCC allows the following MCS51
5204  specific storage classes.
5205 \layout Subsubsection
5206
5207 xdata
5208 \begin_inset LatexCommand \index{xdata}
5209
5210 \end_inset
5211
5212
5213 \layout Standard
5214
5215 Variables declared with this storage class will be placed in the extern
5216  RAM.
5217  This is the
5218 \series bold
5219 default
5220 \series default
5221  storage class for Large Memory model, e.g.:
5222 \newline
5223
5224 \newline
5225
5226 \family typewriter
5227 xdata unsigned char xduc;
5228 \layout Subsubsection
5229
5230 data
5231 \begin_inset LatexCommand \index{data}
5232
5233 \end_inset
5234
5235
5236 \layout Standard
5237
5238 This is the
5239 \series bold
5240 default
5241 \series default
5242  storage class for Small Memory model.
5243  Variables declared with this storage class will be allocated in the internal
5244  RAM, e.g.:
5245 \newline
5246
5247 \newline
5248
5249 \family typewriter
5250 data int iramdata;
5251 \layout Subsubsection
5252
5253 idata
5254 \begin_inset LatexCommand \index{idata}
5255
5256 \end_inset
5257
5258
5259 \layout Standard
5260
5261 Variables declared with this storage class will be allocated into the indirectly
5262  addressable portion of the internal ram of a 8051, e.g.:
5263 \newline
5264
5265 \newline
5266
5267 \family typewriter
5268 idata int idi;
5269 \layout Subsubsection
5270
5271 bit
5272 \begin_inset LatexCommand \index{bit}
5273
5274 \end_inset
5275
5276
5277 \layout Standard
5278
5279 This is a data-type and a storage class specifier.
5280  When a variable is declared as a bit, it is allocated into the bit addressable
5281  memory of 8051, e.g.:
5282 \newline
5283
5284 \newline
5285
5286 \family typewriter
5287 bit iFlag;
5288 \layout Subsubsection
5289
5290 sfr
5291 \begin_inset LatexCommand \index{sfr}
5292
5293 \end_inset
5294
5295  / sbit
5296 \begin_inset LatexCommand \index{sbit}
5297
5298 \end_inset
5299
5300
5301 \layout Standard
5302
5303 Like the bit keyword,
5304 \emph on
5305 sfr / sbit
5306 \emph default
5307 signifies both a data-type and storage class, they are used to describe
5308  the special function registers and special bit variables of a 8051, eg:
5309 \newline
5310
5311 \newline
5312
5313 \family typewriter
5314 sfr at 0x80 P0; /* special function register P0 at location 0x80 */
5315 \newline
5316 sbit at 0xd7 CY; /* CY (Carry Flag
5317 \begin_inset LatexCommand \index{Carry flag}
5318
5319 \end_inset
5320
5321 ) */
5322 \layout Subsection
5323
5324 Pointers
5325 \begin_inset LatexCommand \index{Pointers}
5326
5327 \end_inset
5328
5329
5330 \layout Standard
5331
5332 SDCC allows (via language extensions) pointers to explicitly point to any
5333  of the memory spaces
5334 \begin_inset LatexCommand \index{memory spaces}
5335
5336 \end_inset
5337
5338  of the 8051.
5339  In addition to the explicit pointers, the compiler uses (by default) generic
5340  pointers which can be used to point to any of the memory spaces.
5341 \newline
5342
5343 \newline
5344 Pointer declaration examples:
5345 \newline
5346
5347 \size small
5348
5349 \newline
5350
5351 \family typewriter
5352 \size default
5353 /* pointer physically in xternal ram pointing to object in internal ram
5354  */
5355 \newline
5356 data unsigned char * xdata p;
5357 \newline
5358
5359 \newline
5360 /* pointer physically in code rom pointing to data in xdata space */
5361 \newline
5362 xdata unsigned char * code p;
5363 \newline
5364
5365 \newline
5366 /* pointer physically in code space pointing to data in code space */
5367 \newline
5368 code unsigned char * code p;
5369 \newline
5370
5371 \newline
5372 /* the folowing is a generic pointer physically located in xdata space */
5373 \newline
5374 char * xdata p;
5375 \family default
5376 \size small
5377
5378 \newline
5379
5380 \newline
5381
5382 \size default
5383 Well you get the idea.
5384
5385 \newline
5386
5387 \newline
5388 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
5389 \emph on
5390 generic
5391 \emph default
5392  pointers.
5393
5394 \size small
5395
5396 \newline
5397
5398 \newline
5399
5400 \size default
5401 The highest order byte of the
5402 \emph on
5403 generic
5404 \emph default
5405  pointers contains the data space information.
5406  Assembler support routines are called whenever data is stored or retrieved
5407  using
5408 \emph on
5409 generic
5410 \emph default
5411  pointers.
5412  These are useful for developing reusable library routines.
5413  Explicitly specifying the pointer type will generate the most efficient
5414  code.
5415 \layout Subsection
5416
5417 Parameters
5418 \begin_inset LatexCommand \index{Parameters}
5419
5420 \end_inset
5421
5422  & Local Variables
5423 \begin_inset LatexCommand \index{Local Variables}
5424
5425 \end_inset
5426
5427
5428 \layout Standard
5429
5430 Automatic (local) variables and parameters to functions can either be placed
5431  on the stack or in data-space.
5432  The default action of the compiler is to place these variables in the internal
5433  RAM (for small model) or external RAM (for large model).
5434  This in fact makes them
5435 \emph on
5436 static
5437 \begin_inset LatexCommand \index{static}
5438
5439 \end_inset
5440
5441
5442 \emph default
5443  so by default functions are non-reentrant
5444 \begin_inset LatexCommand \index{non-reentrant}
5445
5446 \end_inset
5447
5448 .
5449 \newline
5450
5451 \newline
5452 They can be placed on the stack
5453 \begin_inset LatexCommand \index{stack}
5454
5455 \end_inset
5456
5457  either by using the
5458 \emph on
5459  ---stack-auto
5460 \begin_inset LatexCommand \index{--stack-auto}
5461
5462 \end_inset
5463
5464
5465 \emph default
5466  option or by using the
5467 \emph on
5468 reentrant
5469 \begin_inset LatexCommand \index{reentrant}
5470
5471 \end_inset
5472
5473
5474 \emph default
5475  keyword in the function declaration, e.g.:
5476 \newline
5477
5478 \size small
5479
5480 \newline
5481
5482 \family typewriter
5483 \size default
5484 unsigned char foo(char i) reentrant
5485 \newline
5486 {
5487 \newline
5488 ...
5489
5490 \newline
5491 }
5492 \newline
5493
5494 \family default
5495
5496 \newline
5497 Since stack space on 8051 is limited, the
5498 \emph on
5499 reentrant
5500 \emph default
5501 keyword or the
5502 \emph on
5503  ---stack-auto
5504 \emph default
5505  option should be used sparingly.
5506  Note that the reentrant keyword just means that the parameters & local
5507  variables will be allocated to the stack, it
5508 \emph on
5509 does not
5510 \emph default
5511  mean that the function is register bank independent.
5512 \newline
5513
5514 \newline
5515 Local variables can be assigned storage classes and absolute
5516 \begin_inset LatexCommand \index{absolute}
5517
5518 \end_inset
5519
5520  addresses, e.g.:
5521 \newline
5522
5523 \newline
5524
5525 \family typewriter
5526 unsigned char foo() {
5527 \newline
5528 \SpecialChar ~
5529 \SpecialChar ~
5530 \SpecialChar ~
5531 \SpecialChar ~
5532 xdata unsigned char i;
5533 \newline
5534 \SpecialChar ~
5535 \SpecialChar ~
5536 \SpecialChar ~
5537 \SpecialChar ~
5538 bit bvar;
5539 \newline
5540 \SpecialChar ~
5541 \SpecialChar ~
5542 \SpecialChar ~
5543 \SpecialChar ~
5544 data at 0x31 unsiged char j;
5545 \newline
5546 \SpecialChar ~
5547 \SpecialChar ~
5548 \SpecialChar ~
5549 \SpecialChar ~
5550 ...
5551
5552 \newline
5553 }
5554 \newline
5555
5556 \newline
5557
5558 \family default
5559 In the above example the variable
5560 \emph on
5561 i
5562 \emph default
5563  will be allocated in the external ram,
5564 \emph on
5565 bvar
5566 \emph default
5567  in bit addressable space and
5568 \emph on
5569  j
5570 \emph default
5571  in internal ram.
5572  When compiled with
5573 \emph on
5574 ---stack-auto
5575 \emph default
5576  or when a function is declared as
5577 \emph on
5578 reentrant
5579 \emph default
5580  this should only be done for static variables.
5581 \layout Standard
5582
5583 Parameters however are not allowed any storage class, (storage classes for
5584  parameters will be ignored), their allocation is governed by the memory
5585  model in use, and the reentrancy options.
5586 \layout Subsection
5587
5588 Overlaying
5589 \begin_inset LatexCommand \index{Overlaying}
5590
5591 \end_inset
5592
5593
5594 \layout Standard
5595
5596 For non-reentrant functions SDCC will try to reduce internal ram space usage
5597  by overlaying parameters and local variables of a function (if possible).
5598  Parameters and local variables of a function will be allocated to an overlayabl
5599 e segment if the function has
5600 \emph on
5601 no other function calls and the function is non-reentrant and the memory
5602  model
5603 \begin_inset LatexCommand \index{memory model}
5604
5605 \end_inset
5606
5607  is small.
5608
5609 \emph default
5610  If an explicit storage class is specified for a local variable, it will
5611  NOT be overlayed.
5612 \layout Standard
5613
5614 Note that the compiler (not the linkage editor) makes the decision for overlayin
5615 g the data items.
5616  Functions that are called from an interrupt service routine should be preceded
5617  by a #pragma\SpecialChar ~
5618 NOOVERLAY
5619 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
5620
5621 \end_inset
5622
5623  if they are not reentrant.
5624 \layout Standard
5625
5626 Also note that the compiler does not do any processing of inline
5627 \begin_inset LatexCommand \index{inline}
5628
5629 \end_inset
5630
5631  assembler code, so the compiler might incorrectly assign local variables
5632  and parameters of a function into the overlay segment if the inline assembler
5633  code calls other c-functions that might use the overlay.
5634  In that case the #pragma\SpecialChar ~
5635 NOOVERLAY should be used.
5636 \layout Standard
5637
5638 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
5639 tion
5640 \begin_inset LatexCommand \index{multiplication}
5641
5642 \end_inset
5643
5644  or division
5645 \begin_inset LatexCommand \index{division}
5646
5647 \end_inset
5648
5649  will NOT be overlayed since these are implemented using external functions,
5650  e.g.:
5651 \newline
5652
5653 \newline
5654
5655 \family typewriter
5656 #pragma SAVE
5657 \newline
5658 #pragma NOOVERLAY
5659 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
5660
5661 \end_inset
5662
5663
5664 \newline
5665 void set_error(unsigned char errcd)
5666 \newline
5667 {
5668 \newline
5669 \SpecialChar ~
5670 \SpecialChar ~
5671 \SpecialChar ~
5672 \SpecialChar ~
5673 P3 = errcd;
5674 \newline
5675 }
5676 \newline
5677 #pragma RESTORE
5678 \newline
5679
5680 \newline
5681 void some_isr () interrupt
5682 \begin_inset LatexCommand \index{interrupt}
5683
5684 \end_inset
5685
5686  2 using
5687 \begin_inset LatexCommand \index{using}
5688
5689 \end_inset
5690
5691  1
5692 \newline
5693 {
5694 \newline
5695 \SpecialChar ~
5696 \SpecialChar ~
5697 \SpecialChar ~
5698 \SpecialChar ~
5699 ...
5700 \newline
5701 \SpecialChar ~
5702 \SpecialChar ~
5703 \SpecialChar ~
5704 \SpecialChar ~
5705 set_error(10);
5706 \newline
5707 \SpecialChar ~
5708 \SpecialChar ~
5709 \SpecialChar ~
5710 \SpecialChar ~
5711 ...
5712
5713 \newline
5714 }
5715 \newline
5716
5717 \newline
5718
5719 \family default
5720 In the above example the parameter
5721 \emph on
5722 errcd
5723 \emph default
5724  for the function
5725 \emph on
5726 set_error
5727 \emph default
5728  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
5729 NOOVERLAY was
5730  not present, this could cause unpredictable runtime behavior when called
5731  from an ISR.
5732  The #pragma\SpecialChar ~
5733 NOOVERLAY ensures that the parameters and local variables for
5734  the function are NOT overlayed.
5735 \layout Subsection
5736
5737 Interrupt Service Routines
5738 \begin_inset LatexCommand \index{Interrupt Service Routines}
5739
5740 \end_inset
5741
5742
5743 \layout Standard
5744
5745 SDCC allows interrupt service routines to be coded in C, with some extended
5746  keywords.
5747 \newline
5748
5749 \newline
5750
5751 \family typewriter
5752 void timer_isr (void) interrupt 2 using 1
5753 \newline
5754 {
5755 \newline
5756 ..
5757
5758 \newline
5759 }
5760 \newline
5761
5762 \newline
5763
5764 \family default
5765 The number following the
5766 \emph on
5767 interrupt
5768 \begin_inset LatexCommand \index{interrupt}
5769
5770 \end_inset
5771
5772
5773 \emph default
5774  keyword is the interrupt number this routine will service.
5775  The compiler will insert a call to this routine in the interrupt vector
5776  table for the interrupt number specified.
5777  The
5778 \emph on
5779 using
5780 \emph default
5781  keyword is used to tell the compiler to use the specified register bank
5782  (8051 specific) when generating code for this function.
5783  Note that when some function is called from an interrupt service routine
5784  it should be preceded by a #pragma\SpecialChar ~
5785 NOOVERLAY
5786 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
5787
5788 \end_inset
5789
5790  if it is not reentrant.
5791  A special note here, int (16 bit) and long (32 bit) integer division, multiplic
5792 ation & modulus operations are implemented using external support routines
5793  developed in ANSI-C, if an interrupt service routine needs to do any of
5794  these operations then the support routines (as mentioned in a following
5795  section) will have to be recompiled using the
5796 \emph on
5797  ---stack-auto
5798 \begin_inset LatexCommand \index{---stack-auto}
5799
5800 \end_inset
5801
5802
5803 \emph default
5804  option and the source file will need to be compiled using the
5805 \emph on
5806 ---int-long-ren
5807 \emph default
5808 t
5809 \begin_inset LatexCommand \index{---int-long-rent}
5810
5811 \end_inset
5812
5813  compiler option.
5814 \layout Standard
5815
5816 If you have multiple source files in your project, interrupt service routines
5817  can be present in any of them, but a prototype of the isr MUST be present
5818  or included in the file that contains the function
5819 \emph on
5820 main
5821 \emph default
5822 .
5823 \layout Standard
5824
5825 Interrupt Numbers and the corresponding address & descriptions for the Standard
5826  8051 are listed below.
5827  SDCC will automatically adjust the interrupt vector table
5828 \begin_inset LatexCommand \index{ interrupt vector table}
5829
5830 \end_inset
5831
5832  to the maximum interrupt number specified.
5833 \newline
5834
5835 \layout Standard
5836
5837
5838 \begin_inset  Tabular
5839 <lyxtabular version="3" rows="6" columns="3">
5840 <features>
5841 <column alignment="center" valignment="top" leftline="true" width="0in">
5842 <column alignment="center" valignment="top" leftline="true" width="0in">
5843 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
5844 <row topline="true" bottomline="true">
5845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5846 \begin_inset Text
5847
5848 \layout Standard
5849
5850 Interrupt #
5851 \end_inset
5852 </cell>
5853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5854 \begin_inset Text
5855
5856 \layout Standard
5857
5858 Description
5859 \end_inset
5860 </cell>
5861 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5862 \begin_inset Text
5863
5864 \layout Standard
5865
5866 Vector Address
5867 \end_inset
5868 </cell>
5869 </row>
5870 <row topline="true">
5871 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5872 \begin_inset Text
5873
5874 \layout Standard
5875
5876 0
5877 \end_inset
5878 </cell>
5879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5880 \begin_inset Text
5881
5882 \layout Standard
5883
5884 External 0
5885 \end_inset
5886 </cell>
5887 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5888 \begin_inset Text
5889
5890 \layout Standard
5891
5892 0x0003
5893 \end_inset
5894 </cell>
5895 </row>
5896 <row topline="true">
5897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5898 \begin_inset Text
5899
5900 \layout Standard
5901
5902 1
5903 \end_inset
5904 </cell>
5905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5906 \begin_inset Text
5907
5908 \layout Standard
5909
5910 Timer 0
5911 \end_inset
5912 </cell>
5913 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5914 \begin_inset Text
5915
5916 \layout Standard
5917
5918 0x000B
5919 \end_inset
5920 </cell>
5921 </row>
5922 <row topline="true">
5923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5924 \begin_inset Text
5925
5926 \layout Standard
5927
5928 2
5929 \end_inset
5930 </cell>
5931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5932 \begin_inset Text
5933
5934 \layout Standard
5935
5936 External 1
5937 \end_inset
5938 </cell>
5939 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5940 \begin_inset Text
5941
5942 \layout Standard
5943
5944 0x0013
5945 \end_inset
5946 </cell>
5947 </row>
5948 <row topline="true">
5949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5950 \begin_inset Text
5951
5952 \layout Standard
5953
5954 3
5955 \end_inset
5956 </cell>
5957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5958 \begin_inset Text
5959
5960 \layout Standard
5961
5962 Timer 1
5963 \end_inset
5964 </cell>
5965 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5966 \begin_inset Text
5967
5968 \layout Standard
5969
5970 0x001B
5971 \end_inset
5972 </cell>
5973 </row>
5974 <row topline="true" bottomline="true">
5975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5976 \begin_inset Text
5977
5978 \layout Standard
5979
5980 4
5981 \end_inset
5982 </cell>
5983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5984 \begin_inset Text
5985
5986 \layout Standard
5987
5988 Serial
5989 \end_inset
5990 </cell>
5991 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5992 \begin_inset Text
5993
5994 \layout Standard
5995
5996 0x0023
5997 \end_inset
5998 </cell>
5999 </row>
6000 </lyxtabular>
6001
6002 \end_inset
6003
6004
6005 \newline
6006
6007 \newline
6008 If the interrupt service routine is defined without
6009 \emph on
6010 using
6011 \begin_inset LatexCommand \index{using}
6012
6013 \end_inset
6014
6015
6016 \emph default
6017  a register bank or with register bank 0 (using 0), the compiler will save
6018  the registers used by itself on the stack upon entry and restore them at
6019  exit, however if such an interrupt service routine calls another function
6020  then the entire register bank will be saved on the stack.
6021  This scheme may be advantageous for small interrupt service routines which
6022  have low register usage.
6023 \layout Standard
6024
6025 If the interrupt service routine is defined to be using a specific register
6026  bank then only
6027 \emph on
6028 a, b & dptr
6029 \emph default
6030  are save and restored, if such an interrupt service routine calls another
6031  function (using another register bank) then the entire register bank of
6032  the called function will be saved on the stack.
6033  This scheme is recommended for larger interrupt service routines.
6034 \layout Standard
6035
6036 Calling other functions from an interrupt service routine is not recommended,
6037  avoid it if possible.
6038 \newline
6039
6040 \newline
6041 Also see the _naked modifier.
6042 \layout Subsection
6043
6044 Critical Functions
6045 \layout Standard
6046
6047
6048 \shape italic
6049 <TODO: this isn't implemented at all!>
6050 \shape default
6051
6052 \newline
6053
6054 \newline
6055 A special keyword may be associated with a function declaring it as
6056 \emph on
6057 critical
6058 \emph default
6059 .
6060  SDCC will generate code to disable all interrupts upon entry to a critical
6061  function and enable them back before returning.
6062  Note that nesting critical functions may cause unpredictable results.
6063 \newline
6064
6065 \size small
6066
6067 \newline
6068
6069 \family typewriter
6070 \size default
6071 int foo () critical
6072 \newline
6073 {
6074 \newline
6075 ...
6076
6077 \newline
6078 ...
6079
6080 \newline
6081 }
6082 \newline
6083
6084 \family default
6085
6086 \newline
6087 The critical attribute maybe used with other attributes like
6088 \emph on
6089 reentrant.
6090 \layout Subsection
6091
6092 Naked Functions
6093 \begin_inset LatexCommand \index{Naked Functions}
6094
6095 \end_inset
6096
6097
6098 \layout Standard
6099
6100 A special keyword may be associated with a function declaring it as
6101 \emph on
6102 _naked
6103 \begin_inset LatexCommand \index{\_naked}
6104
6105 \end_inset
6106
6107 .
6108
6109 \emph default
6110 The
6111 \emph on
6112 _naked
6113 \emph default
6114  function modifier attribute prevents the compiler from generating prologue
6115 \begin_inset LatexCommand \index{function prologue}
6116
6117 \end_inset
6118
6119  and epilogue
6120 \begin_inset LatexCommand \index{function epilogue}
6121
6122 \end_inset
6123
6124  code for that function.
6125  This means that the user is entirely responsible for such things as saving
6126  any registers that may need to be preserved, selecting the proper register
6127  bank, generating the
6128 \emph on
6129 return
6130 \emph default
6131  instruction at the end, etc.
6132  Practically, this means that the contents of the function must be written
6133  in inline assembler.
6134  This is particularly useful for interrupt functions, which can have a large
6135  (and often unnecessary) prologue/epilogue.
6136  For example, compare the code generated by these two functions:
6137 \newline
6138
6139 \newline
6140
6141 \family typewriter
6142 data unsigned char counter;
6143 \newline
6144 void simpleInterrupt(void) interrupt
6145 \begin_inset LatexCommand \index{interrupt}
6146
6147 \end_inset
6148
6149  1
6150 \newline
6151 {
6152 \newline
6153 \SpecialChar ~
6154 \SpecialChar ~
6155 \SpecialChar ~
6156 \SpecialChar ~
6157 counter++;
6158 \newline
6159 }
6160 \newline
6161
6162 \newline
6163 void nakedInterrupt(void) interrupt 2 _naked
6164 \newline
6165 {
6166 \newline
6167 \SpecialChar ~
6168 \SpecialChar ~
6169 \SpecialChar ~
6170 \SpecialChar ~
6171 _asm
6172 \newline
6173 \SpecialChar ~
6174 \SpecialChar ~
6175 \SpecialChar ~
6176 \SpecialChar ~
6177 \SpecialChar ~
6178 \SpecialChar ~
6179 inc\SpecialChar ~
6180 \SpecialChar ~
6181 \SpecialChar ~
6182 \SpecialChar ~
6183 \SpecialChar ~
6184 _counter
6185 \newline
6186 \SpecialChar ~
6187 \SpecialChar ~
6188 \SpecialChar ~
6189 \SpecialChar ~
6190 \SpecialChar ~
6191 \SpecialChar ~
6192 reti\SpecialChar ~
6193 \SpecialChar ~
6194 \SpecialChar ~
6195 \SpecialChar ~
6196 ; MUST explicitly include ret in _naked function.
6197 \newline
6198 \SpecialChar ~
6199 \SpecialChar ~
6200 \SpecialChar ~
6201 \SpecialChar ~
6202 _endasm;
6203 \newline
6204 }
6205 \family default
6206
6207 \newline
6208
6209 \newline
6210 For an 8051 target, the generated simpleInterrupt looks like:
6211 \newline
6212
6213 \newline
6214
6215 \family typewriter
6216 _simpleIterrupt:
6217 \newline
6218 \SpecialChar ~
6219 \SpecialChar ~
6220 \SpecialChar ~
6221 \SpecialChar ~
6222 push\SpecialChar ~
6223 \SpecialChar ~
6224 \SpecialChar ~
6225 \SpecialChar ~
6226 acc
6227 \newline
6228 \SpecialChar ~
6229 \SpecialChar ~
6230 \SpecialChar ~
6231 \SpecialChar ~
6232 push\SpecialChar ~
6233 \SpecialChar ~
6234 \SpecialChar ~
6235 \SpecialChar ~
6236 b
6237 \newline
6238 \SpecialChar ~
6239 \SpecialChar ~
6240 \SpecialChar ~
6241 \SpecialChar ~
6242 push\SpecialChar ~
6243 \SpecialChar ~
6244 \SpecialChar ~
6245 \SpecialChar ~
6246 dpl
6247 \newline
6248 \SpecialChar ~
6249 \SpecialChar ~
6250 \SpecialChar ~
6251 \SpecialChar ~
6252 push\SpecialChar ~
6253 \SpecialChar ~
6254 \SpecialChar ~
6255 \SpecialChar ~
6256 dph
6257 \newline
6258 \SpecialChar ~
6259 \SpecialChar ~
6260 \SpecialChar ~
6261 \SpecialChar ~
6262 push\SpecialChar ~
6263 \SpecialChar ~
6264 \SpecialChar ~
6265 \SpecialChar ~
6266 psw
6267 \newline
6268 \SpecialChar ~
6269 \SpecialChar ~
6270 \SpecialChar ~
6271 \SpecialChar ~
6272 mov\SpecialChar ~
6273 \SpecialChar ~
6274 \SpecialChar ~
6275 \SpecialChar ~
6276 \SpecialChar ~
6277 psw,#0x00
6278 \newline
6279 \SpecialChar ~
6280 \SpecialChar ~
6281 \SpecialChar ~
6282 \SpecialChar ~
6283 inc\SpecialChar ~
6284 \SpecialChar ~
6285 \SpecialChar ~
6286 \SpecialChar ~
6287 \SpecialChar ~
6288 _counter
6289 \newline
6290 \SpecialChar ~
6291 \SpecialChar ~
6292 \SpecialChar ~
6293 \SpecialChar ~
6294 pop\SpecialChar ~
6295 \SpecialChar ~
6296 \SpecialChar ~
6297 \SpecialChar ~
6298 \SpecialChar ~
6299 psw
6300 \newline
6301 \SpecialChar ~
6302 \SpecialChar ~
6303 \SpecialChar ~
6304 \SpecialChar ~
6305 pop\SpecialChar ~
6306 \SpecialChar ~
6307 \SpecialChar ~
6308 \SpecialChar ~
6309 \SpecialChar ~
6310 dph
6311 \newline
6312 \SpecialChar ~
6313 \SpecialChar ~
6314 \SpecialChar ~
6315 \SpecialChar ~
6316 pop\SpecialChar ~
6317 \SpecialChar ~
6318 \SpecialChar ~
6319 \SpecialChar ~
6320 \SpecialChar ~
6321 dpl
6322 \newline
6323 \SpecialChar ~
6324 \SpecialChar ~
6325 \SpecialChar ~
6326 \SpecialChar ~
6327 pop\SpecialChar ~
6328 \SpecialChar ~
6329 \SpecialChar ~
6330 \SpecialChar ~
6331 \SpecialChar ~
6332 b
6333 \newline
6334 \SpecialChar ~
6335 \SpecialChar ~
6336 \SpecialChar ~
6337 \SpecialChar ~
6338 pop\SpecialChar ~
6339 \SpecialChar ~
6340 \SpecialChar ~
6341 \SpecialChar ~
6342 \SpecialChar ~
6343 acc
6344 \newline
6345 \SpecialChar ~
6346 \SpecialChar ~
6347 \SpecialChar ~
6348 \SpecialChar ~
6349 reti
6350 \family default
6351
6352 \newline
6353
6354 \newline
6355 whereas nakedInterrupt looks like:
6356 \newline
6357
6358 \newline
6359
6360 \family typewriter
6361 _nakedInterrupt:
6362 \newline
6363 \SpecialChar ~
6364 \SpecialChar ~
6365 \SpecialChar ~
6366 \SpecialChar ~
6367 inc\SpecialChar ~
6368 \SpecialChar ~
6369 \SpecialChar ~
6370 \SpecialChar ~
6371 _counter
6372 \newline
6373 \SpecialChar ~
6374 \SpecialChar ~
6375 \SpecialChar ~
6376 \SpecialChar ~
6377 reti\SpecialChar ~
6378 \SpecialChar ~
6379 \SpecialChar ~
6380 ; MUST explicitly include ret(i) in _naked function.
6381 \family default
6382
6383 \newline
6384
6385 \newline
6386 While there is nothing preventing you from writing C code inside a _naked
6387  function, there are many ways to shoot yourself in the foot doing this,
6388  and it is recommended that you stick to inline assembler.
6389 \layout Subsection
6390
6391 Functions using private banks
6392 \begin_inset LatexCommand \index{banks}
6393
6394 \end_inset
6395
6396
6397 \layout Standard
6398
6399 The
6400 \emph on
6401 using
6402 \begin_inset LatexCommand \index{using}
6403
6404 \end_inset
6405
6406
6407 \emph default
6408  attribute (which tells the compiler to use a register bank other than the
6409  default bank zero) should only be applied to
6410 \emph on
6411 interrupt
6412 \begin_inset LatexCommand \index{interrupt}
6413
6414 \end_inset
6415
6416
6417 \emph default
6418  functions (see note 1 below).
6419  This will in most circumstances make the generated ISR code more efficient
6420  since it will not have to save registers on the stack.
6421 \layout Standard
6422
6423 The
6424 \emph on
6425 using
6426 \emph default
6427  attribute will have no effect on the generated code for a
6428 \emph on
6429 non-interrupt
6430 \emph default
6431  function (but may occasionally be useful anyway
6432 \begin_inset Foot
6433 collapsed true
6434
6435 \layout Standard
6436
6437 possible exception: if a function is called ONLY from 'interrupt' functions
6438  using a particular bank, it can be declared with the same 'using' attribute
6439  as the calling 'interrupt' functions.
6440  For instance, if you have several ISRs using bank one, and all of them
6441  call memcpy(), it might make sense to create a specialized version of memcpy()
6442  'using 1', since this would prevent the ISR from having to save bank zero
6443  to the stack on entry and switch to bank zero before calling the function
6444 \end_inset
6445
6446 ).
6447 \newline
6448
6449 \emph on
6450 (pending: I don't think this has been done yet)
6451 \layout Standard
6452
6453 An
6454 \emph on
6455 interrupt
6456 \emph default
6457  function using a non-zero bank will assume that it can trash that register
6458  bank, and will not save it.
6459  Since high-priority interrupts
6460 \begin_inset LatexCommand \index{interrupt priority}
6461
6462 \end_inset
6463
6464  can interrupt low-priority ones on the 8051 and friends, this means that
6465  if a high-priority ISR
6466 \emph on
6467 using
6468 \emph default
6469  a particular bank occurs while processing a low-priority ISR
6470 \emph on
6471 using
6472 \emph default
6473  the same bank, terrible and bad things can happen.
6474  To prevent this, no single register bank should be
6475 \emph on
6476 used
6477 \emph default
6478  by both a high priority and a low priority ISR.
6479  This is probably most easily done by having all high priority ISRs use
6480  one bank and all low priority ISRs use another.
6481  If you have an ISR which can change priority at runtime, you're on your
6482  own: I suggest using the default bank zero and taking the small performance
6483  hit.
6484 \layout Standard
6485
6486 It is most efficient if your ISR calls no other functions.
6487  If your ISR must call other functions, it is most efficient if those functions
6488  use the same bank as the ISR (see note 1 below); the next best is if the
6489  called functions use bank zero.
6490  It is very inefficient to call a function using a different, non-zero bank
6491  from an ISR.
6492
6493 \layout Subsection
6494
6495 Absolute Addressing
6496 \begin_inset LatexCommand \index{Absolute Addressing}
6497
6498 \end_inset
6499
6500
6501 \layout Standard
6502
6503 Data items can be assigned an absolute address with the
6504 \emph on
6505 at
6506 \begin_inset LatexCommand \index{at}
6507
6508 \end_inset
6509
6510  <address>
6511 \emph default
6512  keyword, in addition to a storage class, e.g.:
6513 \newline
6514
6515 \newline
6516
6517 \family typewriter
6518 xdata
6519 \begin_inset LatexCommand \index{xdata}
6520
6521 \end_inset
6522
6523  at
6524 \begin_inset LatexCommand \index{at}
6525
6526 \end_inset
6527
6528  0x8000 unsigned char PORTA_8255 ;
6529 \newline
6530
6531 \family default
6532
6533 \newline
6534 In the above example the PORTA_8255 will be allocated to the location 0x8000
6535  of the external ram.
6536  Note that this feature is provided to give the programmer access to
6537 \emph on
6538 memory mapped
6539 \emph default
6540  devices attached to the controller.
6541  The compiler does not actually reserve any space for variables declared
6542  in this way (they are implemented with an equate in the assembler).
6543  Thus it is left to the programmer to make sure there are no overlaps with
6544  other variables that are declared without the absolute address.
6545  The assembler listing file (.lst
6546 \begin_inset LatexCommand \index{.lst}
6547
6548 \end_inset
6549
6550 ) and the linker output files (.rst
6551 \begin_inset LatexCommand \index{.rst}
6552
6553 \end_inset
6554
6555 ) and (.map
6556 \begin_inset LatexCommand \index{.map}
6557
6558 \end_inset
6559
6560 ) are a good places to look for such overlaps.
6561 \newline
6562
6563 \newline
6564 Absolute address can be specified for variables in all storage classes,
6565  e.g.:
6566 \newline
6567
6568 \newline
6569
6570 \family typewriter
6571 bit
6572 \begin_inset LatexCommand \index{bit}
6573
6574 \end_inset
6575
6576  at
6577 \begin_inset LatexCommand \index{at}
6578
6579 \end_inset
6580
6581  0x02 bvar;
6582 \newline
6583
6584 \newline
6585
6586 \family default
6587 The above example will allocate the variable at offset 0x02 in the bit-addressab
6588 le space.
6589  There is no real advantage to assigning absolute addresses to variables
6590  in this manner, unless you want strict control over all the variables allocated.
6591 \layout Subsection
6592
6593 Startup Code
6594 \begin_inset LatexCommand \index{Startup Code}
6595
6596 \end_inset
6597
6598
6599 \layout Standard
6600
6601 The compiler inserts a call to the C routine
6602 \emph on
6603 _sdcc_external_startup()
6604 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
6605
6606 \end_inset
6607
6608
6609 \series bold
6610 \emph default
6611
6612 \series default
6613 at the start of the CODE area.
6614  This routine is in the runtime library.
6615  By default this routine returns 0, if this routine returns a non-zero value,
6616  the static & global variable initialization will be skipped and the function
6617  main will be invoked Other wise static & global variables will be initialized
6618  before the function main is invoked.
6619  You could add a
6620 \emph on
6621 _sdcc_external_startup()
6622 \emph default
6623  routine to your program to override the default if you need to setup hardware
6624  or perform some other critical operation prior to static & global variable
6625  initialization.
6626 \layout Subsection
6627
6628 Inline Assembler Code
6629 \begin_inset LatexCommand \index{Inline Assembler Code}
6630
6631 \end_inset
6632
6633
6634 \layout Standard
6635
6636 SDCC allows the use of in-line assembler with a few restriction as regards
6637  labels.
6638  All labels defined within inline assembler code
6639 \emph on
6640 has to be
6641 \emph default
6642  of the form
6643 \emph on
6644 nnnnn$
6645 \emph default
6646  where nnnn is a number less than 100 (which implies a limit of utmost 100
6647  inline assembler labels
6648 \emph on
6649 per function
6650 \emph default
6651 \noun on
6652 )
6653 \noun default
6654 .
6655  It is strongly recommended that each assembly instruction (including labels)
6656  be placed in a separate line (as the example shows).
6657  When the
6658 \emph on
6659 ---peep-asm
6660 \begin_inset LatexCommand \index{--peep-asm}
6661
6662 \end_inset
6663
6664
6665 \emph default
6666  command line option is used, the inline assembler code will be passed through
6667  the peephole optimizer
6668 \begin_inset LatexCommand \index{Peephole optimizer}
6669
6670 \end_inset
6671
6672 .
6673  This might cause some unexpected changes in the inline assembler code.
6674  Please go throught the peephole optimizer rules defined in file
6675 \emph on
6676 SDCCpeeph.def
6677 \emph default
6678  carefully before using this option.
6679 \newline
6680
6681 \newline
6682
6683 \family typewriter
6684 _asm
6685 \begin_inset LatexCommand \index{\_asm}
6686
6687 \end_inset
6688
6689
6690 \newline
6691 \SpecialChar ~
6692 \SpecialChar ~
6693 \SpecialChar ~
6694 \SpecialChar ~
6695 mov\SpecialChar ~
6696 \SpecialChar ~
6697 \SpecialChar ~
6698 \SpecialChar ~
6699 \SpecialChar ~
6700 b,#10
6701 \newline
6702 00001$:
6703 \newline
6704 \SpecialChar ~
6705 \SpecialChar ~
6706 \SpecialChar ~
6707 \SpecialChar ~
6708 djnz\SpecialChar ~
6709 \SpecialChar ~
6710 \SpecialChar ~
6711 \SpecialChar ~
6712 b,00001$
6713 \newline
6714 _endasm
6715 \begin_inset LatexCommand \index{\_endasm}
6716
6717 \end_inset
6718
6719  ;
6720 \family default
6721 \size small
6722
6723 \newline
6724
6725 \newline
6726
6727 \size default
6728 The inline assembler code can contain any valid code understood by the assembler
6729 , this includes any assembler directives and comment lines.
6730  The compiler does not do any validation of the code within the
6731 \family typewriter
6732 _asm ...
6733  _endasm;
6734 \family default
6735  keyword pair.
6736
6737 \newline
6738
6739 \newline
6740 Inline assembler code cannot reference any C-Labels, however it can reference
6741  labels
6742 \begin_inset LatexCommand \index{Labels}
6743
6744 \end_inset
6745
6746  defined by the inline assembler, e.g.:
6747 \newline
6748
6749 \newline
6750
6751 \family typewriter
6752 foo() {
6753 \newline
6754 \SpecialChar ~
6755 \SpecialChar ~
6756 \SpecialChar ~
6757 \SpecialChar ~
6758 /* some c code */
6759 \newline
6760 \SpecialChar ~
6761 \SpecialChar ~
6762 \SpecialChar ~
6763 \SpecialChar ~
6764 _asm
6765 \newline
6766 \SpecialChar ~
6767 \SpecialChar ~
6768 \SpecialChar ~
6769 \SpecialChar ~
6770 \SpecialChar ~
6771 \SpecialChar ~
6772 ; some assembler code
6773 \newline
6774 \SpecialChar ~
6775 \SpecialChar ~
6776 \SpecialChar ~
6777 \SpecialChar ~
6778 \SpecialChar ~
6779 \SpecialChar ~
6780 ljmp $0003
6781 \newline
6782 \SpecialChar ~
6783 \SpecialChar ~
6784 \SpecialChar ~
6785 \SpecialChar ~
6786 _endasm;
6787 \newline
6788 \SpecialChar ~
6789 \SpecialChar ~
6790 \SpecialChar ~
6791 \SpecialChar ~
6792 /* some more c code */
6793 \newline
6794 clabel:\SpecialChar ~
6795 \SpecialChar ~
6796 /* inline assembler cannot reference this label */
6797 \newline
6798 \SpecialChar ~
6799 \SpecialChar ~
6800 \SpecialChar ~
6801 \SpecialChar ~
6802 _asm
6803 \newline
6804 \SpecialChar ~
6805 \SpecialChar ~
6806 \SpecialChar ~
6807 \SpecialChar ~
6808 $0003: ;label (can be reference by inline assembler only)
6809 \newline
6810 \SpecialChar ~
6811 \SpecialChar ~
6812 \SpecialChar ~
6813 \SpecialChar ~
6814 _endasm ;
6815 \newline
6816 \SpecialChar ~
6817 \SpecialChar ~
6818 \SpecialChar ~
6819 \SpecialChar ~
6820 /* some more c code */
6821 \newline
6822 }
6823 \newline
6824
6825 \newline
6826
6827 \family default
6828 In other words inline assembly code can access labels defined in inline
6829  assembly within the scope of the funtion.
6830
6831 \layout Standard
6832
6833 The same goes the other way, ie.
6834  labels defines in inline assembly CANNOT be accessed by C statements.
6835 \layout Subsection
6836
6837 int (16 bit)
6838 \begin_inset LatexCommand \index{int (16 bit)}
6839
6840 \end_inset
6841
6842  and long (32 bit)
6843 \begin_inset LatexCommand \index{long (32 bit)}
6844
6845 \end_inset
6846
6847  Support
6848 \layout Standard
6849
6850 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
6851  multiplication and modulus operations are implemented by support routines.
6852  These support routines are all developed in ANSI-C to facilitate porting
6853  to other MCUs, although some model specific assembler optimations are used.
6854  The following files contain the described routine, all of them can be found
6855  in <installdir>/share/sdcc/lib.
6856 \newline
6857
6858 \newline
6859
6860 \emph on
6861 <pending: tabularise this>
6862 \emph default
6863
6864 \newline
6865
6866 \newline
6867 _mulsint.c - signed 16 bit multiplication (calls _muluint)
6868 \newline
6869 _muluint.c - unsigned 16 bit multiplication
6870 \newline
6871 _divsint.c - signed 16 bit division (calls _divuint)
6872 \newline
6873 _divuint.c - unsigned 16 bit division
6874 \newline
6875 _modsint.c - signed 16 bit modulus (call _moduint)
6876 \newline
6877 _moduint.c - unsigned 16 bit modulus
6878 \newline
6879 _mulslong.c - signed 32 bit multiplication (calls _mululong)
6880 \newline
6881 _mululong.c - unsigned32 bit multiplication
6882 \newline
6883 _divslong.c - signed 32 division (calls _divulong)
6884 \newline
6885 _divulong.c - unsigned 32 division
6886 \newline
6887 _modslong.c - signed 32 bit modulus (calls _modulong)
6888 \newline
6889 _modulong.c - unsigned 32 bit modulus
6890 \size footnotesize
6891
6892 \newline
6893
6894 \newline
6895
6896 \size default
6897 Since they are compiled as
6898 \emph on
6899 non-reentrant
6900 \emph default
6901
6902 \begin_inset LatexCommand \index{reentrant}
6903
6904 \end_inset
6905
6906
6907 \begin_inset LatexCommand \index{non-reentrant}
6908
6909 \end_inset
6910
6911 , interrupt
6912 \begin_inset LatexCommand \index{interrupt}
6913
6914 \end_inset
6915
6916  service routines should not do any of the above operations.
6917  If this is unavoidable then the above routines will need to be compiled
6918  with the
6919 \emph on
6920 ---stack-auto
6921 \begin_inset LatexCommand \index{---stack-auto}
6922
6923 \end_inset
6924
6925
6926 \emph default
6927  option, after which the source program will have to be compiled with
6928 \emph on
6929 ---int-long-rent
6930 \begin_inset LatexCommand \index{---int-long-rent}
6931
6932 \end_inset
6933
6934
6935 \emph default
6936  option.
6937 \layout Subsection
6938
6939 Floating Point Support
6940 \begin_inset LatexCommand \index{Floating Point Support}
6941
6942 \end_inset
6943
6944
6945 \layout Standard
6946
6947 SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
6948  point support routines are derived from gcc's floatlib.c and consists of
6949  the following routines:
6950 \newline
6951
6952 \newline
6953
6954 \emph on
6955 <pending: tabularise this>
6956 \emph default
6957
6958 \newline
6959
6960 \newline
6961 _fsadd.c - add floating point numbers
6962 \newline
6963 _fssub.c - subtract floating point numbers
6964 \newline
6965 _fsdiv.c - divide floating point numbers
6966 \newline
6967 _fsmul.c - multiply floating point numbers
6968 \newline
6969 _fs2uchar.c - convert floating point to unsigned char
6970 \newline
6971 _fs2char.c - convert floating point to signed char
6972 \newline
6973 _fs2uint.c - convert floating point to unsigned int
6974 \newline
6975 _fs2int.c - convert floating point to signed int
6976 \newline
6977 _fs2ulong.c - convert floating point to unsigned long
6978 \newline
6979 _fs2long.c - convert floating point to signed long
6980 \newline
6981 _uchar2fs.c - convert unsigned char to floating point
6982 \newline
6983 _char2fs.c - convert char to floating point number
6984 \newline
6985 _uint2fs.c - convert unsigned int to floating point
6986 \newline
6987 _int2fs.c - convert int to floating point numbers
6988 \newline
6989 _ulong2fs.c - convert unsigned long to floating point number
6990 \newline
6991 _long2fs.c - convert long to floating point number
6992 \size footnotesize
6993
6994 \newline
6995
6996 \newline
6997
6998 \size default
6999 Note if all these routines are used simultaneously the data space might
7000  overflow.
7001  For serious floating point usage it is strongly recommended that the large
7002  model be used.
7003 \layout Subsection
7004
7005 MCS51 Memory Models
7006 \begin_inset LatexCommand \index{Memory Models}
7007
7008 \end_inset
7009
7010
7011 \begin_inset LatexCommand \index{MCS51 Memory Models}
7012
7013 \end_inset
7014
7015
7016 \layout Standard
7017
7018 SDCC allows two memory models for MCS51 code, small and large.
7019  Modules compiled with different memory models should
7020 \emph on
7021 never
7022 \emph default
7023  be combined together or the results would be unpredictable.
7024  The library routines supplied with the compiler are compiled as both small
7025  and large.
7026  The compiled library modules are contained in seperate directories as small
7027  and large so that you can link to either set.
7028
7029 \layout Standard
7030
7031 When the large model is used all variables declared without a storage class
7032  will be allocated into the external ram, this includes all parameters and
7033  local variables (for non-reentrant functions).
7034  When the small model is used variables without storage class are allocated
7035  in the internal ram.
7036 \layout Standard
7037
7038 Judicious usage of the processor specific storage classes
7039 \begin_inset LatexCommand \index{storage classes}
7040
7041 \end_inset
7042
7043  and the 'reentrant' function type will yield much more efficient code,
7044  than using the large model.
7045  Several optimizations are disabled when the program is compiled using the
7046  large model, it is therefore strongly recommdended that the small model
7047  be used unless absolutely required.
7048 \layout Subsection
7049
7050 DS390 Memory Models
7051 \begin_inset LatexCommand \index{Memory Models}
7052
7053 \end_inset
7054
7055
7056 \begin_inset LatexCommand \index{DS390 Memory Models}
7057
7058 \end_inset
7059
7060
7061 \layout Standard
7062
7063 The only model supported is Flat 24
7064 \begin_inset LatexCommand \index{Flat 24}
7065
7066 \end_inset
7067
7068 .
7069  This generates code for the 24 bit contiguous addressing mode of the Dallas
7070  DS80C390 part.
7071  In this mode, up to four meg of external RAM or code space can be directly
7072  addressed.
7073  See the data sheets at www.dalsemi.com for further information on this part.
7074 \newline
7075
7076 \newline
7077 In older versions of the compiler, this option was used with the MCS51 code
7078  generator (
7079 \emph on
7080 -mmcs51
7081 \emph default
7082 ).
7083  Now, however, the '390 has it's own code generator, selected by the
7084 \emph on
7085 -mds390
7086 \emph default
7087  switch.
7088
7089 \newline
7090
7091 \newline
7092 Note that the compiler does not generate any code to place the processor
7093  into 24 bitmode (although
7094 \emph on
7095 tinibios
7096 \emph default
7097  in the ds390 libraries will do that for you).
7098  If you don't use
7099 \emph on
7100 tinibios
7101 \emph default
7102
7103 \begin_inset LatexCommand \index{tinibios}
7104
7105 \end_inset
7106
7107 , the boot loader or similar code must ensure that the processor is in 24
7108  bit contiguous addressing mode before calling the SDCC startup code.
7109 \newline
7110
7111 \newline
7112 Like the
7113 \emph on
7114 ---model-large
7115 \emph default
7116  option, variables will by default be placed into the XDATA segment.
7117
7118 \newline
7119
7120 \newline
7121 Segments may be placed anywhere in the 4 meg address space using the usual
7122  ---*-loc options.
7123  Note that if any segments are located above 64K, the -r flag must be passed
7124  to the linker to generate the proper segment relocations, and the Intel
7125  HEX output format must be used.
7126  The -r flag can be passed to the linker by using the option
7127 \emph on
7128 -Wl-r
7129 \emph default
7130  on the sdcc command line.
7131  However, currently the linker can not handle code segments > 64k.
7132 \layout Subsection
7133
7134 Defines Created by the Compiler
7135 \begin_inset LatexCommand \index{Defines Created by the Compiler}
7136
7137 \end_inset
7138
7139
7140 \layout Standard
7141
7142 The compiler creates the following #defines
7143 \begin_inset LatexCommand \index{\#defines}
7144
7145 \end_inset
7146
7147 .
7148 \layout Itemize
7149
7150 SDCC
7151 \begin_inset LatexCommand \index{SDCC}
7152
7153 \end_inset
7154
7155  - this Symbol is always defined.
7156 \layout Itemize
7157
7158 SDCC_mcs51
7159 \begin_inset LatexCommand \index{SDCC\_mcs51}
7160
7161 \end_inset
7162
7163  or SDCC_ds390
7164 \begin_inset LatexCommand \index{SDCC\_ds390}
7165
7166 \end_inset
7167
7168  or SDCC_z80
7169 \begin_inset LatexCommand \index{SDCC\_z80}
7170
7171 \end_inset
7172
7173 , etc - depending on the model used (e.g.: -mds390)
7174 \layout Itemize
7175
7176 __mcs51
7177 \begin_inset LatexCommand \index{\_\_mcs51}
7178
7179 \end_inset
7180
7181  or __ds390
7182 \begin_inset LatexCommand \index{\_\_ds390}
7183
7184 \end_inset
7185
7186  or __z80
7187 \begin_inset LatexCommand \index{\_\_z80}
7188
7189 \end_inset
7190
7191 , etc - depending on the model used (e.g.
7192  -mz80)
7193 \layout Itemize
7194
7195 SDCC_STACK_AUTO
7196 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
7197
7198 \end_inset
7199
7200  - this symbol is defined when
7201 \emph on
7202 ---stack-auto
7203 \emph default
7204  option is used.
7205 \layout Itemize
7206
7207 SDCC_MODEL_SMALL
7208 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
7209
7210 \end_inset
7211
7212  - when
7213 \emph on
7214 ---model-small
7215 \emph default
7216  is used.
7217 \layout Itemize
7218
7219 SDCC_MODEL_LARGE
7220 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
7221
7222 \end_inset
7223
7224  - when
7225 \emph on
7226 ---model-large
7227 \emph default
7228  is used.
7229 \layout Itemize
7230
7231 SDCC_USE_XSTACK
7232 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
7233
7234 \end_inset
7235
7236  - when
7237 \emph on
7238 ---xstack
7239 \emph default
7240  option is used.
7241 \layout Itemize
7242
7243 SDCC_STACK_TENBIT
7244 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
7245
7246 \end_inset
7247
7248  - when
7249 \emph on
7250 -mds390
7251 \emph default
7252  is used
7253 \layout Itemize
7254
7255 SDCC_MODEL_FLAT24
7256 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
7257
7258 \end_inset
7259
7260  - when
7261 \emph on
7262 -mds390
7263 \emph default
7264  is used
7265 \layout Section
7266
7267 SDCC Technical Data
7268 \layout Subsection
7269
7270 Optimizations
7271 \begin_inset LatexCommand \index{Optimizations}
7272
7273 \end_inset
7274
7275
7276 \layout Standard
7277
7278 SDCC performs a host of standard optimizations in addition to some MCU specific
7279  optimizations.
7280
7281 \layout Subsubsection
7282
7283 Sub-expression Elimination
7284 \begin_inset LatexCommand \index{Sub-expression Elimination}
7285
7286 \end_inset
7287
7288
7289 \layout Standard
7290
7291 The compiler does local and global common subexpression elimination, e.g.:
7292
7293 \newline
7294
7295 \newline
7296
7297 \family typewriter
7298 i = x + y + 1;
7299 \newline
7300 j = x + y;
7301 \family default
7302
7303 \newline
7304
7305 \newline
7306 will be translated to
7307 \newline
7308
7309 \newline
7310
7311 \family typewriter
7312 iTemp = x + y
7313 \newline
7314 i = iTemp + 1
7315 \newline
7316 j = iTemp
7317 \newline
7318
7319 \family default
7320
7321 \newline
7322 Some subexpressions are not as obvious as the above example, e.g.:
7323 \newline
7324
7325 \newline
7326
7327 \family typewriter
7328 a->b[i].c = 10;
7329 \newline
7330 a->b[i].d = 11;
7331 \family default
7332
7333 \newline
7334
7335 \newline
7336 In this case the address arithmetic a->b[i] will be computed only once;
7337  the equivalent code in C would be.
7338 \newline
7339
7340 \newline
7341
7342 \family typewriter
7343 iTemp = a->b[i];
7344 \newline
7345 iTemp.c = 10;
7346 \newline
7347 iTemp.d = 11;
7348 \family default
7349
7350 \newline
7351
7352 \newline
7353 The compiler will try to keep these temporary variables in registers.
7354 \layout Subsubsection
7355
7356 Dead-Code Elimination
7357 \begin_inset LatexCommand \index{Dead-Code Elimination}
7358
7359 \end_inset
7360
7361
7362 \layout Standard
7363
7364
7365 \family typewriter
7366 int global;
7367 \newline
7368 void f () {
7369 \newline
7370 \SpecialChar ~
7371 \SpecialChar ~
7372 int i;
7373 \newline
7374 \SpecialChar ~
7375 \SpecialChar ~
7376 i = 1; \SpecialChar ~
7377 /* dead store */
7378 \newline
7379 \SpecialChar ~
7380 \SpecialChar ~
7381 global = 1;\SpecialChar ~
7382 /* dead store */
7383 \newline
7384 \SpecialChar ~
7385 \SpecialChar ~
7386 global = 2;
7387 \newline
7388 \SpecialChar ~
7389 \SpecialChar ~
7390 return;
7391 \newline
7392 \SpecialChar ~
7393 \SpecialChar ~
7394 global = 3;\SpecialChar ~
7395 /* unreachable */
7396 \newline
7397 }
7398 \family default
7399
7400 \newline
7401
7402 \newline
7403 will be changed to
7404 \newline
7405
7406 \newline
7407
7408 \family typewriter
7409 int global; void f ()
7410 \newline
7411 {
7412 \newline
7413 \SpecialChar ~
7414 \SpecialChar ~
7415 global = 2;
7416 \newline
7417 \SpecialChar ~
7418 \SpecialChar ~
7419 return;
7420 \newline
7421 }
7422 \layout Subsubsection
7423
7424 Copy-Propagation
7425 \begin_inset LatexCommand \index{Copy-Propagation}
7426
7427 \end_inset
7428
7429
7430 \layout Standard
7431
7432
7433 \family typewriter
7434 int f() {
7435 \newline
7436 \SpecialChar ~
7437 \SpecialChar ~
7438 int i, j;
7439 \newline
7440 \SpecialChar ~
7441 \SpecialChar ~
7442 i = 10;
7443 \newline
7444 \SpecialChar ~
7445 \SpecialChar ~
7446 j = i;
7447 \newline
7448 \SpecialChar ~
7449 \SpecialChar ~
7450 return j;
7451 \newline
7452 }
7453 \family default
7454
7455 \newline
7456
7457 \newline
7458 will be changed to
7459 \newline
7460
7461 \newline
7462
7463 \family typewriter
7464 int f() {
7465 \newline
7466 \SpecialChar ~
7467  \SpecialChar ~
7468  int i,j;
7469 \newline
7470 \SpecialChar ~
7471  \SpecialChar ~
7472  i = 10;
7473 \newline
7474 \SpecialChar ~
7475  \SpecialChar ~
7476  j = 10;
7477 \newline
7478 \SpecialChar ~
7479  \SpecialChar ~
7480  return 10;
7481 \newline
7482 }
7483 \newline
7484
7485 \newline
7486
7487 \family default
7488 Note: the dead stores created by this copy propagation will be eliminated
7489  by dead-code elimination.
7490 \layout Subsubsection
7491
7492 Loop Optimizations
7493 \begin_inset LatexCommand \index{Loop Optimizations}
7494
7495 \end_inset
7496
7497
7498 \layout Standard
7499
7500 Two types of loop optimizations are done by SDCC loop invariant lifting
7501  and strength reduction of loop induction variables.
7502  In addition to the strength reduction the optimizer marks the induction
7503  variables and the register allocator tries to keep the induction variables
7504  in registers for the duration of the loop.
7505  Because of this preference of the register allocator
7506 \begin_inset LatexCommand \index{Register allocator}
7507
7508 \end_inset
7509
7510 , loop induction optimization causes an increase in register pressure, which
7511  may cause unwanted spilling of other temporary variables into the stack
7512 \begin_inset LatexCommand \index{stack}
7513
7514 \end_inset
7515
7516  / data space.
7517  The compiler will generate a warning message when it is forced to allocate
7518  extra space either on the stack or data space.
7519  If this extra space allocation is undesirable then induction optimization
7520  can be eliminated either for the entire source file (with ---noinduction
7521  option) or for a given function only using #pragma\SpecialChar ~
7522 NOINDUCTION
7523 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
7524
7525 \end_inset
7526
7527 .
7528 \newline
7529
7530 \newline
7531 Loop Invariant:
7532 \newline
7533
7534 \newline
7535
7536 \family typewriter
7537 for (i = 0 ; i < 100 ; i ++)
7538 \newline
7539  \SpecialChar ~
7540  \SpecialChar ~
7541 f += k + l;
7542 \family default
7543
7544 \newline
7545
7546 \newline
7547 changed to
7548 \newline
7549
7550 \newline
7551
7552 \family typewriter
7553 itemp = k + l;
7554 \newline
7555 for (i = 0; i < 100; i++)
7556 \newline
7557 \SpecialChar ~
7558 \SpecialChar ~
7559 f += itemp;
7560 \family default
7561
7562 \newline
7563
7564 \newline
7565 As mentioned previously some loop invariants are not as apparent, all static
7566  address computations are also moved out of the loop.
7567 \newline
7568
7569 \newline
7570 Strength Reduction
7571 \begin_inset LatexCommand \index{Strength Reduction}
7572
7573 \end_inset
7574
7575 , this optimization substitutes an expression by a cheaper expression:
7576 \newline
7577
7578 \newline
7579
7580 \family typewriter
7581 for (i=0;i < 100; i++)
7582 \newline
7583 \SpecialChar ~
7584 \SpecialChar ~
7585 ar[i*5] = i*3;
7586 \family default
7587
7588 \newline
7589
7590 \newline
7591 changed to
7592 \newline
7593
7594 \newline
7595
7596 \family typewriter
7597 itemp1 = 0;
7598 \newline
7599 itemp2 = 0;
7600 \newline
7601 for (i=0;i< 100;i++) {
7602 \newline
7603  \SpecialChar ~
7604  \SpecialChar ~
7605 ar[itemp1] = itemp2;
7606 \newline
7607  \SpecialChar ~
7608  \SpecialChar ~
7609 itemp1 += 5;
7610 \newline
7611  \SpecialChar ~
7612  \SpecialChar ~
7613 itemp2 += 3;
7614 \newline
7615 }
7616 \family default
7617
7618 \newline
7619
7620 \newline
7621 The more expensive multiplication
7622 \begin_inset LatexCommand \index{multiplication}
7623
7624 \end_inset
7625
7626  is changed to a less expensive addition.
7627 \layout Subsubsection
7628
7629 Loop Reversing
7630 \begin_inset LatexCommand \index{Loop Reversing}
7631
7632 \end_inset
7633
7634
7635 \layout Standard
7636
7637 This optimization is done to reduce the overhead of checking loop boundaries
7638  for every iteration.
7639  Some simple loops can be reversed and implemented using a
7640 \begin_inset Quotes eld
7641 \end_inset
7642
7643 decrement and jump if not zero
7644 \begin_inset Quotes erd
7645 \end_inset
7646
7647  instruction.
7648  SDCC checks for the following criterion to determine if a loop is reversible
7649  (note: more sophisticated compilers use data-dependency analysis to make
7650  this determination, SDCC uses a more simple minded analysis).
7651 \layout Itemize
7652
7653 The 'for' loop is of the form
7654 \newline
7655
7656 \newline
7657
7658 \family typewriter
7659 for (<symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
7660  <sym> += 1])
7661 \newline
7662 \SpecialChar ~
7663 \SpecialChar ~
7664 \SpecialChar ~
7665 \SpecialChar ~
7666 <for body>
7667 \layout Itemize
7668
7669 The <for body> does not contain
7670 \begin_inset Quotes eld
7671 \end_inset
7672
7673 continue
7674 \begin_inset Quotes erd
7675 \end_inset
7676
7677  or 'break
7678 \begin_inset Quotes erd
7679 \end_inset
7680
7681 .
7682 \layout Itemize
7683
7684 All goto's are contained within the loop.
7685 \layout Itemize
7686
7687 No function calls within the loop.
7688 \layout Itemize
7689
7690 The loop control variable <sym> is not assigned any value within the loop
7691 \layout Itemize
7692
7693 The loop control variable does NOT participate in any arithmetic operation
7694  within the loop.
7695 \layout Itemize
7696
7697 There are NO switch statements in the loop.
7698 \layout Subsubsection
7699
7700 Algebraic Simplifications
7701 \layout Standard
7702
7703 SDCC does numerous algebraic simplifications, the following is a small sub-set
7704  of these optimizations.
7705 \newline
7706
7707 \newline
7708
7709 \family typewriter
7710 i = j + 0 ; /* changed to */ i = j;
7711 \newline
7712 i /= 2; /* changed to */ i >>= 1;
7713 \newline
7714 i = j - j ; /* changed to */ i = 0;
7715 \newline
7716 i = j / 1 ; /* changed to */ i = j;
7717 \family default
7718
7719 \newline
7720
7721 \newline
7722 Note the subexpressions
7723 \begin_inset LatexCommand \index{subexpressions}
7724
7725 \end_inset
7726
7727  given above are generally introduced by macro expansions or as a result
7728  of copy/constant propagation.
7729 \layout Subsubsection
7730
7731 'switch' Statements
7732 \begin_inset LatexCommand \index{switch Statements}
7733
7734 \end_inset
7735
7736
7737 \layout Standard
7738
7739 SDCC changes switch statements to jump tables
7740 \begin_inset LatexCommand \index{jump tables}
7741
7742 \end_inset
7743
7744  when the following conditions are true.
7745
7746 \layout Itemize
7747
7748 The case labels are in numerical sequence, the labels need not be in order,
7749  and the starting number need not be one or zero.
7750 \newline
7751
7752 \newline
7753
7754 \family typewriter
7755 switch(i) {\SpecialChar ~
7756  \SpecialChar ~
7757  \SpecialChar ~
7758  \SpecialChar ~
7759  \SpecialChar ~
7760  \SpecialChar ~
7761  \SpecialChar ~
7762  \SpecialChar ~
7763  \SpecialChar ~
7764  \SpecialChar ~
7765  \SpecialChar ~
7766  \SpecialChar ~
7767  \SpecialChar ~
7768 switch (i) {
7769 \newline
7770 case 4:...
7771  \SpecialChar ~
7772  \SpecialChar ~
7773  \SpecialChar ~
7774  \SpecialChar ~
7775  \SpecialChar ~
7776  \SpecialChar ~
7777  \SpecialChar ~
7778  \SpecialChar ~
7779  \SpecialChar ~
7780  \SpecialChar ~
7781  \SpecialChar ~
7782  \SpecialChar ~
7783  \SpecialChar ~
7784 case 1: ...
7785
7786 \newline
7787 case 5:...
7788  \SpecialChar ~
7789  \SpecialChar ~
7790  \SpecialChar ~
7791  \SpecialChar ~
7792  \SpecialChar ~
7793  \SpecialChar ~
7794  \SpecialChar ~
7795  \SpecialChar ~
7796  \SpecialChar ~
7797  \SpecialChar ~
7798  \SpecialChar ~
7799  \SpecialChar ~
7800  \SpecialChar ~
7801 case 2: ...
7802
7803 \newline
7804 case 3:...
7805  \SpecialChar ~
7806  \SpecialChar ~
7807  \SpecialChar ~
7808  \SpecialChar ~
7809  \SpecialChar ~
7810  \SpecialChar ~
7811  \SpecialChar ~
7812  \SpecialChar ~
7813  \SpecialChar ~
7814  \SpecialChar ~
7815  \SpecialChar ~
7816  \SpecialChar ~
7817  \SpecialChar ~
7818 case 3: ...
7819
7820 \newline
7821 case 6:...
7822  \SpecialChar ~
7823  \SpecialChar ~
7824  \SpecialChar ~
7825  \SpecialChar ~
7826  \SpecialChar ~
7827  \SpecialChar ~
7828  \SpecialChar ~
7829  \SpecialChar ~
7830  \SpecialChar ~
7831  \SpecialChar ~
7832  \SpecialChar ~
7833  \SpecialChar ~
7834  \SpecialChar ~
7835 case 4: ...
7836
7837 \newline
7838 }\SpecialChar ~
7839  \SpecialChar ~
7840  \SpecialChar ~
7841  \SpecialChar ~
7842  \SpecialChar ~
7843  \SpecialChar ~
7844  \SpecialChar ~
7845  \SpecialChar ~
7846  \SpecialChar ~
7847  \SpecialChar ~
7848  \SpecialChar ~
7849  \SpecialChar ~
7850  \SpecialChar ~
7851  \SpecialChar ~
7852  \SpecialChar ~
7853  \SpecialChar ~
7854  \SpecialChar ~
7855  \SpecialChar ~
7856 }
7857 \newline
7858
7859 \newline
7860
7861 \family default
7862 Both the above switch statements will be implemented using a jump-table.
7863 \layout Itemize
7864
7865 The number of case labels is at least three, since it takes two conditional
7866  statements to handle the boundary conditions.
7867 \layout Itemize
7868
7869 The number of case labels is less than 84, since each label takes 3 bytes
7870  and a jump-table can be utmost 256 bytes long.
7871
7872 \layout Standard
7873
7874 Switch statements which have gaps in the numeric sequence or those that
7875  have more that 84 case labels can be split into more than one switch statement
7876  for efficient code generation, e.g.:
7877 \newline
7878
7879 \newline
7880
7881 \family typewriter
7882 switch (i) {
7883 \newline
7884 case 1: ...
7885
7886 \newline
7887 case 2: ...
7888
7889 \newline
7890 case 3: ...
7891
7892 \newline
7893 case 4: ...
7894
7895 \newline
7896 case 9: ...
7897
7898 \newline
7899 case 10: ...
7900
7901 \newline
7902 case 11: ...
7903
7904 \newline
7905 case 12: ...
7906
7907 \newline
7908 }
7909 \family default
7910
7911 \newline
7912
7913 \newline
7914 If the above switch statement is broken down into two switch statements
7915 \newline
7916
7917 \newline
7918
7919 \family typewriter
7920 switch (i) {
7921 \newline
7922 case 1: ...
7923
7924 \newline
7925 case 2: ...
7926
7927 \newline
7928 case 3: ...
7929
7930 \newline
7931 case 4: ...
7932
7933 \newline
7934 }
7935 \newline
7936
7937 \newline
7938
7939 \family default
7940 and
7941 \family typewriter
7942
7943 \newline
7944
7945 \newline
7946 switch (i) {
7947 \newline
7948 case 9: \SpecialChar ~
7949 ...
7950
7951 \newline
7952 case 10: ...
7953
7954 \newline
7955 case 11: ...
7956
7957 \newline
7958 case 12:\SpecialChar ~
7959 ...
7960
7961 \newline
7962 }
7963 \newline
7964
7965 \newline
7966
7967 \family default
7968 then both the switch statements will be implemented using jump-tables whereas
7969  the unmodified switch statement will not be.
7970 \layout Subsubsection
7971
7972 Bit-shifting Operations
7973 \begin_inset LatexCommand \index{Bit-shifting Operations}
7974
7975 \end_inset
7976
7977 .
7978 \layout Standard
7979
7980 Bit shifting is one of the most frequently used operation in embedded programmin
7981 g.
7982  SDCC tries to implement bit-shift operations in the most efficient way
7983  possible, e.g.:
7984 \newline
7985
7986 \family typewriter
7987
7988 \newline
7989 unsigned char i;
7990 \newline
7991 ...
7992
7993 \newline
7994 i>>= 4;
7995 \newline
7996 ...
7997 \newline
7998
7999 \family default
8000
8001 \newline
8002 generates the following code:
8003 \newline
8004
8005 \family typewriter
8006
8007 \newline
8008 mov a,_i
8009 \newline
8010 swap a
8011 \newline
8012 anl a,#0x0f
8013 \newline
8014 mov _i,a
8015 \family default
8016
8017 \newline
8018
8019 \newline
8020 In general SDCC will never setup a loop if the shift count is known.
8021  Another example:
8022 \newline
8023
8024 \newline
8025
8026 \family typewriter
8027 unsigned int i;
8028 \newline
8029 ...
8030
8031 \newline
8032 i >>= 9;
8033 \newline
8034 ...
8035 \family default
8036
8037 \newline
8038
8039 \newline
8040 will generate:
8041 \newline
8042
8043 \newline
8044
8045 \family typewriter
8046 mov a,(_i + 1)
8047 \newline
8048 mov (_i + 1),#0x00
8049 \newline
8050 clr c
8051 \newline
8052 rrc a
8053 \newline
8054 mov _i,a
8055 \family default
8056
8057 \newline
8058
8059 \newline
8060 Note that SDCC stores numbers in little-endian format (i.e.
8061  lowest order first).
8062 \layout Subsubsection
8063
8064 Bit-rotation
8065 \begin_inset LatexCommand \index{Bit-rotation}
8066
8067 \end_inset
8068
8069
8070 \layout Standard
8071
8072 A special case of the bit-shift operation is bit rotation, SDCC recognizes
8073  the following expression to be a left bit-rotation:
8074 \newline
8075
8076 \newline
8077
8078 \family typewriter
8079 unsigned char i;
8080 \newline
8081 ...
8082
8083 \newline
8084 i = ((i << 1) | (i >> 7));
8085 \family default
8086
8087 \newline
8088 ...
8089 \newline
8090
8091 \newline
8092 will generate the following code:
8093 \newline
8094
8095 \newline
8096
8097 \family typewriter
8098 mov a,_i
8099 \newline
8100 rl a
8101 \newline
8102 mov _i,a
8103 \family default
8104
8105 \newline
8106
8107 \newline
8108 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
8109 ns of this case will also be recognized as bit-rotation, i.e.:
8110 \newline
8111
8112 \newline
8113
8114 \family typewriter
8115 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
8116 \layout Subsubsection
8117
8118 Highest Order Bit
8119 \begin_inset LatexCommand \index{Highest Order Bit}
8120
8121 \end_inset
8122
8123
8124 \layout Standard
8125
8126 It is frequently required to obtain the highest order bit of an integral
8127  type (long, int, short or char types).
8128  SDCC recognizes the following expression to yield the highest order bit
8129  and generates optimized code for it, e.g.:
8130 \newline
8131
8132 \newline
8133
8134 \family typewriter
8135 unsigned int gint;
8136 \newline
8137
8138 \newline
8139 foo () {
8140 \newline
8141 unsigned char hob;
8142 \newline
8143 \SpecialChar ~
8144 \SpecialChar ~
8145 ...
8146
8147 \newline
8148 \SpecialChar ~
8149 \SpecialChar ~
8150 hob = (gint >> 15) & 1;
8151 \newline
8152 \SpecialChar ~
8153 \SpecialChar ~
8154 ..
8155
8156 \newline
8157 }
8158 \family default
8159
8160 \newline
8161
8162 \newline
8163 will generate the following code:
8164 \newline
8165
8166 \family typewriter
8167
8168 \newline
8169 \SpecialChar ~
8170 \SpecialChar ~
8171 \SpecialChar ~
8172 \SpecialChar ~
8173 \SpecialChar ~
8174 \SpecialChar ~
8175 \SpecialChar ~
8176 \SpecialChar ~
8177 \SpecialChar ~
8178 \SpecialChar ~
8179 \SpecialChar ~
8180 \SpecialChar ~
8181 \SpecialChar ~
8182 \SpecialChar ~
8183 \SpecialChar ~
8184 \SpecialChar ~
8185 \SpecialChar ~
8186 \SpecialChar ~
8187 \SpecialChar ~
8188 \SpecialChar ~
8189 \SpecialChar ~
8190 \SpecialChar ~
8191 \SpecialChar ~
8192 \SpecialChar ~
8193 \SpecialChar ~
8194 \SpecialChar ~
8195 \SpecialChar ~
8196 \SpecialChar ~
8197  61 ;\SpecialChar ~
8198  hob.c 7
8199 \newline
8200 \SpecialChar ~
8201 \SpecialChar ~
8202  000A E5*01\SpecialChar ~
8203 \SpecialChar ~
8204 \SpecialChar ~
8205 \SpecialChar ~
8206 \SpecialChar ~
8207 \SpecialChar ~
8208 \SpecialChar ~
8209 \SpecialChar ~
8210 \SpecialChar ~
8211 \SpecialChar ~
8212 \SpecialChar ~
8213 \SpecialChar ~
8214 \SpecialChar ~
8215 \SpecialChar ~
8216 \SpecialChar ~
8217  62\SpecialChar ~
8218 \SpecialChar ~
8219 \SpecialChar ~
8220 \SpecialChar ~
8221 \SpecialChar ~
8222 \SpecialChar ~
8223 \SpecialChar ~
8224 \SpecialChar ~
8225  mov\SpecialChar ~
8226  a,(_gint + 1)
8227 \newline
8228 \SpecialChar ~
8229 \SpecialChar ~
8230  000C 33\SpecialChar ~
8231 \SpecialChar ~
8232 \SpecialChar ~
8233 \SpecialChar ~
8234 \SpecialChar ~
8235 \SpecialChar ~
8236 \SpecialChar ~
8237 \SpecialChar ~
8238 \SpecialChar ~
8239 \SpecialChar ~
8240 \SpecialChar ~
8241 \SpecialChar ~
8242 \SpecialChar ~
8243 \SpecialChar ~
8244 \SpecialChar ~
8245 \SpecialChar ~
8246 \SpecialChar ~
8247 \SpecialChar ~
8248  63\SpecialChar ~
8249 \SpecialChar ~
8250 \SpecialChar ~
8251 \SpecialChar ~
8252 \SpecialChar ~
8253 \SpecialChar ~
8254 \SpecialChar ~
8255 \SpecialChar ~
8256  rlc\SpecialChar ~
8257  a
8258 \newline
8259 \SpecialChar ~
8260 \SpecialChar ~
8261  000D E4\SpecialChar ~
8262 \SpecialChar ~
8263 \SpecialChar ~
8264 \SpecialChar ~
8265 \SpecialChar ~
8266 \SpecialChar ~
8267 \SpecialChar ~
8268 \SpecialChar ~
8269 \SpecialChar ~
8270 \SpecialChar ~
8271 \SpecialChar ~
8272 \SpecialChar ~
8273 \SpecialChar ~
8274 \SpecialChar ~
8275 \SpecialChar ~
8276 \SpecialChar ~
8277 \SpecialChar ~
8278 \SpecialChar ~
8279  64\SpecialChar ~
8280 \SpecialChar ~
8281 \SpecialChar ~
8282 \SpecialChar ~
8283 \SpecialChar ~
8284 \SpecialChar ~
8285 \SpecialChar ~
8286 \SpecialChar ~
8287  clr\SpecialChar ~
8288  a
8289 \newline
8290 \SpecialChar ~
8291 \SpecialChar ~
8292  000E 13\SpecialChar ~
8293 \SpecialChar ~
8294 \SpecialChar ~
8295 \SpecialChar ~
8296 \SpecialChar ~
8297 \SpecialChar ~
8298 \SpecialChar ~
8299 \SpecialChar ~
8300 \SpecialChar ~
8301 \SpecialChar ~
8302 \SpecialChar ~
8303 \SpecialChar ~
8304 \SpecialChar ~
8305 \SpecialChar ~
8306 \SpecialChar ~
8307 \SpecialChar ~
8308 \SpecialChar ~
8309 \SpecialChar ~
8310  65\SpecialChar ~
8311 \SpecialChar ~
8312 \SpecialChar ~
8313 \SpecialChar ~
8314 \SpecialChar ~
8315 \SpecialChar ~
8316 \SpecialChar ~
8317 \SpecialChar ~
8318  rrc\SpecialChar ~
8319  a
8320 \newline
8321 \SpecialChar ~
8322 \SpecialChar ~
8323  000F F5*02\SpecialChar ~
8324 \SpecialChar ~
8325 \SpecialChar ~
8326 \SpecialChar ~
8327 \SpecialChar ~
8328 \SpecialChar ~
8329 \SpecialChar ~
8330 \SpecialChar ~
8331 \SpecialChar ~
8332 \SpecialChar ~
8333 \SpecialChar ~
8334 \SpecialChar ~
8335 \SpecialChar ~
8336 \SpecialChar ~
8337 \SpecialChar ~
8338  66\SpecialChar ~
8339 \SpecialChar ~
8340 \SpecialChar ~
8341 \SpecialChar ~
8342 \SpecialChar ~
8343 \SpecialChar ~
8344 \SpecialChar ~
8345 \SpecialChar ~
8346  mov\SpecialChar ~
8347  _foo_hob_1_1,a
8348 \newline
8349
8350 \newline
8351
8352 \family default
8353 Variations of this case however will
8354 \emph on
8355 not
8356 \emph default
8357  be recognized.
8358  It is a standard C expression, so I heartily recommend this be the only
8359  way to get the highest order bit, (it is portable).
8360  Of course it will be recognized even if it is embedded in other expressions,
8361  e.g.:
8362 \newline
8363
8364 \newline
8365
8366 \family typewriter
8367 xyz = gint + ((gint >> 15) & 1);
8368 \family default
8369
8370 \newline
8371
8372 \newline
8373 will still be recognized.
8374 \layout Subsubsection
8375
8376 Peephole Optimizer
8377 \begin_inset LatexCommand \index{Peephole optimizer}
8378
8379 \end_inset
8380
8381
8382 \layout Standard
8383
8384 The compiler uses a rule based, pattern matching and re-writing mechanism
8385  for peep-hole optimization.
8386  It is inspired by
8387 \emph on
8388 copt
8389 \emph default
8390  a peep-hole optimizer by Christopher W.
8391  Fraser (cwfraser@microsoft.com).
8392  A default set of rules are compiled into the compiler, additional rules
8393  may be added with the
8394 \emph on
8395 ---peep-file
8396 \begin_inset LatexCommand \index{---peep-file}
8397
8398 \end_inset
8399
8400  <filename>
8401 \emph default
8402  option.
8403  The rule language is best illustrated with examples.
8404 \newline
8405
8406 \newline
8407
8408 \family typewriter
8409 replace {
8410 \newline
8411 \SpecialChar ~
8412 \SpecialChar ~
8413 mov %1,a
8414 \newline
8415 \SpecialChar ~
8416 \SpecialChar ~
8417 mov a,%1
8418 \newline
8419 } by {
8420 \newline
8421 \SpecialChar ~
8422 \SpecialChar ~
8423 mov %1,a
8424 \newline
8425 }
8426 \family default
8427
8428 \newline
8429
8430 \newline
8431 The above rule will change the following assembly sequence:
8432 \newline
8433
8434 \newline
8435
8436 \family typewriter
8437 \SpecialChar ~
8438 \SpecialChar ~
8439 mov r1,a
8440 \newline
8441 \SpecialChar ~
8442 \SpecialChar ~
8443 mov a,r1
8444 \family default
8445
8446 \newline
8447
8448 \newline
8449 to
8450 \newline
8451
8452 \newline
8453
8454 \family typewriter
8455 mov r1,a
8456 \family default
8457
8458 \newline
8459
8460 \newline
8461 Note: All occurrences of a
8462 \emph on
8463 %n
8464 \emph default
8465  (pattern variable) must denote the same string.
8466  With the above rule, the assembly sequence:
8467 \newline
8468
8469 \newline
8470
8471 \family typewriter
8472 \SpecialChar ~
8473 \SpecialChar ~
8474 mov r1,a
8475 \newline
8476 \SpecialChar ~
8477 \SpecialChar ~
8478 mov a,r2
8479 \family default
8480
8481 \newline
8482
8483 \newline
8484 will remain unmodified.
8485 \newline
8486
8487 \newline
8488 Other special case optimizations may be added by the user (via
8489 \emph on
8490 ---peep-file option
8491 \emph default
8492 ).
8493  E.g.
8494  some variants of the 8051 MCU allow only
8495 \family typewriter
8496 ajmp
8497 \family default
8498  and
8499 \family typewriter
8500 acall
8501 \family default
8502 .
8503  The following two rules will change all
8504 \family typewriter
8505 ljmp
8506 \family default
8507  and
8508 \family typewriter
8509 lcall
8510 \family default
8511  to
8512 \family typewriter
8513 ajmp
8514 \family default
8515  and
8516 \family typewriter
8517 acall
8518 \family default
8519
8520 \newline
8521
8522 \newline
8523
8524 \family typewriter
8525 replace { lcall %1 } by { acall %1 }
8526 \newline
8527 replace { ljmp %1 } by { ajmp %1 }
8528 \family default
8529
8530 \newline
8531
8532 \newline
8533 The
8534 \emph on
8535 inline-assembler code
8536 \emph default
8537  is also passed through the peep hole optimizer, thus the peephole optimizer
8538  can also be used as an assembly level macro expander.
8539  The rules themselves are MCU dependent whereas the rule language infra-structur
8540 e is MCU independent.
8541  Peephole optimization rules for other MCU can be easily programmed using
8542  the rule language.
8543 \newline
8544
8545 \newline
8546 The syntax for a rule is as follows:
8547 \newline
8548
8549 \newline
8550
8551 \family typewriter
8552 rule := replace [ restart ] '{' <assembly sequence> '
8553 \backslash
8554 n'
8555 \newline
8556 \SpecialChar ~
8557  \SpecialChar ~
8558  \SpecialChar ~
8559  \SpecialChar ~
8560  \SpecialChar ~
8561  \SpecialChar ~
8562  \SpecialChar ~
8563  \SpecialChar ~
8564  \SpecialChar ~
8565  \SpecialChar ~
8566  \SpecialChar ~
8567  \SpecialChar ~
8568  \SpecialChar ~
8569  \SpecialChar ~
8570  '}' by '{' '
8571 \backslash
8572 n'
8573 \newline
8574 \SpecialChar ~
8575  \SpecialChar ~
8576  \SpecialChar ~
8577  \SpecialChar ~
8578  \SpecialChar ~
8579  \SpecialChar ~
8580  \SpecialChar ~
8581  \SpecialChar ~
8582  \SpecialChar ~
8583  \SpecialChar ~
8584  \SpecialChar ~
8585  \SpecialChar ~
8586  \SpecialChar ~
8587  \SpecialChar ~
8588  \SpecialChar ~
8589  \SpecialChar ~
8590  <assembly sequence> '
8591 \backslash
8592 n'
8593 \newline
8594 \SpecialChar ~
8595  \SpecialChar ~
8596  \SpecialChar ~
8597  \SpecialChar ~
8598  \SpecialChar ~
8599  \SpecialChar ~
8600  \SpecialChar ~
8601  \SpecialChar ~
8602  \SpecialChar ~
8603  \SpecialChar ~
8604  \SpecialChar ~
8605  \SpecialChar ~
8606  \SpecialChar ~
8607  \SpecialChar ~
8608  '}' [if <functionName> ] '
8609 \backslash
8610 n'
8611 \newline
8612
8613 \family default
8614
8615 \newline
8616 <assembly sequence> := assembly instruction (each instruction including
8617  labels must be on a separate line).
8618 \newline
8619
8620 \newline
8621 The optimizer will apply to the rules one by one from the top in the sequence
8622  of their appearance, it will terminate when all rules are exhausted.
8623  If the 'restart' option is specified, then the optimizer will start matching
8624  the rules again from the top, this option for a rule is expensive (performance)
8625 , it is intended to be used in situations where a transformation will trigger
8626  the same rule again.
8627  An example of this (not a good one, it has side effects) is the following
8628  rule:
8629 \newline
8630
8631 \newline
8632
8633 \family typewriter
8634 replace restart {
8635 \newline
8636 \SpecialChar ~
8637 \SpecialChar ~
8638 pop %1
8639 \newline
8640 \SpecialChar ~
8641 \SpecialChar ~
8642 push %1 } by {
8643 \newline
8644 \SpecialChar ~
8645 \SpecialChar ~
8646 ; nop
8647 \newline
8648 }
8649 \family default
8650
8651 \newline
8652
8653 \newline
8654 Note that the replace pattern cannot be a blank, but can be a comment line.
8655  Without the 'restart' option only the inner most 'pop' 'push' pair would
8656  be eliminated, i.e.:
8657 \newline
8658
8659 \newline
8660
8661 \family typewriter
8662 \SpecialChar ~
8663 \SpecialChar ~
8664 pop ar1
8665 \newline
8666 \SpecialChar ~
8667 \SpecialChar ~
8668 pop ar2
8669 \newline
8670 \SpecialChar ~
8671 \SpecialChar ~
8672 push ar2
8673 \newline
8674 \SpecialChar ~
8675 \SpecialChar ~
8676 push ar1
8677 \family default
8678
8679 \newline
8680
8681 \newline
8682 would result in:
8683 \newline
8684
8685 \newline
8686
8687 \family typewriter
8688 \SpecialChar ~
8689 \SpecialChar ~
8690 pop ar1
8691 \newline
8692 \SpecialChar ~
8693 \SpecialChar ~
8694 ; nop
8695 \newline
8696 \SpecialChar ~
8697 \SpecialChar ~
8698 push ar1
8699 \family default
8700
8701 \newline
8702
8703 \newline
8704
8705 \emph on
8706 with
8707 \emph default
8708  the restart option the rule will be applied again to the resulting code
8709  and then all the pop-push pairs will be eliminated to yield:
8710 \newline
8711
8712 \newline
8713
8714 \family typewriter
8715 \SpecialChar ~
8716 \SpecialChar ~
8717 ; nop
8718 \newline
8719 \SpecialChar ~
8720 \SpecialChar ~
8721 ; nop
8722 \family default
8723
8724 \newline
8725
8726 \newline
8727 A conditional function can be attached to a rule.
8728  Attaching rules are somewhat more involved, let me illustrate this with
8729  an example.
8730 \newline
8731
8732 \newline
8733
8734 \family typewriter
8735 replace {
8736 \newline
8737 \SpecialChar ~
8738  \SpecialChar ~
8739  \SpecialChar ~
8740 ljmp %5
8741 \newline
8742 %2:
8743 \newline
8744 } by {
8745 \newline
8746 \SpecialChar ~
8747  \SpecialChar ~
8748  \SpecialChar ~
8749 sjmp %5
8750 \newline
8751 %2:
8752 \newline
8753 } if labelInRange
8754 \family default
8755
8756 \newline
8757
8758 \newline
8759 The optimizer does a look-up of a function name table defined in function
8760
8761 \emph on
8762 callFuncByName
8763 \emph default
8764  in the source file SDCCpeeph.c, with the name
8765 \emph on
8766 labelInRange
8767 \emph default
8768 .
8769  If it finds a corresponding entry the function is called.
8770  Note there can be no parameters specified for these functions, in this
8771  case the use of
8772 \emph on
8773 %5
8774 \emph default
8775  is crucial, since the function
8776 \emph on
8777 labelInRange
8778 \emph default
8779  expects to find the label in that particular variable (the hash table containin
8780 g the variable bindings is passed as a parameter).
8781  If you want to code more such functions, take a close look at the function
8782  labelInRange and the calling mechanism in source file SDCCpeeph.c.
8783  I know this whole thing is a little kludgey, but maybe some day we will
8784  have some better means.
8785  If you are looking at this file, you will also see the default rules that
8786  are compiled into the compiler, you can add your own rules in the default
8787  set there if you get tired of specifying the ---peep-file option.
8788 \layout Subsection
8789
8790 Pragmas
8791 \begin_inset LatexCommand \index{Pragmas}
8792
8793 \end_inset
8794
8795
8796 \layout Standard
8797
8798 SDCC supports the following #pragma directives.
8799 \layout Itemize
8800
8801 SAVE
8802 \begin_inset LatexCommand \index{\#pragma SAVE}
8803
8804 \end_inset
8805
8806  - this will save all current options to the SAVE/RESTORE stack.
8807  See RESTORE.
8808 \layout Itemize
8809
8810 RESTORE
8811 \begin_inset LatexCommand \index{\#pragma RESTORE}
8812
8813 \end_inset
8814
8815  - will restore saved options from the last save.
8816  SAVEs & RESTOREs can be nested.
8817  SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
8818  RESTORE pulls current options from the stack.
8819  See SAVE.
8820 \layout Itemize
8821
8822 NOGCSE
8823 \begin_inset LatexCommand \index{\#pragma NOGCSE}
8824
8825 \end_inset
8826
8827  - will stop global subexpression elimination.
8828 \layout Itemize
8829
8830 NOINDUCTION
8831 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
8832
8833 \end_inset
8834
8835  - will stop loop induction optimizations.
8836 \layout Itemize
8837
8838 NOJTBOUND
8839 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
8840
8841 \end_inset
8842
8843  - will not generate code for boundary value checking, when switch statements
8844  are turned into jump-tables.
8845 \layout Itemize
8846
8847 NOOVERLAY
8848 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
8849
8850 \end_inset
8851
8852  - the compiler will not overlay the parameters and local variables of a
8853  function.
8854 \layout Itemize
8855
8856 LESS_PEDANTIC
8857 \begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
8858
8859 \end_inset
8860
8861  - the compiler will not warn you anymore for obvious mistakes, you'r on
8862  your own now ;-(
8863 \layout Itemize
8864
8865 NOLOOPREVERSE
8866 \begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
8867
8868 \end_inset
8869
8870  - Will not do loop reversal optimization
8871 \layout Itemize
8872
8873 EXCLUDE
8874 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
8875
8876 \end_inset
8877
8878  NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
8879  pair of push/pop instruction in ISR function (using interrupt keyword).
8880  The directive should be placed immediately before the ISR function definition
8881  and it affects ALL ISR functions following it.
8882  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
8883 EXCLUDE\SpecialChar ~
8884 none.
8885 \layout Itemize
8886
8887 NOIV
8888 \begin_inset LatexCommand \index{\#pragma NOIV}
8889
8890 \end_inset
8891
8892  - Do not generate interrupt vector table entries for all ISR functions
8893  defined after the pragma.
8894  This is useful in cases where the interrupt vector table must be defined
8895  manually, or when there is a secondary, manually defined interrupt vector
8896  table (e.g.
8897  for the autovector feature of the Cypress EZ-USB FX2).
8898 \layout Itemize
8899
8900 CALLEE-SAVES
8901 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
8902
8903 \end_inset
8904
8905  function1[,function2[,function3...]] - The compiler by default uses a caller
8906  saves convention for register saving across function calls, however this
8907  can cause unneccessary register pushing & popping when calling small functions
8908  from larger functions.
8909  This option can be used to switch off the register saving convention for
8910  the function names specified.
8911  The compiler will not save registers when calling these functions, extra
8912  code need to be manually inserted at the entry & exit for these functions
8913  to save & restore the registers used by these functions, this can SUBSTANTIALLY
8914  reduce code & improve run time performance of the generated code.
8915  In the future the compiler (with interprocedural analysis) may be able
8916  to determine the appropriate scheme to use for each function call.
8917  If ---callee-saves command line option is used, the function names specified
8918  in #pragma\SpecialChar ~
8919 CALLEE-SAVES is appended to the list of functions specified in
8920  the command line.
8921 \layout Standard
8922
8923 The pragma's are intended to be used to turn-off certain optimizations which
8924  might cause the compiler to generate extra stack / data space to store
8925  compiler generated temporary variables.
8926  This usually happens in large functions.
8927  Pragma directives should be used as shown in the following example, they
8928  are used to control options & optimizations for a given function; pragmas
8929  should be placed before and/or after a function, placing pragma's inside
8930  a function body could have unpredictable results.
8931 \newline
8932
8933 \newline
8934
8935 \family typewriter
8936 #pragma SAVE
8937 \begin_inset LatexCommand \index{\#pragma SAVE}
8938
8939 \end_inset
8940
8941  /* save the current settings */
8942 \newline
8943 #pragma NOGCSE
8944 \begin_inset LatexCommand \index{\#pragma NOGCSE}
8945
8946 \end_inset
8947
8948  /* turnoff global subexpression elimination */
8949 \newline
8950 #pragma NOINDUCTION
8951 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
8952
8953 \end_inset
8954
8955  /* turn off induction optimizations */
8956 \newline
8957 int foo ()
8958 \newline
8959 {
8960 \newline
8961 \SpecialChar ~
8962  \SpecialChar ~
8963  ...
8964
8965 \newline
8966 \SpecialChar ~
8967  \SpecialChar ~
8968  /* large code */
8969 \newline
8970 \SpecialChar ~
8971  \SpecialChar ~
8972  ...
8973
8974 \newline
8975 }
8976 \newline
8977 #pragma RESTORE
8978 \begin_inset LatexCommand \index{\#pragma RESTORE}
8979
8980 \end_inset
8981
8982  /* turn the optimizations back on */
8983 \family default
8984
8985 \newline
8986
8987 \newline
8988 The compiler will generate a warning message when extra space is allocated.
8989  It is strongly recommended that the SAVE and RESTORE pragma's be used when
8990  changing options for a function.
8991 \layout Subsection
8992
8993
8994 \emph on
8995 <pending: this is messy and incomplete>
8996 \emph default
8997  Library Routines
8998 \layout Enumerate
8999
9000 Compiler support routines (_gptrget, _mulint etc)
9001 \layout Enumerate
9002
9003 Stdclib functions (puts, printf, strcat etc)
9004 \layout Enumerate
9005
9006 Math functions (sin, pow, sqrt etc)
9007 \layout Subsection
9008
9009 Interfacing with Assembly Routines
9010 \begin_inset LatexCommand \index{Assembly Routines}
9011
9012 \end_inset
9013
9014
9015 \layout Subsubsection
9016
9017 Global Registers used for Parameter Passing
9018 \begin_inset LatexCommand \index{Parameter Passing}
9019
9020 \end_inset
9021
9022
9023 \layout Standard
9024
9025 The compiler always uses the global registers
9026 \emph on
9027 DPL
9028 \begin_inset LatexCommand \index{DPL}
9029
9030 \end_inset
9031
9032 ,DPH
9033 \begin_inset LatexCommand \index{DPH}
9034
9035 \end_inset
9036
9037
9038 \begin_inset LatexCommand \index{DPTR}
9039
9040 \end_inset
9041
9042 ,B
9043 \begin_inset LatexCommand \index{B}
9044
9045 \end_inset
9046
9047
9048 \emph default
9049 and
9050 \emph on
9051  ACC
9052 \begin_inset LatexCommand \index{ACC}
9053
9054 \end_inset
9055
9056
9057 \emph default
9058  to pass the first parameter to a routine.
9059  The second parameter onwards is either allocated on the stack (for reentrant
9060  routines or if ---stack-auto is used) or in the internal / external ram
9061  (depending on the memory model).
9062
9063 \layout Subsubsection
9064
9065 Assembler Routine(non-reentrant)
9066 \begin_inset LatexCommand \index{Assembler Routine(non-reentrant)}
9067
9068 \end_inset
9069
9070
9071 \layout Standard
9072
9073 In the following example the function cfunc calls an assembler routine asm_func,
9074  which takes two parameters.
9075 \newline
9076
9077 \newline
9078
9079 \family typewriter
9080 extern int asm_func(unsigned char, unsigned char);
9081 \newline
9082
9083 \newline
9084 int c_func (unsigned char i, unsigned char j)
9085 \newline
9086 {
9087 \newline
9088 \SpecialChar ~
9089 \SpecialChar ~
9090 \SpecialChar ~
9091 \SpecialChar ~
9092 return asm_func(i,j);
9093 \newline
9094 }
9095 \newline
9096
9097 \newline
9098 int main()
9099 \newline
9100 {
9101 \newline
9102 \SpecialChar ~
9103 \SpecialChar ~
9104 \SpecialChar ~
9105 \SpecialChar ~
9106 return c_func(10,9);
9107 \newline
9108 }
9109 \newline
9110
9111 \newline
9112
9113 \family default
9114 The corresponding assembler function is:
9115 \newline
9116
9117 \newline
9118
9119 \family typewriter
9120 .globl _asm_func_PARM_2
9121 \newline
9122 \SpecialChar ~
9123 \SpecialChar ~
9124 \SpecialChar ~
9125 \SpecialChar ~
9126 \SpecialChar ~
9127 \SpecialChar ~
9128 \SpecialChar ~
9129 \SpecialChar ~
9130 .globl _asm_func
9131 \newline
9132 \SpecialChar ~
9133 \SpecialChar ~
9134 \SpecialChar ~
9135 \SpecialChar ~
9136 \SpecialChar ~
9137 \SpecialChar ~
9138 \SpecialChar ~
9139 \SpecialChar ~
9140 .area OSEG
9141 \newline
9142 _asm_func_PARM_2:
9143 \newline
9144 \SpecialChar ~
9145 \SpecialChar ~
9146 \SpecialChar ~
9147 \SpecialChar ~
9148 \SpecialChar ~
9149 \SpecialChar ~
9150 \SpecialChar ~
9151 \SpecialChar ~
9152 .ds      1
9153 \newline
9154 \SpecialChar ~
9155 \SpecialChar ~
9156 \SpecialChar ~
9157 \SpecialChar ~
9158 \SpecialChar ~
9159 \SpecialChar ~
9160 \SpecialChar ~
9161 \SpecialChar ~
9162 .area CSEG
9163 \newline
9164 _asm_func:
9165 \newline
9166 \SpecialChar ~
9167 \SpecialChar ~
9168 \SpecialChar ~
9169 \SpecialChar ~
9170 \SpecialChar ~
9171 \SpecialChar ~
9172 \SpecialChar ~
9173 \SpecialChar ~
9174 mov     a,dpl
9175 \newline
9176 \SpecialChar ~
9177 \SpecialChar ~
9178 \SpecialChar ~
9179 \SpecialChar ~
9180 \SpecialChar ~
9181 \SpecialChar ~
9182 \SpecialChar ~
9183 \SpecialChar ~
9184 add     a,_asm_func_PARM_2
9185 \newline
9186 \SpecialChar ~
9187 \SpecialChar ~
9188 \SpecialChar ~
9189 \SpecialChar ~
9190 \SpecialChar ~
9191 \SpecialChar ~
9192 \SpecialChar ~
9193 \SpecialChar ~
9194 mov     dpl,a
9195 \newline
9196 \SpecialChar ~
9197 \SpecialChar ~
9198 \SpecialChar ~
9199 \SpecialChar ~
9200 \SpecialChar ~
9201 \SpecialChar ~
9202 \SpecialChar ~
9203 \SpecialChar ~
9204 mov     dpl,#0x00
9205 \newline
9206 \SpecialChar ~
9207 \SpecialChar ~
9208 \SpecialChar ~
9209 \SpecialChar ~
9210 \SpecialChar ~
9211 \SpecialChar ~
9212 \SpecialChar ~
9213 \SpecialChar ~
9214 ret
9215 \newline
9216
9217 \newline
9218
9219 \family default
9220 Note here that the return values are placed in 'dpl' - One byte return value,
9221  'dpl' LSB & 'dph' MSB for two byte values.
9222  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
9223 b' & 'acc' for four byte values.
9224 \layout Standard
9225
9226 The parameter naming convention is _<function_name>_PARM_<n>, where n is
9227  the parameter number starting from 1, and counting from the left.
9228  The first parameter is passed in
9229 \begin_inset Quotes eld
9230 \end_inset
9231
9232 dpl
9233 \begin_inset Quotes erd
9234 \end_inset
9235
9236  for One bye parameter,
9237 \begin_inset Quotes eld
9238 \end_inset
9239
9240 dptr
9241 \begin_inset Quotes erd
9242 \end_inset
9243
9244  if two bytes,
9245 \begin_inset Quotes eld
9246 \end_inset
9247
9248 b,dptr
9249 \begin_inset Quotes erd
9250 \end_inset
9251
9252  for three bytes and
9253 \begin_inset Quotes eld
9254 \end_inset
9255
9256 acc,b,dptr
9257 \begin_inset Quotes erd
9258 \end_inset
9259
9260  for four bytes, the varible name for the second parameter will be _<function_na
9261 me>_PARM_2.
9262 \newline
9263
9264 \newline
9265 Assemble the assembler routine with the following command:
9266 \newline
9267
9268 \newline
9269
9270 \family sans
9271 \series bold
9272 asx8051 -losg asmfunc.asm
9273 \newline
9274
9275 \newline
9276
9277 \family default
9278 \series default
9279 Then compile and link the assembler routine to the C source file with the
9280  following command:
9281 \newline
9282
9283 \newline
9284
9285 \family sans
9286 \series bold
9287 sdcc cfunc.c asmfunc.rel
9288 \layout Subsubsection
9289
9290 Assembler Routine(reentrant)
9291 \begin_inset LatexCommand \index{Assembler Routine(reentrant)}
9292
9293 \end_inset
9294
9295
9296 \layout Standard
9297
9298 In this case the second parameter onwards will be passed on the stack, the
9299  parameters are pushed from right to left i.e.
9300  after the call the left most parameter will be on the top of the stack.
9301  Here is an example:
9302 \newline
9303
9304 \newline
9305
9306 \family typewriter
9307 extern int asm_func(unsigned char, unsigned char);
9308 \newline
9309
9310 \newline
9311 int c_func (unsigned char i, unsigned char j) reentrant
9312 \newline
9313 {
9314 \newline
9315 \SpecialChar ~
9316 \SpecialChar ~
9317 \SpecialChar ~
9318 \SpecialChar ~
9319 return asm_func(i,j);
9320 \newline
9321 }
9322 \newline
9323
9324 \newline
9325 int main()
9326 \newline
9327 {
9328 \newline
9329 \SpecialChar ~
9330 \SpecialChar ~
9331 \SpecialChar ~
9332 \SpecialChar ~
9333 return c_func(10,9);
9334 \newline
9335 }
9336 \newline
9337
9338 \family default
9339
9340 \newline
9341 The corresponding assembler routine is:
9342 \newline
9343
9344 \newline
9345
9346 \family typewriter
9347 .globl _asm_func
9348 \newline
9349 _asm_func:
9350 \newline
9351 \SpecialChar ~
9352 \SpecialChar ~
9353 \SpecialChar ~
9354 \SpecialChar ~
9355 push  _bp
9356 \newline
9357 \SpecialChar ~
9358 \SpecialChar ~
9359 \SpecialChar ~
9360 \SpecialChar ~
9361 mov _bp,sp
9362 \newline
9363 \SpecialChar ~
9364 \SpecialChar ~
9365 \SpecialChar ~
9366 \SpecialChar ~
9367 mov  r2,dpl
9368 \newline
9369 \SpecialChar ~
9370 \SpecialChar ~
9371 \SpecialChar ~
9372 \SpecialChar ~
9373 mov  a,_bp
9374 \newline
9375 \SpecialChar ~
9376 \SpecialChar ~
9377 \SpecialChar ~
9378 \SpecialChar ~
9379 clr  c
9380 \newline
9381 \SpecialChar ~
9382 \SpecialChar ~
9383 \SpecialChar ~
9384 \SpecialChar ~
9385 add  a,#0xfd
9386 \newline
9387 \SpecialChar ~
9388 \SpecialChar ~
9389 \SpecialChar ~
9390 \SpecialChar ~
9391 mov  r0,a
9392 \newline
9393 \SpecialChar ~
9394 \SpecialChar ~
9395 \SpecialChar ~
9396 \SpecialChar ~
9397 add  a,#0xfc
9398 \newline
9399 \SpecialChar ~
9400 \SpecialChar ~
9401 \SpecialChar ~
9402 \SpecialChar ~
9403 mov  r1,a
9404 \newline
9405 \SpecialChar ~
9406 \SpecialChar ~
9407 \SpecialChar ~
9408 \SpecialChar ~
9409 mov  a,@r0
9410 \newline
9411 \SpecialChar ~
9412 \SpecialChar ~
9413 \SpecialChar ~
9414 \SpecialChar ~
9415 add  a,r2
9416 \newline
9417 \SpecialChar ~
9418 \SpecialChar ~
9419 \SpecialChar ~
9420 \SpecialChar ~
9421 mov  dpl,a
9422 \newline
9423 \SpecialChar ~
9424 \SpecialChar ~
9425 \SpecialChar ~
9426 \SpecialChar ~
9427 mov  dph,#0x00
9428 \newline
9429 \SpecialChar ~
9430 \SpecialChar ~
9431 \SpecialChar ~
9432 \SpecialChar ~
9433 mov  sp,_bp
9434 \newline
9435 \SpecialChar ~
9436 \SpecialChar ~
9437 \SpecialChar ~
9438 \SpecialChar ~
9439 pop  _bp
9440 \newline
9441 \SpecialChar ~
9442 \SpecialChar ~
9443 \SpecialChar ~
9444 \SpecialChar ~
9445 ret
9446 \newline
9447
9448 \newline
9449
9450 \family default
9451 The compiling and linking procedure remains the same, however note the extra
9452  entry & exit linkage required for the assembler code, _bp is the stack
9453  frame pointer and is used to compute the offset into the stack for parameters
9454  and local variables.
9455 \layout Subsection
9456
9457 External Stack
9458 \begin_inset LatexCommand \index{External Stack}
9459
9460 \end_inset
9461
9462
9463 \layout Standard
9464
9465 The external stack is located at the start of the external ram segment,
9466  and is 256 bytes in size.
9467  When ---xstack option is used to compile the program, the parameters and
9468  local variables of all reentrant functions are allocated in this area.
9469  This option is provided for programs with large stack space requirements.
9470  When used with the ---stack-auto option, all parameters and local variables
9471  are allocated on the external stack (note support libraries will need to
9472  be recompiled with the same options).
9473 \layout Standard
9474
9475 The compiler outputs the higher order address byte of the external ram segment
9476  into PORT P2, therefore when using the External Stack option, this port
9477  MAY NOT be used by the application program.
9478 \layout Subsection
9479
9480 ANSI-Compliance
9481 \begin_inset LatexCommand \index{ANSI-Compliance}
9482
9483 \end_inset
9484
9485
9486 \layout Standard
9487
9488 Deviations from the compliancy.
9489 \layout Itemize
9490
9491 functions are not always reentrant.
9492 \layout Itemize
9493
9494 structures cannot be assigned values directly, cannot be passed as function
9495  parameters or assigned to each other and cannot be a return value from
9496  a function, e.g.:
9497 \family typewriter
9498
9499 \newline
9500
9501 \newline
9502 struct s { ...
9503  };
9504 \newline
9505 struct s s1, s2;
9506 \newline
9507 foo()
9508 \newline
9509 {
9510 \newline
9511 \SpecialChar ~
9512 \SpecialChar ~
9513 \SpecialChar ~
9514 \SpecialChar ~
9515 ...
9516
9517 \newline
9518 \SpecialChar ~
9519 \SpecialChar ~
9520 \SpecialChar ~
9521 \SpecialChar ~
9522 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
9523 \newline
9524 \SpecialChar ~
9525 \SpecialChar ~
9526 \SpecialChar ~
9527 \SpecialChar ~
9528 ...
9529
9530 \newline
9531 }
9532 \newline
9533 struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
9534  ANSI */
9535 \newline
9536 {
9537 \newline
9538 \SpecialChar ~
9539 \SpecialChar ~
9540 \SpecialChar ~
9541 \SpecialChar ~
9542 struct s rets;
9543 \newline
9544 \SpecialChar ~
9545 \SpecialChar ~
9546 \SpecialChar ~
9547 \SpecialChar ~
9548 ...
9549
9550 \newline
9551 \SpecialChar ~
9552 \SpecialChar ~
9553 \SpecialChar ~
9554 \SpecialChar ~
9555 return rets;/* is invalid in SDCC although allowed in ANSI */
9556 \newline
9557 }
9558 \layout Itemize
9559
9560 'long long' (64 bit integers) not supported.
9561 \layout Itemize
9562
9563 'double' precision floating point not supported.
9564 \layout Itemize
9565
9566 No support for setjmp and longjmp (for now).
9567 \layout Itemize
9568
9569 Old K&R style function declarations are NOT allowed.
9570 \newline
9571
9572 \family typewriter
9573
9574 \newline
9575 foo(i,j) /* this old style of function declarations */
9576 \newline
9577 int i,j; /* are valid in ANSI but not valid in SDCC */
9578 \newline
9579 {
9580 \newline
9581 \SpecialChar ~
9582 \SpecialChar ~
9583 \SpecialChar ~
9584 \SpecialChar ~
9585 ...
9586
9587 \newline
9588 }
9589 \layout Itemize
9590
9591 functions declared as pointers must be dereferenced during the call.
9592 \newline
9593
9594 \family typewriter
9595
9596 \newline
9597 int (*foo)();
9598 \newline
9599 ...
9600
9601 \newline
9602 /* has to be called like this */
9603 \newline
9604 (*foo)(); /* ansi standard allows calls to be made like 'foo()' */
9605 \layout Subsection
9606
9607 Cyclomatic Complexity
9608 \begin_inset LatexCommand \index{Cyclomatic Complexity}
9609
9610 \end_inset
9611
9612
9613 \layout Standard
9614
9615 Cyclomatic complexity of a function is defined as the number of independent
9616  paths the program can take during execution of the function.
9617  This is an important number since it defines the number test cases you
9618  have to generate to validate the function.
9619  The accepted industry standard for complexity number is 10, if the cyclomatic
9620  complexity reported by SDCC exceeds 10 you should think about simplification
9621  of the function logic.
9622  Note that the complexity level is not related to the number of lines of
9623  code in a function.
9624  Large functions can have low complexity, and small functions can have large
9625  complexity levels.
9626
9627 \newline
9628
9629 \newline
9630 SDCC uses the following formula to compute the complexity:
9631 \newline
9632
9633 \layout Standard
9634
9635 complexity = (number of edges in control flow graph) - (number of nodes
9636  in control flow graph) + 2;
9637 \newline
9638
9639 \newline
9640 Having said that the industry standard is 10, you should be aware that in
9641  some cases it be may unavoidable to have a complexity level of less than
9642  10.
9643  For example if you have switch statement with more than 10 case labels,
9644  each case label adds one to the complexity level.
9645  The complexity level is by no means an absolute measure of the algorithmic
9646  complexity of the function, it does however provide a good starting point
9647  for which functions you might look at for further optimization.
9648 \layout Section
9649
9650 TIPS
9651 \layout Standard
9652
9653 Here are a few guidelines that will help the compiler generate more efficient
9654  code, some of the tips are specific to this compiler others are generally
9655  good programming practice.
9656 \layout Itemize
9657
9658 Use the smallest data type to represent your data-value.
9659  If it is known in advance that the value is going to be less than 256 then
9660  use an 'unsigned char' instead of a 'short' or 'int'.
9661 \layout Itemize
9662
9663 Use unsigned when it is known in advance that the value is not going to
9664  be negative.
9665  This helps especially if you are doing division or multiplication.
9666 \layout Itemize
9667
9668 NEVER jump into a LOOP.
9669 \layout Itemize
9670
9671 Declare the variables to be local whenever possible, especially loop control
9672  variables (induction).
9673 \layout Itemize
9674
9675 Since the compiler does not always do implicit integral promotion, the programme
9676 r should do an explicit cast when integral promotion is required.
9677 \layout Itemize
9678
9679 Reducing the size of division, multiplication & modulus operations can reduce
9680  code size substantially.
9681  Take the following code for example.
9682 \family typewriter
9683
9684 \newline
9685
9686 \newline
9687 foobar(unsigned int p1, unsigned char ch)
9688 \newline
9689 {
9690 \newline
9691     unsigned char ch1 = p1 % ch ;
9692 \newline
9693     ....
9694
9695 \newline
9696 }
9697 \newline
9698
9699 \family default
9700
9701 \newline
9702 For the modulus operation the variable ch will be promoted to unsigned int
9703  first then the modulus operation will be performed (this will lead to a
9704  call to support routine _moduint()), and the result will be casted to a
9705  char.
9706  If the code is changed to
9707 \newline
9708
9709 \family typewriter
9710
9711 \newline
9712 foobar(unsigned int p1, unsigned char ch)
9713 \newline
9714 {
9715 \newline
9716     unsigned char ch1 = (unsigned char)p1 % ch ;
9717 \newline
9718     ....
9719
9720 \newline
9721 }
9722 \newline
9723
9724 \family default
9725
9726 \newline
9727 It would substantially reduce the code generated (future versions of the
9728  compiler will be smart enough to detect such optimization oppurtunities).
9729 \layout Subsection
9730
9731 Notes on MCS51 memory
9732 \begin_inset LatexCommand \index{MCS51 memory}
9733
9734 \end_inset
9735
9736  layout
9737 \layout Standard
9738
9739 The 8051 family of micro controller have a minimum of 128 bytes of internal
9740  memory which is structured as follows
9741 \newline
9742
9743 \newline
9744 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
9745
9746 \newline
9747 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
9748 \newline
9749 - Bytes 30-7F - 60 bytes for general purpose use.
9750 \newline
9751
9752 \newline
9753 Normally the SDCC compiler will only utilise the first bank
9754 \begin_inset LatexCommand \index{bank}
9755
9756 \end_inset
9757
9758  of registers, but it is possible to specify that other banks of registers
9759  should be used in interrupt
9760 \begin_inset LatexCommand \index{interrupt}
9761
9762 \end_inset
9763
9764  routines.
9765  By default, the compiler will place the stack after the last bank of used
9766  registers, i.e.
9767  if the first 2 banks of registers are used, it will position the base of
9768  the internal stack at address 16 (0X10).
9769  This implies that as the stack
9770 \begin_inset LatexCommand \index{stack}
9771
9772 \end_inset
9773
9774  grows, it will use up the remaining register banks, and the 16 bytes used
9775  by the 128 bit variables, and 60 bytes for general purpose use.
9776 \layout Standard
9777
9778 By default, the compiler uses the 60 general purpose bytes to hold "near
9779  data".
9780  The compiler/optimiser may also declare some Local Variables in this area
9781  to hold local data.
9782
9783 \layout Standard
9784
9785 If any of the 128 bit variables are used, or near data is being used then
9786  care needs to be taken to ensure that the stack does not grow so much that
9787  it starts to over write either your bit variables or "near data".
9788  There is no runtime checking to prevent this from happening.
9789 \layout Standard
9790
9791 The amount of stack being used is affected by the use of the "internal stack"
9792  to save registers before a subroutine call is made (---stack-auto
9793 \begin_inset LatexCommand \index{---stack-auto}
9794
9795 \end_inset
9796
9797  will declare parameters and local variables on the stack) and the number
9798  of nested subroutines.
9799 \layout Standard
9800
9801 If you detect that the stack is over writing you data, then the following
9802  can be done.
9803  ---xstack will cause an external stack to be used for saving registers
9804  and (if ---stack-auto is being used) storing parameters and local variables.
9805  However this will produce more code which will be slower to execute.
9806
9807 \layout Standard
9808
9809 ---stack-loc
9810 \begin_inset LatexCommand \index{---stack-loc}
9811
9812 \end_inset
9813
9814  will allow you specify the start of the stack, i.e.
9815  you could start it after any data in the general purpose area.
9816  However this may waste the memory not used by the register banks and if
9817  the size of the "near data" increases, it may creep into the bottom of
9818  the stack.
9819 \layout Standard
9820
9821 ---stack-after-data
9822 \begin_inset LatexCommand \index{---stack-after-data}
9823
9824 \end_inset
9825
9826 , similar to the ---stack-loc, but it automatically places the stack after
9827  the end of the "near data".
9828  Again this could waste any spare register space.
9829 \layout Standard
9830
9831 ---data-loc
9832 \begin_inset LatexCommand \index{---data-loc}
9833
9834 \end_inset
9835
9836  allows you to specify the start address of the near data.
9837  This could be used to move the "near data" further away from the stack
9838  giving it more room to grow.
9839  This will only work if no bit variables are being used and the stack can
9840  grow to use the bit variable space.
9841 \newline
9842
9843 \newline
9844 Conclusion.
9845 \newline
9846
9847 \newline
9848 If you find that the stack is over writing your bit variables or "near data"
9849  then the approach which best utilised the internal memory is to position
9850  the "near data" after the last bank of used registers or, if you use bit
9851  variables, after the last bit variable by using the ---data-loc, e.g.
9852  if two register banks are being used and no bit variables, ---data-loc
9853  16, and use the ---stack-after-data option.
9854 \layout Standard
9855
9856 If bit variables are being used, another method would be to try and squeeze
9857  the data area in the unused register banks if it will fit, and start the
9858  stack after the last bit variable.
9859 \layout Section
9860
9861 Retargetting for other MCUs.
9862 \layout Standard
9863
9864 The issues for retargetting the compiler are far too numerous to be covered
9865  by this document.
9866  What follows is a brief description of each of the seven phases of the
9867  compiler and its MCU dependency.
9868 \layout Itemize
9869
9870 Parsing the source and building the annotated parse tree.
9871  This phase is largely MCU independent (except for the language extensions).
9872  Syntax & semantic checks are also done in this phase, along with some initial
9873  optimizations like back patching labels and the pattern matching optimizations
9874  like bit-rotation etc.
9875 \layout Itemize
9876
9877 The second phase involves generating an intermediate code which can be easy
9878  manipulated during the later phases.
9879  This phase is entirely MCU independent.
9880  The intermediate code generation assumes the target machine has unlimited
9881  number of registers, and designates them with the name iTemp.
9882  The compiler can be made to dump a human readable form of the code generated
9883  by using the ---dumpraw option.
9884 \layout Itemize
9885
9886 This phase does the bulk of the standard optimizations and is also MCU independe
9887 nt.
9888  This phase can be broken down into several sub-phases:
9889 \newline
9890
9891 \newline
9892 Break down intermediate code (iCode) into basic blocks.
9893 \newline
9894 Do control flow & data flow analysis on the basic blocks.
9895 \newline
9896 Do local common subexpression elimination, then global subexpression elimination
9897 \newline
9898 Dead code elimination
9899 \newline
9900 Loop optimizations
9901 \newline
9902 If loop optimizations caused any changes then do 'global subexpression eliminati
9903 on' and 'dead code elimination' again.
9904 \layout Itemize
9905
9906 This phase determines the live-ranges; by live range I mean those iTemp
9907  variables defined by the compiler that still survive after all the optimization
9908 s.
9909  Live range analysis is essential for register allocation, since these computati
9910 on determines which of these iTemps will be assigned to registers, and for
9911  how long.
9912 \layout Itemize
9913
9914 Phase five is register allocation.
9915  There are two parts to this process.
9916 \newline
9917
9918 \newline
9919 The first part I call 'register packing' (for lack of a better term).
9920  In this case several MCU specific expression folding is done to reduce
9921  register pressure.
9922 \newline
9923
9924 \newline
9925 The second part is more MCU independent and deals with allocating registers
9926  to the remaining live ranges.
9927  A lot of MCU specific code does creep into this phase because of the limited
9928  number of index registers available in the 8051.
9929 \layout Itemize
9930
9931 The Code generation phase is (unhappily), entirely MCU dependent and very
9932  little (if any at all) of this code can be reused for other MCU.
9933  However the scheme for allocating a homogenized assembler operand for each
9934  iCode operand may be reused.
9935 \layout Itemize
9936
9937 As mentioned in the optimization section the peep-hole optimizer is rule
9938  based system, which can reprogrammed for other MCUs.
9939 \layout Section
9940 \pagebreak_top
9941 SDCDB
9942 \begin_inset LatexCommand \index{SDCDB}
9943
9944 \end_inset
9945
9946  - Source Level Debugger
9947 \begin_inset LatexCommand \index{Debugger}
9948
9949 \end_inset
9950
9951
9952 \layout Standard
9953
9954 SDCC is distributed with a source level debugger.
9955  The debugger uses a command line interface, the command repertoire of the
9956  debugger has been kept as close to gdb (the GNU debugger) as possible.
9957  The configuration and build process is part of the standard compiler installati
9958 on, which also builds and installs the debugger in the target directory
9959  specified during configuration.
9960  The debugger allows you debug BOTH at the C source and at the ASM source
9961  level.
9962 \layout Subsection
9963
9964 Compiling for Debugging
9965 \layout Standard
9966
9967 The \SpecialChar \-
9968 \SpecialChar \-
9969 debug option must be specified for all files for which debug information
9970  is to be generated.
9971  The complier generates a .adb file for each of these files.
9972  The linker creates the .cdb file from the .adb files and the address information.
9973  This .cdb is used by the debugger.
9974 \layout Subsection
9975
9976 How the Debugger Works
9977 \layout Standard
9978
9979 When the ---debug option is specified the compiler generates extra symbol
9980  information some of which are put into the the assembler source and some
9981  are put into the .adb file.
9982   Then the linker creates the .cdb file from the individual .adb files with
9983  the address information for the symbols.
9984  The debugger reads the symbolic information generated by the compiler &
9985  the address information generated by the linker.
9986  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
9987  execution is controlled by the debugger.
9988  When a command is issued for the debugger, it translates it into appropriate
9989  commands for the simulator.
9990 \layout Subsection
9991
9992 Starting the Debugger
9993 \layout Standard
9994
9995 The debugger can be started using the following command line.
9996  (Assume the file you are debugging has the file name foo).
9997 \newline
9998
9999 \newline
10000
10001 \family sans
10002 \series bold
10003 sdcdb foo
10004 \newline
10005
10006 \family default
10007 \series default
10008
10009 \newline
10010 The debugger will look for the following files.
10011 \layout Itemize
10012
10013 foo.c - the source file.
10014 \layout Itemize
10015
10016 foo.cdb - the debugger symbol information file.
10017 \layout Itemize
10018
10019 foo.ihx - the intel hex format object file.
10020 \layout Subsection
10021
10022 Command Line Options.
10023 \layout Itemize
10024
10025 ---directory=<source file directory> this option can used to specify the
10026  directory search list.
10027  The debugger will look into the directory list specified for source, cdb
10028  & ihx files.
10029  The items in the directory list must be separated by ':', e.g.
10030  if the source files can be in the directories /home/src1 and /home/src2,
10031  the ---directory option should be ---directory=/home/src1:/home/src2.
10032  Note there can be no spaces in the option.
10033
10034 \layout Itemize
10035
10036 -cd <directory> - change to the <directory>.
10037 \layout Itemize
10038
10039 -fullname - used by GUI front ends.
10040 \layout Itemize
10041
10042 -cpu <cpu-type> - this argument is passed to the simulator please see the
10043  simulator docs for details.
10044 \layout Itemize
10045
10046 -X <Clock frequency > this options is passed to the simulator please see
10047  the simulator docs for details.
10048 \layout Itemize
10049
10050 -s <serial port file> passed to simulator see the simulator docs for details.
10051 \layout Itemize
10052
10053 -S <serial in,out> passed to simulator see the simulator docs for details.
10054 \layout Subsection
10055
10056 Debugger Commands.
10057 \layout Standard
10058
10059 As mention earlier the command interface for the debugger has been deliberately
10060  kept as close the GNU debugger gdb, as possible.
10061  This will help the integration with existing graphical user interfaces
10062  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
10063 \layout Subsubsection
10064
10065 break [line | file:line | function | file:function]
10066 \layout Standard
10067
10068 Set breakpoint at specified line or function:
10069 \newline
10070
10071 \newline
10072
10073 \family sans
10074 \series bold
10075 sdcdb>break 100
10076 \newline
10077 sdcdb>break foo.c:100
10078 \newline
10079 sdcdb>break funcfoo
10080 \newline
10081 sdcdb>break foo.c:funcfoo
10082 \layout Subsubsection
10083
10084 clear [line | file:line | function | file:function ]
10085 \layout Standard
10086
10087 Clear breakpoint at specified line or function:
10088 \newline
10089
10090 \newline
10091
10092 \family sans
10093 \series bold
10094 sdcdb>clear 100
10095 \newline
10096 sdcdb>clear foo.c:100
10097 \newline
10098 sdcdb>clear funcfoo
10099 \newline
10100 sdcdb>clear foo.c:funcfoo
10101 \layout Subsubsection
10102
10103 continue
10104 \layout Standard
10105
10106 Continue program being debugged, after breakpoint.
10107 \layout Subsubsection
10108
10109 finish
10110 \layout Standard
10111
10112 Execute till the end of the current function.
10113 \layout Subsubsection
10114
10115 delete [n]
10116 \layout Standard
10117
10118 Delete breakpoint number 'n'.
10119  If used without any option clear ALL user defined break points.
10120 \layout Subsubsection
10121
10122 info [break | stack | frame | registers ]
10123 \layout Itemize
10124
10125 info break - list all breakpoints
10126 \layout Itemize
10127
10128 info stack - show the function call stack.
10129 \layout Itemize
10130
10131 info frame - show information about the current execution frame.
10132 \layout Itemize
10133
10134 info registers - show content of all registers.
10135 \layout Subsubsection
10136
10137 step
10138 \layout Standard
10139
10140 Step program until it reaches a different source line.
10141 \layout Subsubsection
10142
10143 next
10144 \layout Standard
10145
10146 Step program, proceeding through subroutine calls.
10147 \layout Subsubsection
10148
10149 run
10150 \layout Standard
10151
10152 Start debugged program.
10153 \layout Subsubsection
10154
10155 ptype variable
10156 \layout Standard
10157
10158 Print type information of the variable.
10159 \layout Subsubsection
10160
10161 print variable
10162 \layout Standard
10163
10164 print value of variable.
10165 \layout Subsubsection
10166
10167 file filename
10168 \layout Standard
10169
10170 load the given file name.
10171  Note this is an alternate method of loading file for debugging.
10172 \layout Subsubsection
10173
10174 frame
10175 \layout Standard
10176
10177 print information about current frame.
10178 \layout Subsubsection
10179
10180 set srcmode
10181 \layout Standard
10182
10183 Toggle between C source & assembly source.
10184 \layout Subsubsection
10185
10186 ! simulator command
10187 \layout Standard
10188
10189 Send the string following '!' to the simulator, the simulator response is
10190  displayed.
10191  Note the debugger does not interpret the command being sent to the simulator,
10192  so if a command like 'go' is sent the debugger can loose its execution
10193  context and may display incorrect values.
10194 \layout Subsubsection
10195
10196 quit.
10197 \layout Standard
10198
10199 "Watch me now.
10200  Iam going Down.
10201  My name is Bobby Brown"
10202 \layout Subsection
10203
10204 Interfacing with XEmacs
10205 \begin_inset LatexCommand \index{XEmacs}
10206
10207 \end_inset
10208
10209
10210 \begin_inset LatexCommand \index{Emacs}
10211
10212 \end_inset
10213
10214 .
10215 \layout Standard
10216
10217 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
10218  sdcdb.el and sdcdbsrc.el.
10219  These two files can be found in the $(prefix)/bin directory after the installat
10220 ion is complete.
10221  These files need to be loaded into XEmacs for the interface to work.
10222  This can be done at XEmacs startup time by inserting the following into
10223  your '.xemacs' file (which can be found in your HOME directory):
10224 \newline
10225
10226 \newline
10227
10228 \family typewriter
10229 (load-file sdcdbsrc.el)
10230 \family default
10231
10232 \newline
10233
10234 \newline
10235 .xemacs is a lisp file so the () around the command is REQUIRED.
10236  The files can also be loaded dynamically while XEmacs is running, set the
10237  environment variable 'EMACSLOADPATH' to the installation bin directory
10238  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
10239  To start the interface enter the following command:
10240 \newline
10241
10242 \newline
10243
10244 \family sans
10245 \series bold
10246 ESC-x sdcdbsrc
10247 \family default
10248 \series default
10249
10250 \newline
10251
10252 \newline
10253 You will prompted to enter the file name to be debugged.
10254
10255 \newline
10256
10257 \newline
10258 The command line options that are passed to the simulator directly are bound
10259  to default values in the file sdcdbsrc.el.
10260  The variables are listed below, these values maybe changed as required.
10261 \layout Itemize
10262
10263 sdcdbsrc-cpu-type '51
10264 \layout Itemize
10265
10266 sdcdbsrc-frequency '11059200
10267 \layout Itemize
10268
10269 sdcdbsrc-serial nil
10270 \layout Standard
10271
10272 The following is a list of key mapping for the debugger interface.
10273 \layout Standard
10274
10275 \SpecialChar ~
10276
10277 \family typewriter
10278
10279 \newline
10280 ;; Current Listing ::
10281 \newline
10282 ;;key\SpecialChar ~
10283 \SpecialChar ~
10284 \SpecialChar ~
10285 \SpecialChar ~
10286 \SpecialChar ~
10287 \SpecialChar ~
10288 \SpecialChar ~
10289 \SpecialChar ~
10290 \SpecialChar ~
10291 \SpecialChar ~
10292 \SpecialChar ~
10293 \SpecialChar ~
10294 \SpecialChar ~
10295 \SpecialChar ~
10296 \SpecialChar ~
10297 binding\SpecialChar ~
10298 \SpecialChar ~
10299 \SpecialChar ~
10300 \SpecialChar ~
10301 \SpecialChar ~
10302 \SpecialChar ~
10303 \SpecialChar ~
10304 \SpecialChar ~
10305 \SpecialChar ~
10306 \SpecialChar ~
10307 \SpecialChar ~
10308 \SpecialChar ~
10309 \SpecialChar ~
10310 \SpecialChar ~
10311 \SpecialChar ~
10312 \SpecialChar ~
10313 \SpecialChar ~
10314 \SpecialChar ~
10315 \SpecialChar ~
10316 \SpecialChar ~
10317 \SpecialChar ~
10318 \SpecialChar ~
10319 Comment
10320 \newline
10321 ;;---\SpecialChar ~
10322 \SpecialChar ~
10323 \SpecialChar ~
10324 \SpecialChar ~
10325 \SpecialChar ~
10326 \SpecialChar ~
10327 \SpecialChar ~
10328 \SpecialChar ~
10329 \SpecialChar ~
10330 \SpecialChar ~
10331 \SpecialChar ~
10332 \SpecialChar ~
10333 \SpecialChar ~
10334 \SpecialChar ~
10335 \SpecialChar ~
10336 ------\SpecialChar ~
10337 \SpecialChar ~
10338 \SpecialChar ~
10339 \SpecialChar ~
10340 \SpecialChar ~
10341 \SpecialChar ~
10342 \SpecialChar ~
10343 \SpecialChar ~
10344 \SpecialChar ~
10345 \SpecialChar ~
10346 \SpecialChar ~
10347 \SpecialChar ~
10348 \SpecialChar ~
10349 \SpecialChar ~
10350 \SpecialChar ~
10351 \SpecialChar ~
10352 \SpecialChar ~
10353 \SpecialChar ~
10354 \SpecialChar ~
10355 \SpecialChar ~
10356 \SpecialChar ~
10357 \SpecialChar ~
10358 --------
10359 \newline
10360 ;;
10361 \newline
10362 ;; n\SpecialChar ~
10363 \SpecialChar ~
10364 \SpecialChar ~
10365 \SpecialChar ~
10366 \SpecialChar ~
10367 \SpecialChar ~
10368 \SpecialChar ~
10369 \SpecialChar ~
10370 \SpecialChar ~
10371 \SpecialChar ~
10372 \SpecialChar ~
10373 \SpecialChar ~
10374 \SpecialChar ~
10375 \SpecialChar ~
10376  sdcdb-next-from-src\SpecialChar ~
10377 \SpecialChar ~
10378 \SpecialChar ~
10379 \SpecialChar ~
10380 \SpecialChar ~
10381 \SpecialChar ~
10382 \SpecialChar ~
10383 \SpecialChar ~
10384 \SpecialChar ~
10385 \SpecialChar ~
10386 SDCDB next command
10387 \newline
10388 ;; b\SpecialChar ~
10389 \SpecialChar ~
10390 \SpecialChar ~
10391 \SpecialChar ~
10392 \SpecialChar ~
10393 \SpecialChar ~
10394 \SpecialChar ~
10395 \SpecialChar ~
10396 \SpecialChar ~
10397 \SpecialChar ~
10398 \SpecialChar ~
10399 \SpecialChar ~
10400 \SpecialChar ~
10401 \SpecialChar ~
10402  sdcdb-back-from-src\SpecialChar ~
10403 \SpecialChar ~
10404 \SpecialChar ~
10405 \SpecialChar ~
10406 \SpecialChar ~
10407 \SpecialChar ~
10408 \SpecialChar ~
10409 \SpecialChar ~
10410 \SpecialChar ~
10411 \SpecialChar ~
10412 SDCDB back command
10413 \newline
10414 ;; c\SpecialChar ~
10415 \SpecialChar ~
10416 \SpecialChar ~
10417 \SpecialChar ~
10418 \SpecialChar ~
10419 \SpecialChar ~
10420 \SpecialChar ~
10421 \SpecialChar ~
10422 \SpecialChar ~
10423 \SpecialChar ~
10424 \SpecialChar ~
10425 \SpecialChar ~
10426 \SpecialChar ~
10427 \SpecialChar ~
10428  sdcdb-cont-from-src\SpecialChar ~
10429 \SpecialChar ~
10430 \SpecialChar ~
10431 \SpecialChar ~
10432 \SpecialChar ~
10433 \SpecialChar ~
10434 \SpecialChar ~
10435 \SpecialChar ~
10436 \SpecialChar ~
10437 \SpecialChar ~
10438 SDCDB continue command
10439 \newline
10440 ;; s\SpecialChar ~
10441 \SpecialChar ~
10442 \SpecialChar ~
10443 \SpecialChar ~
10444 \SpecialChar ~
10445 \SpecialChar ~
10446 \SpecialChar ~
10447 \SpecialChar ~
10448 \SpecialChar ~
10449 \SpecialChar ~
10450 \SpecialChar ~
10451 \SpecialChar ~
10452 \SpecialChar ~
10453 \SpecialChar ~
10454  sdcdb-step-from-src\SpecialChar ~
10455 \SpecialChar ~
10456 \SpecialChar ~
10457 \SpecialChar ~
10458 \SpecialChar ~
10459 \SpecialChar ~
10460 \SpecialChar ~
10461 \SpecialChar ~
10462 \SpecialChar ~
10463 \SpecialChar ~
10464 SDCDB step command
10465 \newline
10466 ;; ?\SpecialChar ~
10467 \SpecialChar ~
10468 \SpecialChar ~
10469 \SpecialChar ~
10470 \SpecialChar ~
10471 \SpecialChar ~
10472 \SpecialChar ~
10473 \SpecialChar ~
10474 \SpecialChar ~
10475 \SpecialChar ~
10476 \SpecialChar ~
10477 \SpecialChar ~
10478 \SpecialChar ~
10479 \SpecialChar ~
10480  sdcdb-whatis-c-sexp\SpecialChar ~
10481 \SpecialChar ~
10482 \SpecialChar ~
10483 \SpecialChar ~
10484 \SpecialChar ~
10485 \SpecialChar ~
10486 \SpecialChar ~
10487 \SpecialChar ~
10488 \SpecialChar ~
10489 \SpecialChar ~
10490 SDCDB ptypecommand for data at
10491 \newline
10492 ;;\SpecialChar ~
10493 \SpecialChar ~
10494 \SpecialChar ~
10495 \SpecialChar ~
10496 \SpecialChar ~
10497 \SpecialChar ~
10498 \SpecialChar ~
10499 \SpecialChar ~
10500 \SpecialChar ~
10501 \SpecialChar ~
10502 \SpecialChar ~
10503 \SpecialChar ~
10504 \SpecialChar ~
10505 \SpecialChar ~
10506 \SpecialChar ~
10507 \SpecialChar ~
10508 \SpecialChar ~
10509 \SpecialChar ~
10510 \SpecialChar ~
10511 \SpecialChar ~
10512 \SpecialChar ~
10513 \SpecialChar ~
10514 \SpecialChar ~
10515 \SpecialChar ~
10516 \SpecialChar ~
10517 \SpecialChar ~
10518 \SpecialChar ~
10519 \SpecialChar ~
10520 \SpecialChar ~
10521 \SpecialChar ~
10522 \SpecialChar ~
10523 \SpecialChar ~
10524 \SpecialChar ~
10525 \SpecialChar ~
10526 \SpecialChar ~
10527 \SpecialChar ~
10528 \SpecialChar ~
10529 \SpecialChar ~
10530 \SpecialChar ~
10531 \SpecialChar ~
10532 \SpecialChar ~
10533 \SpecialChar ~
10534 \SpecialChar ~
10535 \SpecialChar ~
10536 \SpecialChar ~
10537 \SpecialChar ~
10538  buffer point
10539 \newline
10540 ;; x\SpecialChar ~
10541 \SpecialChar ~
10542 \SpecialChar ~
10543 \SpecialChar ~
10544 \SpecialChar ~
10545 \SpecialChar ~
10546 \SpecialChar ~
10547 \SpecialChar ~
10548 \SpecialChar ~
10549 \SpecialChar ~
10550 \SpecialChar ~
10551 \SpecialChar ~
10552 \SpecialChar ~
10553 \SpecialChar ~
10554  sdcdbsrc-delete\SpecialChar ~
10555 \SpecialChar ~
10556 \SpecialChar ~
10557 \SpecialChar ~
10558 \SpecialChar ~
10559 \SpecialChar ~
10560 \SpecialChar ~
10561 \SpecialChar ~
10562 \SpecialChar ~
10563 \SpecialChar ~
10564 \SpecialChar ~
10565 \SpecialChar ~
10566 \SpecialChar ~
10567 \SpecialChar ~
10568 SDCDB Delete all breakpoints if no arg
10569 \newline
10570 ;;\SpecialChar ~
10571 \SpecialChar ~
10572 \SpecialChar ~
10573 \SpecialChar ~
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 \SpecialChar ~
10580 \SpecialChar ~
10581 \SpecialChar ~
10582 \SpecialChar ~
10583 \SpecialChar ~
10584 \SpecialChar ~
10585 \SpecialChar ~
10586 \SpecialChar ~
10587 \SpecialChar ~
10588 \SpecialChar ~
10589 \SpecialChar ~
10590 \SpecialChar ~
10591 \SpecialChar ~
10592 \SpecialChar ~
10593 \SpecialChar ~
10594 \SpecialChar ~
10595 \SpecialChar ~
10596 \SpecialChar ~
10597 \SpecialChar ~
10598 \SpecialChar ~
10599 \SpecialChar ~
10600 \SpecialChar ~
10601 \SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 \SpecialChar ~
10605 \SpecialChar ~
10606 \SpecialChar ~
10607 \SpecialChar ~
10608 \SpecialChar ~
10609 \SpecialChar ~
10610 \SpecialChar ~
10611 \SpecialChar ~
10612 \SpecialChar ~
10613 \SpecialChar ~
10614 \SpecialChar ~
10615 \SpecialChar ~
10616 given or delete arg (C-u arg x)
10617 \newline
10618 ;; m\SpecialChar ~
10619 \SpecialChar ~
10620 \SpecialChar ~
10621 \SpecialChar ~
10622 \SpecialChar ~
10623 \SpecialChar ~
10624 \SpecialChar ~
10625 \SpecialChar ~
10626 \SpecialChar ~
10627 \SpecialChar ~
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632  sdcdbsrc-frame\SpecialChar ~
10633 \SpecialChar ~
10634 \SpecialChar ~
10635 \SpecialChar ~
10636 \SpecialChar ~
10637 \SpecialChar ~
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 \SpecialChar ~
10645 \SpecialChar ~
10646 \SpecialChar ~
10647 SDCDB Display current frame if no arg,
10648 \newline
10649 ;;\SpecialChar ~
10650 \SpecialChar ~
10651 \SpecialChar ~
10652 \SpecialChar ~
10653 \SpecialChar ~
10654 \SpecialChar ~
10655 \SpecialChar ~
10656 \SpecialChar ~
10657 \SpecialChar ~
10658 \SpecialChar ~
10659 \SpecialChar ~
10660 \SpecialChar ~
10661 \SpecialChar ~
10662 \SpecialChar ~
10663 \SpecialChar ~
10664 \SpecialChar ~
10665 \SpecialChar ~
10666 \SpecialChar ~
10667 \SpecialChar ~
10668 \SpecialChar ~
10669 \SpecialChar ~
10670 \SpecialChar ~
10671 \SpecialChar ~
10672 \SpecialChar ~
10673 \SpecialChar ~
10674 \SpecialChar ~
10675 \SpecialChar ~
10676 \SpecialChar ~
10677 \SpecialChar ~
10678 \SpecialChar ~
10679 \SpecialChar ~
10680 \SpecialChar ~
10681 \SpecialChar ~
10682 \SpecialChar ~
10683 \SpecialChar ~
10684 \SpecialChar ~
10685 \SpecialChar ~
10686 \SpecialChar ~
10687 \SpecialChar ~
10688 \SpecialChar ~
10689 \SpecialChar ~
10690 \SpecialChar ~
10691 \SpecialChar ~
10692 \SpecialChar ~
10693 \SpecialChar ~
10694 \SpecialChar ~
10695 \SpecialChar ~
10696 given or display frame arg
10697 \newline
10698 ;;\SpecialChar ~
10699 \SpecialChar ~
10700 \SpecialChar ~
10701 \SpecialChar ~
10702 \SpecialChar ~
10703 \SpecialChar ~
10704 \SpecialChar ~
10705 \SpecialChar ~
10706 \SpecialChar ~
10707 \SpecialChar ~
10708 \SpecialChar ~
10709 \SpecialChar ~
10710 \SpecialChar ~
10711 \SpecialChar ~
10712 \SpecialChar ~
10713 \SpecialChar ~
10714 \SpecialChar ~
10715 \SpecialChar ~
10716 \SpecialChar ~
10717 \SpecialChar ~
10718 \SpecialChar ~
10719 \SpecialChar ~
10720 \SpecialChar ~
10721 \SpecialChar ~
10722 \SpecialChar ~
10723 \SpecialChar ~
10724 \SpecialChar ~
10725 \SpecialChar ~
10726 \SpecialChar ~
10727 \SpecialChar ~
10728 \SpecialChar ~
10729 \SpecialChar ~
10730 \SpecialChar ~
10731 \SpecialChar ~
10732 \SpecialChar ~
10733 \SpecialChar ~
10734 \SpecialChar ~
10735 \SpecialChar ~
10736 \SpecialChar ~
10737 \SpecialChar ~
10738 \SpecialChar ~
10739 \SpecialChar ~
10740 \SpecialChar ~
10741 \SpecialChar ~
10742 \SpecialChar ~
10743 \SpecialChar ~
10744 \SpecialChar ~
10745 buffer point
10746 \newline
10747 ;; !\SpecialChar ~
10748 \SpecialChar ~
10749 \SpecialChar ~
10750 \SpecialChar ~
10751 \SpecialChar ~
10752 \SpecialChar ~
10753 \SpecialChar ~
10754 \SpecialChar ~
10755 \SpecialChar ~
10756 \SpecialChar ~
10757 \SpecialChar ~
10758 \SpecialChar ~
10759 \SpecialChar ~
10760 \SpecialChar ~
10761  sdcdbsrc-goto-sdcdb\SpecialChar ~
10762 \SpecialChar ~
10763 \SpecialChar ~
10764 \SpecialChar ~
10765 \SpecialChar ~
10766 \SpecialChar ~
10767 \SpecialChar ~
10768 \SpecialChar ~
10769 \SpecialChar ~
10770 \SpecialChar ~
10771 Goto the SDCDB output buffer
10772 \newline
10773 ;; p\SpecialChar ~
10774 \SpecialChar ~
10775 \SpecialChar ~
10776 \SpecialChar ~
10777 \SpecialChar ~
10778 \SpecialChar ~
10779 \SpecialChar ~
10780 \SpecialChar ~
10781 \SpecialChar ~
10782 \SpecialChar ~
10783 \SpecialChar ~
10784 \SpecialChar ~
10785 \SpecialChar ~
10786 \SpecialChar ~
10787  sdcdb-print-c-sexp\SpecialChar ~
10788 \SpecialChar ~
10789 \SpecialChar ~
10790 \SpecialChar ~
10791 \SpecialChar ~
10792 \SpecialChar ~
10793 \SpecialChar ~
10794 \SpecialChar ~
10795 \SpecialChar ~
10796 \SpecialChar ~
10797 \SpecialChar ~
10798 SDCDB print command for data at
10799 \newline
10800 ;;\SpecialChar ~
10801 \SpecialChar ~
10802 \SpecialChar ~
10803 \SpecialChar ~
10804 \SpecialChar ~
10805 \SpecialChar ~
10806 \SpecialChar ~
10807 \SpecialChar ~
10808 \SpecialChar ~
10809 \SpecialChar ~
10810 \SpecialChar ~
10811 \SpecialChar ~
10812 \SpecialChar ~
10813 \SpecialChar ~
10814 \SpecialChar ~
10815 \SpecialChar ~
10816 \SpecialChar ~
10817 \SpecialChar ~
10818 \SpecialChar ~
10819 \SpecialChar ~
10820 \SpecialChar ~
10821 \SpecialChar ~
10822 \SpecialChar ~
10823 \SpecialChar ~
10824 \SpecialChar ~
10825 \SpecialChar ~
10826 \SpecialChar ~
10827 \SpecialChar ~
10828 \SpecialChar ~
10829 \SpecialChar ~
10830 \SpecialChar ~
10831 \SpecialChar ~
10832 \SpecialChar ~
10833 \SpecialChar ~
10834 \SpecialChar ~
10835 \SpecialChar ~
10836 \SpecialChar ~
10837 \SpecialChar ~
10838 \SpecialChar ~
10839 \SpecialChar ~
10840 \SpecialChar ~
10841 \SpecialChar ~
10842 \SpecialChar ~
10843 \SpecialChar ~
10844 \SpecialChar ~
10845 \SpecialChar ~
10846  buffer point
10847 \newline
10848 ;; g\SpecialChar ~
10849 \SpecialChar ~
10850 \SpecialChar ~
10851 \SpecialChar ~
10852 \SpecialChar ~
10853 \SpecialChar ~
10854 \SpecialChar ~
10855 \SpecialChar ~
10856 \SpecialChar ~
10857 \SpecialChar ~
10858 \SpecialChar ~
10859 \SpecialChar ~
10860 \SpecialChar ~
10861 \SpecialChar ~
10862  sdcdbsrc-goto-sdcdb\SpecialChar ~
10863 \SpecialChar ~
10864 \SpecialChar ~
10865 \SpecialChar ~
10866 \SpecialChar ~
10867 \SpecialChar ~
10868 \SpecialChar ~
10869 \SpecialChar ~
10870 \SpecialChar ~
10871 \SpecialChar ~
10872 Goto the SDCDB output buffer
10873 \newline
10874 ;; t\SpecialChar ~
10875 \SpecialChar ~
10876 \SpecialChar ~
10877 \SpecialChar ~
10878 \SpecialChar ~
10879 \SpecialChar ~
10880 \SpecialChar ~
10881 \SpecialChar ~
10882 \SpecialChar ~
10883 \SpecialChar ~
10884 \SpecialChar ~
10885 \SpecialChar ~
10886 \SpecialChar ~
10887 \SpecialChar ~
10888  sdcdbsrc-mode\SpecialChar ~
10889 \SpecialChar ~
10890 \SpecialChar ~
10891 \SpecialChar ~
10892 \SpecialChar ~
10893 \SpecialChar ~
10894 \SpecialChar ~
10895 \SpecialChar ~
10896 \SpecialChar ~
10897 \SpecialChar ~
10898 \SpecialChar ~
10899 \SpecialChar ~
10900 \SpecialChar ~
10901 \SpecialChar ~
10902 \SpecialChar ~
10903 \SpecialChar ~
10904 Toggles Sdcdbsrc mode (turns it off)
10905 \newline
10906 ;;
10907 \newline
10908 ;; C-c C-f\SpecialChar ~
10909 \SpecialChar ~
10910 \SpecialChar ~
10911 \SpecialChar ~
10912 \SpecialChar ~
10913 \SpecialChar ~
10914 \SpecialChar ~
10915 \SpecialChar ~
10916  sdcdb-finish-from-src\SpecialChar ~
10917 \SpecialChar ~
10918 \SpecialChar ~
10919 \SpecialChar ~
10920 \SpecialChar ~
10921 \SpecialChar ~
10922 \SpecialChar ~
10923 \SpecialChar ~
10924 SDCDB finish command
10925 \newline
10926 ;;
10927 \newline
10928 ;; C-x SPC\SpecialChar ~
10929 \SpecialChar ~
10930 \SpecialChar ~
10931 \SpecialChar ~
10932 \SpecialChar ~
10933 \SpecialChar ~
10934 \SpecialChar ~
10935 \SpecialChar ~
10936  sdcdb-break\SpecialChar ~
10937 \SpecialChar ~
10938 \SpecialChar ~
10939 \SpecialChar ~
10940 \SpecialChar ~
10941 \SpecialChar ~
10942 \SpecialChar ~
10943 \SpecialChar ~
10944 \SpecialChar ~
10945 \SpecialChar ~
10946 \SpecialChar ~
10947 \SpecialChar ~
10948 \SpecialChar ~
10949 \SpecialChar ~
10950 \SpecialChar ~
10951 \SpecialChar ~
10952 \SpecialChar ~
10953 \SpecialChar ~
10954 Set break for line with point
10955 \newline
10956 ;; ESC t\SpecialChar ~
10957 \SpecialChar ~
10958 \SpecialChar ~
10959 \SpecialChar ~
10960 \SpecialChar ~
10961 \SpecialChar ~
10962 \SpecialChar ~
10963 \SpecialChar ~
10964 \SpecialChar ~
10965 \SpecialChar ~
10966  sdcdbsrc-mode\SpecialChar ~
10967 \SpecialChar ~
10968 \SpecialChar ~
10969 \SpecialChar ~
10970 \SpecialChar ~
10971 \SpecialChar ~
10972 \SpecialChar ~
10973 \SpecialChar ~
10974 \SpecialChar ~
10975 \SpecialChar ~
10976 \SpecialChar ~
10977 \SpecialChar ~
10978 \SpecialChar ~
10979 \SpecialChar ~
10980 \SpecialChar ~
10981 \SpecialChar ~
10982 Toggle Sdcdbsrc mode
10983 \newline
10984 ;; ESC m\SpecialChar ~
10985 \SpecialChar ~
10986 \SpecialChar ~
10987 \SpecialChar ~
10988 \SpecialChar ~
10989 \SpecialChar ~
10990 \SpecialChar ~
10991 \SpecialChar ~
10992 \SpecialChar ~
10993 \SpecialChar ~
10994  sdcdbsrc-srcmode\SpecialChar ~
10995 \SpecialChar ~
10996 \SpecialChar ~
10997 \SpecialChar ~
10998 \SpecialChar ~
10999 \SpecialChar ~
11000 \SpecialChar ~
11001 \SpecialChar ~
11002 \SpecialChar ~
11003 \SpecialChar ~
11004 \SpecialChar ~
11005 \SpecialChar ~
11006  Toggle list mode
11007 \newline
11008 ;;
11009 \family default
11010
11011 \newline
11012
11013 \layout Section
11014 \pagebreak_top
11015 Other Processors
11016 \layout Subsection
11017
11018 The Z80 and gbz80 port
11019 \layout Standard
11020
11021 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
11022  The port is incomplete - long support is incomplete (mul, div and mod are
11023  unimplimented), and both float and bitfield support is missing.
11024  Apart from that the code generated is correct.
11025 \layout Standard
11026
11027 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
11028  The stack frame is similar to that generated by the IAR Z80 compiler.
11029  IX is used as the base pointer, HL is used as a temporary register, and
11030  BC and DE are available for holding varibles.
11031  IY is currently unusued.
11032  Return values are stored in HL.
11033  One bad side effect of using IX as the base pointer is that a functions
11034  stack frame is limited to 127 bytes - this will be fixed in a later version.
11035 \layout Section
11036
11037 Support
11038 \begin_inset LatexCommand \index{Support}
11039
11040 \end_inset
11041
11042
11043 \layout Standard
11044
11045 SDCC has grown to be a large project.
11046  The compiler alone (without the preprocessor, assembler and linker) is
11047  about 40,000 lines of code (blank stripped).
11048  The open source nature of this project is a key to its continued growth
11049  and support.
11050  You gain the benefit and support of many active software developers and
11051  end users.
11052  Is SDCC perfect? No, that's why we need your help.
11053  The developers take pride in fixing reported bugs.
11054  You can help by reporting the bugs and helping other SDCC users.
11055  There are lots of ways to contribute, and we encourage you to take part
11056  in making SDCC a great software package.
11057 \layout Subsection
11058
11059 Reporting Bugs
11060 \begin_inset LatexCommand \index{Bugs}
11061
11062 \end_inset
11063
11064
11065 \begin_inset LatexCommand \index{Reporting Bugs}
11066
11067 \end_inset
11068
11069
11070 \layout Standard
11071
11072 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
11073 cc@sdcc.sourceforge.net'.
11074  Bugs will be fixed ASAP.
11075  When reporting a bug, it is very useful to include a small test program
11076  which reproduces the problem.
11077  If you can isolate the problem by looking at the generated assembly code,
11078  this can be very helpful.
11079  Compiling your program with the ---dumpall option can sometimes be useful
11080  in locating optimization problems.
11081 \layout Section
11082 \pagebreak_top
11083 Compiler internals
11084 \layout Subsection
11085
11086 The anatomy of the compiler
11087 \layout Standard
11088
11089
11090 \shape italic
11091 This is an excerpt from an atricle published in Circuit Cellar MagaZine
11092  in august 2000.
11093  It's a little outdated (the compiler is much more efficient now and user/devell
11094 oper friendly), but pretty well exposes the guts of it all.
11095 \shape default
11096
11097 \newline
11098
11099 \newline
11100 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
11101  It is fairly easy to retarget for other 8-bit MCU.
11102  Here we take a look at some of the internals of the compiler.
11103
11104 \layout Paragraph*
11105
11106 Parsing
11107 \begin_inset LatexCommand \index{Parsing}
11108
11109 \end_inset
11110
11111
11112 \layout Standard
11113
11114 Parsing the input source file and creating an AST (Annotated Syntax Tree
11115 \begin_inset LatexCommand \index{Annotated Syntax Tree}
11116
11117 \end_inset
11118
11119 ).
11120  This phase also involves propagating types (annotating each node of the
11121  parse tree with type information) and semantic analysis.
11122  There are some MCU specific parsing rules.
11123  For example the storage classes, the extended storage classes are MCU specific
11124  while there may be a xdata storage class for 8051 there is no such storage
11125  class for z80 or Atmel AVR.
11126  SDCC allows MCU specific storage class extensions, i.e.
11127  xdata will be treated as a storage class specifier when parsing 8051 C
11128  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
11129  C code.
11130 \layout Paragraph*
11131
11132 Generating iCode
11133 \begin_inset LatexCommand \index{iCode}
11134
11135 \end_inset
11136
11137
11138 \layout Standard
11139
11140 Intermediate code generation.
11141  In this phase the AST is broken down into three-operand form (iCode).
11142  These three operand forms are represented as doubly linked lists.
11143  ICode is the term given to the intermediate form generated by the compiler.
11144  ICode example section shows some examples of iCode generated for some simple
11145  C source functions.
11146 \layout Paragraph*
11147
11148 Optimizations
11149 \begin_inset LatexCommand \index{Optimizations}
11150
11151 \end_inset
11152
11153 .
11154 \layout Standard
11155
11156 Bulk of the target independent optimizations is performed in this phase.
11157  The optimizations include constant propagation, common sub-expression eliminati
11158 on, loop invariant code movement, strength reduction of loop induction variables
11159  and dead-code elimination.
11160 \layout Paragraph*
11161
11162 Live range analysis
11163 \begin_inset LatexCommand \index{Live range analysis}
11164
11165 \end_inset
11166
11167
11168 \layout Standard
11169
11170 During intermediate code generation phase, the compiler assumes the target
11171  machine has infinite number of registers and generates a lot of temporary
11172  variables.
11173  The live range computation determines the lifetime of each of these compiler-ge
11174 nerated temporaries.
11175  A picture speaks a thousand words.
11176  ICode example sections show the live range annotations for each of the
11177  operand.
11178  It is important to note here, each iCode is assigned a number in the order
11179  of its execution in the function.
11180  The live ranges are computed in terms of these numbers.
11181  The from number is the number of the iCode which first defines the operand
11182  and the to number signifies the iCode which uses this operand last.
11183 \layout Paragraph*
11184
11185 Register Allocation
11186 \begin_inset LatexCommand \index{Register Allocation}
11187
11188 \end_inset
11189
11190
11191 \layout Standard
11192
11193 The register allocation determines the type and number of registers needed
11194  by each operand.
11195  In most MCUs only a few registers can be used for indirect addressing.
11196  In case of 8051 for example the registers R0 & R1 can be used to indirectly
11197  address the internal ram and DPTR to indirectly address the external ram.
11198  The compiler will try to allocate the appropriate register to pointer variables
11199  if it can.
11200  ICode example section shows the operands annotated with the registers assigned
11201  to them.
11202  The compiler will try to keep operands in registers as much as possible;
11203  there are several schemes the compiler uses to do achieve this.
11204  When the compiler runs out of registers the compiler will check to see
11205  if there are any live operands which is not used or defined in the current
11206  basic block being processed, if there are any found then it will push that
11207  operand and use the registers in this block, the operand will then be popped
11208  at the end of the basic block.
11209
11210 \layout Standard
11211
11212 There are other MCU specific considerations in this phase.
11213  Some MCUs have an accumulator; very short-lived operands could be assigned
11214  to the accumulator instead of general-purpose register.
11215 \layout Paragraph*
11216
11217 Code generation
11218 \layout Standard
11219
11220 Figure II gives a table of iCode operations supported by the compiler.
11221  The code generation involves translating these operations into corresponding
11222  assembly code for the processor.
11223  This sounds overly simple but that is the essence of code generation.
11224  Some of the iCode operations are generated on a MCU specific manner for
11225  example, the z80 port does not use registers to pass parameters so the
11226  SEND and RECV iCode operations will not be generated, and it also does
11227  not support JUMPTABLES.
11228
11229 \newline
11230
11231 \series bold
11232 \shape italic
11233 \color red
11234 <Where is Figure II ?>
11235 \layout Paragraph*
11236
11237 ICode Example
11238 \begin_inset LatexCommand \index{ICode Example}
11239
11240 \end_inset
11241
11242
11243 \layout Standard
11244
11245 This section shows some details of iCode.
11246  The example C code does not do anything useful; it is used as an example
11247  to illustrate the intermediate code generated by the compiler.
11248 \newline
11249
11250 \newline
11251
11252 \family typewriter
11253 1.\SpecialChar ~
11254 xdata int * p;
11255 \newline
11256 2.\SpecialChar ~
11257 int gint;
11258 \newline
11259 3.\SpecialChar ~
11260 /* This function does nothing useful.
11261  It is used
11262 \newline
11263 4.\SpecialChar ~
11264 \SpecialChar ~
11265 \SpecialChar ~
11266 \SpecialChar ~
11267 for the purpose of explaining iCode */
11268 \newline
11269 5.\SpecialChar ~
11270 short function (data int *x)
11271 \newline
11272 6.\SpecialChar ~
11273 {
11274 \newline
11275 7.\SpecialChar ~
11276 \SpecialChar ~
11277 \SpecialChar ~
11278 short i=10; /* dead initialization eliminated */
11279 \newline
11280 8.\SpecialChar ~
11281 \SpecialChar ~
11282 \SpecialChar ~
11283 short sum=10; /* dead initialization eliminated */
11284 \newline
11285 9.\SpecialChar ~
11286 \SpecialChar ~
11287 \SpecialChar ~
11288 short mul;
11289 \newline
11290 10.\SpecialChar ~
11291 \SpecialChar ~
11292 int j ;
11293 \newline
11294 11.\SpecialChar ~
11295 \SpecialChar ~
11296 while (*x) *x++ = *p++;
11297 \newline
11298 12.\SpecialChar ~
11299 \SpecialChar ~
11300 \SpecialChar ~
11301 \SpecialChar ~
11302 sum = 0 ;
11303 \newline
11304 13.\SpecialChar ~
11305 \SpecialChar ~
11306 mul = 0;
11307 \newline
11308 14.\SpecialChar ~
11309 \SpecialChar ~
11310 /* compiler detects i,j to be induction variables */
11311 \newline
11312 15.\SpecialChar ~
11313 \SpecialChar ~
11314 for (i = 0, j = 10 ; i < 10 ; i++, j---) {
11315 \newline
11316 16.\SpecialChar ~
11317 \SpecialChar ~
11318 \SpecialChar ~
11319 \SpecialChar ~
11320 sum += i;
11321 \newline
11322 17.\SpecialChar ~
11323 \SpecialChar ~
11324 \SpecialChar ~
11325 \SpecialChar ~
11326 mul += i * 3; /* this multiplication remains */
11327 \newline
11328 18.\SpecialChar ~
11329 \SpecialChar ~
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 gint += j * 3;/* this multiplication changed to addition */
11333 \newline
11334 19.\SpecialChar ~
11335 \SpecialChar ~
11336 }
11337 \newline
11338 20.\SpecialChar ~
11339 \SpecialChar ~
11340 return sum+mul;
11341 \newline
11342 21.\SpecialChar ~
11343 }
11344 \newline
11345
11346 \newline
11347
11348 \family default
11349 In addition to the operands each iCode contains information about the filename
11350  and line it corresponds to in the source file.
11351  The first field in the listing should be interpreted as follows:
11352 \newline
11353
11354 \shape italic
11355 \size footnotesize
11356 Filename(linenumber: iCode Execution sequence number : ICode hash table
11357  key : loop depth of the iCode).
11358 \shape default
11359 \size default
11360
11361 \newline
11362 Then follows the human readable form of the ICode operation.
11363  Each operand of this triplet form can be of three basic types a) compiler
11364  generated temporary b) user defined variable c) a constant value.
11365  Note that local variables and parameters are replaced by compiler generated
11366  temporaries.
11367  Live ranges are computed only for temporaries (i.e.
11368  live ranges are not computed for global variables).
11369  Registers are allocated for temporaries only.
11370  Operands are formatted in the following manner:
11371 \newline
11372
11373 \shape italic
11374 \size footnotesize
11375 Operand Name [lr live-from : live-to ] { type information } [ registers
11376  allocated ].
11377 \shape default
11378 \size default
11379
11380 \newline
11381 As mentioned earlier the live ranges are computed in terms of the execution
11382  sequence number of the iCodes, for example
11383 \newline
11384 the iTemp0 is live from (i.e.
11385  first defined in iCode with execution sequence number 3, and is last used
11386  in the iCode with sequence number 5).
11387  For induction variables such as iTemp21 the live range computation extends
11388  the lifetime from the start to the end of the loop.
11389 \newline
11390 The register allocator used the live range information to allocate registers,
11391  the same registers may be used for different temporaries if their live
11392  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
11393  iTemp17 since their live ranges do not overlap.
11394  In addition the allocator also takes into consideration the type and usage
11395  of a temporary, for example itemp6 is a pointer to near space and is used
11396  as to fetch data from (i.e.
11397  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
11398  Some short lived temporaries are allocated to special registers which have
11399  meaning to the code generator e.g.
11400  iTemp13 is allocated to a pseudo register CC which tells the back end that
11401  the temporary is used only for a conditional jump the code generation makes
11402  use of this information to optimize a compare and jump ICode.
11403 \newline
11404 There are several loop optimizations performed by the compiler.
11405  It can detect induction variables iTemp21(i) and iTemp23(j).
11406  Also note the compiler does selective strength reduction, i.e.
11407  the multiplication of an induction variable in line 18 (gint = j * 3) is
11408  changed to addition, a new temporary iTemp17 is allocated and assigned
11409  a initial value, a constant 3 is then added for each iteration of the loop.
11410  The compiler does not change the multiplication in line 17 however since
11411  the processor does support an 8 * 8 bit multiplication.
11412 \newline
11413 Note the dead code elimination optimization eliminated the dead assignments
11414  in line 7 & 8 to I and sum respectively.
11415 \newline
11416
11417 \layout Standard
11418
11419
11420 \size footnotesize
11421 Sample.c (5:1:0:0) _entry($9) :
11422 \layout Standard
11423
11424
11425 \size footnotesize
11426 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
11427 \layout Standard
11428
11429
11430 \size footnotesize
11431 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
11432 \layout Standard
11433
11434
11435 \size footnotesize
11436 Sample.c(11:4:53:0) preHeaderLbl0($11) :
11437 \layout Standard
11438
11439
11440 \size footnotesize
11441 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
11442  * int}[r2]
11443 \layout Standard
11444
11445
11446 \size footnotesize
11447 Sample.c(11:6:5:1) _whilecontinue_0($1) :
11448 \layout Standard
11449
11450
11451 \size footnotesize
11452 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
11453  int}[r0]]
11454 \layout Standard
11455
11456
11457 \size footnotesize
11458 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
11459 \layout Standard
11460
11461
11462 \size footnotesize
11463 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
11464  * int}
11465 \layout Standard
11466
11467
11468 \size footnotesize
11469 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
11470  {short}
11471 \layout Standard
11472
11473
11474 \size footnotesize
11475 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
11476  * int}[DPTR]]
11477 \layout Standard
11478
11479
11480 \size footnotesize
11481 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
11482 }[r2 r3]
11483 \layout Standard
11484
11485
11486 \size footnotesize
11487 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
11488  * int}[r0] + 0x2 {short}
11489 \layout Standard
11490
11491
11492 \size footnotesize
11493 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
11494 \layout Standard
11495
11496
11497 \size footnotesize
11498 Sample.c(11:17:21:0)_whilebreak_0($3) :
11499 \layout Standard
11500
11501
11502 \size footnotesize
11503 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
11504 \layout Standard
11505
11506
11507 \size footnotesize
11508 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
11509 \layout Standard
11510
11511
11512 \size footnotesize
11513 Sample.c(15:20:54:0)preHeaderLbl1($13) :
11514 \layout Standard
11515
11516
11517 \size footnotesize
11518 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
11519 \layout Standard
11520
11521
11522 \size footnotesize
11523 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
11524 \layout Standard
11525
11526
11527 \size footnotesize
11528 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
11529 \layout Standard
11530
11531
11532 \size footnotesize
11533 Sample.c(15:24:26:1)_forcond_0($4) :
11534 \layout Standard
11535
11536
11537 \size footnotesize
11538 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
11539  < 0xa {short}
11540 \layout Standard
11541
11542
11543 \size footnotesize
11544 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
11545 \layout Standard
11546
11547
11548 \size footnotesize
11549 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
11550  + ITemp21 [lr21:38]{short}[r4]
11551 \layout Standard
11552
11553
11554 \size footnotesize
11555 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
11556  * 0x3 {short}
11557 \layout Standard
11558
11559
11560 \size footnotesize
11561 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
11562  + iTemp15 [lr29:30]{short}[r1]
11563 \layout Standard
11564
11565
11566 \size footnotesize
11567 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
11568  r0]- 0x3 {short}
11569 \layout Standard
11570
11571
11572 \size footnotesize
11573 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
11574 int}[r7 r0]
11575 \layout Standard
11576
11577
11578 \size footnotesize
11579 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
11580  + 0x1 {short}
11581 \layout Standard
11582
11583
11584 \size footnotesize
11585 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
11586  r6]- 0x1 {short}
11587 \layout Standard
11588
11589
11590 \size footnotesize
11591 Sample.c(19:38:47:1) goto _forcond_0($4)
11592 \layout Standard
11593
11594
11595 \size footnotesize
11596 Sample.c(19:39:48:0)_forbreak_0($7) :
11597 \layout Standard
11598
11599
11600 \size footnotesize
11601 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
11602  + ITemp11 [lr19:40]{short}[r3]
11603 \layout Standard
11604
11605
11606 \size footnotesize
11607 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
11608 \layout Standard
11609
11610
11611 \size footnotesize
11612 Sample.c(20:42:51:0)_return($8) :
11613 \layout Standard
11614
11615
11616 \size footnotesize
11617 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
11618 \size default
11619
11620 \newline
11621
11622 \newline
11623 Finally the code generated for this function:
11624 \newline
11625
11626 \layout Standard
11627
11628
11629 \size footnotesize
11630 .area DSEG (DATA)
11631 \layout Standard
11632
11633
11634 \size footnotesize
11635 _p::
11636 \layout Standard
11637
11638
11639 \size footnotesize
11640 \SpecialChar ~
11641 \SpecialChar ~
11642 .ds 2
11643 \layout Standard
11644
11645
11646 \size footnotesize
11647 _gint::
11648 \layout Standard
11649
11650
11651 \size footnotesize
11652 \SpecialChar ~
11653 \SpecialChar ~
11654 .ds 2
11655 \layout Standard
11656
11657
11658 \size footnotesize
11659 ; sample.c 5
11660 \layout Standard
11661
11662
11663 \size footnotesize
11664 ; ----------------------------------------------
11665 \layout Standard
11666
11667
11668 \size footnotesize
11669 ; function function
11670 \layout Standard
11671
11672
11673 \size footnotesize
11674 ; ----------------------------------------------
11675 \layout Standard
11676
11677
11678 \size footnotesize
11679 _function:
11680 \layout Standard
11681
11682
11683 \size footnotesize
11684 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
11685 \layout Standard
11686
11687
11688 \size footnotesize
11689 \SpecialChar ~
11690 \SpecialChar ~
11691 mov r2,dpl
11692 \layout Standard
11693
11694
11695 \size footnotesize
11696 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
11697 \layout Standard
11698
11699
11700 \size footnotesize
11701 \SpecialChar ~
11702 \SpecialChar ~
11703 mov ar0,r2
11704 \layout Standard
11705
11706
11707 \size footnotesize
11708 ;_whilecontinue_0($1) :
11709 \layout Standard
11710
11711
11712 \size footnotesize
11713 00101$:
11714 \layout Standard
11715
11716
11717 \size footnotesize
11718 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
11719 \layout Standard
11720
11721
11722 \size footnotesize
11723 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
11724 \layout Standard
11725
11726
11727 \size footnotesize
11728 \SpecialChar ~
11729 \SpecialChar ~
11730 mov ar2,@r0
11731 \layout Standard
11732
11733
11734 \size footnotesize
11735 \SpecialChar ~
11736 \SpecialChar ~
11737 inc r0
11738 \layout Standard
11739
11740
11741 \size footnotesize
11742 \SpecialChar ~
11743 \SpecialChar ~
11744 mov ar3,@r0
11745 \layout Standard
11746
11747
11748 \size footnotesize
11749 \SpecialChar ~
11750 \SpecialChar ~
11751 dec r0
11752 \layout Standard
11753
11754
11755 \size footnotesize
11756 \SpecialChar ~
11757 \SpecialChar ~
11758 mov a,r2
11759 \layout Standard
11760
11761
11762 \size footnotesize
11763 \SpecialChar ~
11764 \SpecialChar ~
11765 orl a,r3
11766 \layout Standard
11767
11768
11769 \size footnotesize
11770 \SpecialChar ~
11771 \SpecialChar ~
11772 jz 00103$
11773 \layout Standard
11774
11775
11776 \size footnotesize
11777 00114$:
11778 \layout Standard
11779
11780
11781 \size footnotesize
11782 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
11783 \layout Standard
11784
11785
11786 \size footnotesize
11787 \SpecialChar ~
11788 \SpecialChar ~
11789 mov dpl,_p
11790 \layout Standard
11791
11792
11793 \size footnotesize
11794 \SpecialChar ~
11795 \SpecialChar ~
11796 mov dph,(_p + 1)
11797 \layout Standard
11798
11799
11800 \size footnotesize
11801 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
11802 \layout Standard
11803
11804
11805 \size footnotesize
11806 \SpecialChar ~
11807 \SpecialChar ~
11808 mov a,#0x02
11809 \layout Standard
11810
11811
11812 \size footnotesize
11813 \SpecialChar ~
11814 \SpecialChar ~
11815 add a,_p
11816 \layout Standard
11817
11818
11819 \size footnotesize
11820 \SpecialChar ~
11821 \SpecialChar ~
11822 mov _p,a
11823 \layout Standard
11824
11825
11826 \size footnotesize
11827 \SpecialChar ~
11828 \SpecialChar ~
11829 clr a
11830 \layout Standard
11831
11832
11833 \size footnotesize
11834 \SpecialChar ~
11835 \SpecialChar ~
11836 addc a,(_p + 1)
11837 \layout Standard
11838
11839
11840 \size footnotesize
11841 \SpecialChar ~
11842 \SpecialChar ~
11843 mov (_p + 1),a
11844 \layout Standard
11845
11846
11847 \size footnotesize
11848 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
11849 \layout Standard
11850
11851
11852 \size footnotesize
11853 \SpecialChar ~
11854 \SpecialChar ~
11855 movx a,@dptr
11856 \layout Standard
11857
11858
11859 \size footnotesize
11860 \SpecialChar ~
11861 \SpecialChar ~
11862 mov r2,a
11863 \layout Standard
11864
11865
11866 \size footnotesize
11867 \SpecialChar ~
11868 \SpecialChar ~
11869 inc dptr
11870 \layout Standard
11871
11872
11873 \size footnotesize
11874 \SpecialChar ~
11875 \SpecialChar ~
11876 movx a,@dptr
11877 \layout Standard
11878
11879
11880 \size footnotesize
11881 \SpecialChar ~
11882 \SpecialChar ~
11883 mov r3,a
11884 \layout Standard
11885
11886
11887 \size footnotesize
11888 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
11889 \layout Standard
11890
11891
11892 \size footnotesize
11893 \SpecialChar ~
11894 \SpecialChar ~
11895 mov @r0,ar2
11896 \layout Standard
11897
11898
11899 \size footnotesize
11900 \SpecialChar ~
11901 \SpecialChar ~
11902 inc r0
11903 \layout Standard
11904
11905
11906 \size footnotesize
11907 \SpecialChar ~
11908 \SpecialChar ~
11909 mov @r0,ar3
11910 \layout Standard
11911
11912
11913 \size footnotesize
11914 ; iTemp6 [lr5:16]{_near * int}[r0] =
11915 \layout Standard
11916
11917
11918 \size footnotesize
11919 ; iTemp6 [lr5:16]{_near * int}[r0] +
11920 \layout Standard
11921
11922
11923 \size footnotesize
11924 ; 0x2 {short}
11925 \layout Standard
11926
11927
11928 \size footnotesize
11929 \SpecialChar ~
11930 \SpecialChar ~
11931 inc r0
11932 \layout Standard
11933
11934
11935 \size footnotesize
11936 ; goto _whilecontinue_0($1)
11937 \layout Standard
11938
11939
11940 \size footnotesize
11941 \SpecialChar ~
11942 \SpecialChar ~
11943 sjmp 00101$
11944 \layout Standard
11945
11946
11947 \size footnotesize
11948 ; _whilebreak_0($3) :
11949 \layout Standard
11950
11951
11952 \size footnotesize
11953 00103$:
11954 \layout Standard
11955
11956
11957 \size footnotesize
11958 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
11959 \layout Standard
11960
11961
11962 \size footnotesize
11963 \SpecialChar ~
11964 \SpecialChar ~
11965 mov r2,#0x00
11966 \layout Standard
11967
11968
11969 \size footnotesize
11970 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
11971 \layout Standard
11972
11973
11974 \size footnotesize
11975 \SpecialChar ~
11976 \SpecialChar ~
11977 mov r3,#0x00
11978 \layout Standard
11979
11980
11981 \size footnotesize
11982 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
11983 \layout Standard
11984
11985
11986 \size footnotesize
11987 \SpecialChar ~
11988 \SpecialChar ~
11989 mov r4,#0x00
11990 \layout Standard
11991
11992
11993 \size footnotesize
11994 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
11995 \layout Standard
11996
11997
11998 \size footnotesize
11999 \SpecialChar ~
12000 \SpecialChar ~
12001 mov r5,#0x0A
12002 \layout Standard
12003
12004
12005 \size footnotesize
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 mov r6,#0x00
12009 \layout Standard
12010
12011
12012 \size footnotesize
12013 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
12014 \layout Standard
12015
12016
12017 \size footnotesize
12018 \SpecialChar ~
12019 \SpecialChar ~
12020 mov r7,#0x1E
12021 \layout Standard
12022
12023
12024 \size footnotesize
12025 \SpecialChar ~
12026 \SpecialChar ~
12027 mov r0,#0x00
12028 \layout Standard
12029
12030
12031 \size footnotesize
12032 ; _forcond_0($4) :
12033 \layout Standard
12034
12035
12036 \size footnotesize
12037 00104$:
12038 \layout Standard
12039
12040
12041 \size footnotesize
12042 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
12043 \layout Standard
12044
12045
12046 \size footnotesize
12047 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
12048 \layout Standard
12049
12050
12051 \size footnotesize
12052 \SpecialChar ~
12053 \SpecialChar ~
12054 clr c
12055 \layout Standard
12056
12057
12058 \size footnotesize
12059 \SpecialChar ~
12060 \SpecialChar ~
12061 mov a,r4
12062 \layout Standard
12063
12064
12065 \size footnotesize
12066 \SpecialChar ~
12067 \SpecialChar ~
12068 xrl a,#0x80
12069 \layout Standard
12070
12071
12072 \size footnotesize
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 subb a,#0x8a
12076 \layout Standard
12077
12078
12079 \size footnotesize
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 jnc 00107$
12083 \layout Standard
12084
12085
12086 \size footnotesize
12087 00115$:
12088 \layout Standard
12089
12090
12091 \size footnotesize
12092 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
12093 \layout Standard
12094
12095
12096 \size footnotesize
12097 ; iTemp21 [lr21:38]{short}[r4]
12098 \layout Standard
12099
12100
12101 \size footnotesize
12102 \SpecialChar ~
12103 \SpecialChar ~
12104 mov a,r4
12105 \layout Standard
12106
12107
12108 \size footnotesize
12109 \SpecialChar ~
12110 \SpecialChar ~
12111 add a,r2
12112 \layout Standard
12113
12114
12115 \size footnotesize
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 mov r2,a
12119 \layout Standard
12120
12121
12122 \size footnotesize
12123 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
12124 \layout Standard
12125
12126
12127 \size footnotesize
12128 \SpecialChar ~
12129 \SpecialChar ~
12130 mov b,#0x03
12131 \layout Standard
12132
12133
12134 \size footnotesize
12135 \SpecialChar ~
12136 \SpecialChar ~
12137 mov a,r4
12138 \layout Standard
12139
12140
12141 \size footnotesize
12142 \SpecialChar ~
12143 \SpecialChar ~
12144 mul ab
12145 \layout Standard
12146
12147
12148 \size footnotesize
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 mov r1,a
12152 \layout Standard
12153
12154
12155 \size footnotesize
12156 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
12157 \layout Standard
12158
12159
12160 \size footnotesize
12161 ; iTemp15 [lr29:30]{short}[r1]
12162 \layout Standard
12163
12164
12165 \size footnotesize
12166 \SpecialChar ~
12167 \SpecialChar ~
12168 add a,r3
12169 \layout Standard
12170
12171
12172 \size footnotesize
12173 \SpecialChar ~
12174 \SpecialChar ~
12175 mov r3,a
12176 \layout Standard
12177
12178
12179 \size footnotesize
12180 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
12181 \layout Standard
12182
12183
12184 \size footnotesize
12185 \SpecialChar ~
12186 \SpecialChar ~
12187 mov a,r7
12188 \layout Standard
12189
12190
12191 \size footnotesize
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 add a,#0xfd
12195 \layout Standard
12196
12197
12198 \size footnotesize
12199 \SpecialChar ~
12200 \SpecialChar ~
12201 mov r7,a
12202 \layout Standard
12203
12204
12205 \size footnotesize
12206 \SpecialChar ~
12207 \SpecialChar ~
12208 mov a,r0
12209 \layout Standard
12210
12211
12212 \size footnotesize
12213 \SpecialChar ~
12214 \SpecialChar ~
12215 addc a,#0xff
12216 \layout Standard
12217
12218
12219 \size footnotesize
12220 \SpecialChar ~
12221 \SpecialChar ~
12222 mov r0,a
12223 \layout Standard
12224
12225
12226 \size footnotesize
12227 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
12228 \layout Standard
12229
12230
12231 \size footnotesize
12232 \SpecialChar ~
12233 \SpecialChar ~
12234 mov a,r7
12235 \layout Standard
12236
12237
12238 \size footnotesize
12239 \SpecialChar ~
12240 \SpecialChar ~
12241 add a,_gint
12242 \layout Standard
12243
12244
12245 \size footnotesize
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 mov _gint,a
12249 \layout Standard
12250
12251
12252 \size footnotesize
12253 \SpecialChar ~
12254 \SpecialChar ~
12255 mov a,r0
12256 \layout Standard
12257
12258
12259 \size footnotesize
12260 \SpecialChar ~
12261 \SpecialChar ~
12262 addc a,(_gint + 1)
12263 \layout Standard
12264
12265
12266 \size footnotesize
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 mov (_gint + 1),a
12270 \layout Standard
12271
12272
12273 \size footnotesize
12274 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
12275 \layout Standard
12276
12277
12278 \size footnotesize
12279 \SpecialChar ~
12280 \SpecialChar ~
12281 inc r4
12282 \layout Standard
12283
12284
12285 \size footnotesize
12286 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
12287 \layout Standard
12288
12289
12290 \size footnotesize
12291 \SpecialChar ~
12292 \SpecialChar ~
12293 dec r5
12294 \layout Standard
12295
12296
12297 \size footnotesize
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 cjne r5,#0xff,00104$
12301 \layout Standard
12302
12303
12304 \size footnotesize
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 dec r6
12308 \layout Standard
12309
12310
12311 \size footnotesize
12312 ; goto _forcond_0($4)
12313 \layout Standard
12314
12315
12316 \size footnotesize
12317 \SpecialChar ~
12318 \SpecialChar ~
12319 sjmp 00104$
12320 \layout Standard
12321
12322
12323 \size footnotesize
12324 ; _forbreak_0($7) :
12325 \layout Standard
12326
12327
12328 \size footnotesize
12329 00107$:
12330 \layout Standard
12331
12332
12333 \size footnotesize
12334 ; ret iTemp24 [lr40:41]{short}
12335 \layout Standard
12336
12337
12338 \size footnotesize
12339 \SpecialChar ~
12340 \SpecialChar ~
12341 mov a,r3
12342 \layout Standard
12343
12344
12345 \size footnotesize
12346 \SpecialChar ~
12347 \SpecialChar ~
12348 add a,r2
12349 \layout Standard
12350
12351
12352 \size footnotesize
12353 \SpecialChar ~
12354 \SpecialChar ~
12355 mov dpl,a
12356 \layout Standard
12357
12358
12359 \size footnotesize
12360 ; _return($8) :
12361 \layout Standard
12362
12363
12364 \size footnotesize
12365 00108$:
12366 \layout Standard
12367
12368
12369 \size footnotesize
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 ret
12373 \newline
12374
12375 \layout Subsection
12376
12377 A few words about basic block successors, predecessors and dominators
12378 \layout Standard
12379
12380 Successors are basic blocks that might execute after this basic block.
12381 \newline
12382 Predecessors are basic blocks that might execute before reaching this basic
12383  block.
12384 \newline
12385 Dominators are basic blocks that WILL execute before reaching this basic
12386  block.
12387 \newline
12388
12389 \layout Standard
12390
12391 [basic block 1]
12392 \layout Standard
12393
12394 if (something)
12395 \layout Standard
12396
12397 [basic block 2]
12398 \layout Standard
12399
12400 else
12401 \layout Standard
12402
12403 [basic block 3]
12404 \layout Standard
12405
12406 [basic block 4]
12407 \newline
12408
12409 \layout Standard
12410
12411 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
12412 \layout Standard
12413
12414 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
12415 \layout Standard
12416
12417 c) domVect of [BB4] = BB1 ...
12418  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
12419  was executed.
12420 \layout Section
12421
12422 Acknowledgments
12423 \layout Standard
12424
12425
12426 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
12427
12428 \end_inset
12429
12430
12431 \newline
12432
12433 \newline
12434
12435 \emph on
12436 Thanks to all the other volunteer developers who have helped with coding,
12437  testing, web-page creation, distribution sets, etc.
12438  You know who you are :-)
12439 \emph default
12440
12441 \newline
12442
12443 \layout Standard
12444
12445 This document was initially written by Sandeep Dutta
12446 \layout Standard
12447
12448 All product names mentioned herein may be trademarks of their respective
12449  companies.
12450
12451 \layout Section
12452
12453 Alphabetical index
12454 \layout Standard
12455
12456 To avoid confusion, the installation and building options for sdcc itself
12457  (chapter 2) are not part of the index.
12458 \layout Standard
12459
12460
12461 \begin_inset LatexCommand \printindex{}
12462
12463 \end_inset
12464
12465
12466 \the_end