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