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