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