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.ihx - The load module in Intel hex format (you can select the
3270  Motorola S19 format with ---out-fmt-s19)
3271 \newline
3272 sourcefile.cdb - An optional file (with ---debug) containing debug information
3273 \newline
3274 sourcefile.dump* - Dump file to debug the compiler it self (with ---dumpall)
3275  (see section
3276 \begin_inset Quotes sld
3277 \end_inset
3278
3279 Anatomy of the compiler
3280 \begin_inset Quotes srd
3281 \end_inset
3282
3283 ).
3284 \layout Subsubsection
3285
3286 Projects with Multiple Source Files
3287 \layout Standard
3288
3289 SDCC can compile only ONE file at a time.
3290  Let us for example assume that you have a project containing the following
3291  files:
3292 \newline
3293
3294 \newline
3295 foo1.c (contains some functions)
3296 \newline
3297 foo2.c (contains some more functions)
3298 \newline
3299 foomain.c (contains more functions and the function main)
3300 \newline
3301
3302 \size footnotesize
3303
3304 \newline
3305
3306 \size default
3307 The first two files will need to be compiled separately with the commands:
3308 \size footnotesize
3309
3310 \size default
3311
3312 \newline
3313
3314 \newline
3315
3316 \family sans
3317 \series bold
3318 sdcc\SpecialChar ~
3319 -c\SpecialChar ~
3320 foo1.c
3321 \family default
3322 \series default
3323 \size footnotesize
3324
3325 \newline
3326
3327 \family sans
3328 \series bold
3329 \size default
3330 sdcc\SpecialChar ~
3331 -c\SpecialChar ~
3332 foo2.c
3333 \family default
3334 \series default
3335
3336 \newline
3337
3338 \newline
3339 Then compile the source file containing the
3340 \emph on
3341 main()
3342 \emph default
3343  function and link the files together with the following command:
3344 \newline
3345
3346 \newline
3347
3348 \family sans
3349 \series bold
3350 sdcc\SpecialChar ~
3351 foomain.c\SpecialChar ~
3352 foo1.rel\SpecialChar ~
3353 foo2.rel
3354 \family default
3355 \series default
3356
3357 \newline
3358
3359 \newline
3360 Alternatively,
3361 \emph on
3362 foomain.c
3363 \emph default
3364 can be separately compiled as well:
3365 \family sans
3366 \series bold
3367
3368 \newline
3369
3370 \newline
3371 sdcc\SpecialChar ~
3372 -c\SpecialChar ~
3373 foomain.c
3374 \newline
3375 sdcc foomain.rel foo1.rel foo2.rel
3376 \newline
3377
3378 \newline
3379
3380 \family default
3381 \series default
3382 The file containing the
3383 \emph on
3384 main()
3385 \emph default
3386  function
3387 \emph on
3388
3389 \emph default
3390 \noun on
3391 must
3392 \noun default
3393  be the
3394 \noun on
3395 first
3396 \noun default
3397  file specified in the command line, since the linkage editor processes
3398  file in the order they are presented to it.
3399 \layout Subsubsection
3400
3401 Projects with Additional Libraries
3402 \layout Standard
3403
3404 Some reusable routines may be compiled into a library, see the documentation
3405  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
3406  for how to create a
3407 \emph on
3408 .lib
3409 \emph default
3410  library file.
3411  Libraries created in this manner can be included in the command line.
3412  Make sure you include the -L <library-path> option to tell the linker where
3413  to look for these files if they are not in the current directory.
3414  Here is an example, assuming you have the source file
3415 \emph on
3416 foomain.c
3417 \emph default
3418  and a library
3419 \emph on
3420  foolib.lib
3421 \emph default
3422  in the directory
3423 \emph on
3424 mylib
3425 \emph default
3426  (if that is not the same as your current project):
3427 \newline
3428
3429 \newline
3430
3431 \family sans
3432 \series bold
3433 sdcc foomain.c foolib.lib -L mylib
3434 \newline
3435
3436 \newline
3437
3438 \family default
3439 \series default
3440 Note here that
3441 \emph on
3442  mylib
3443 \emph default
3444  must be an absolute path name.
3445 \newline
3446
3447 \newline
3448 The most efficient way to use libraries is to keep seperate modules in seperate
3449  source files.
3450  The lib file now should name all the modules.rel files.
3451  For an example see the standard library file
3452 \emph on
3453 libsdcc.lib
3454 \emph default
3455  in the directory <installdir>/share/lib/small.
3456 \layout Subsection
3457
3458 Command Line Options
3459 \layout Subsubsection
3460
3461 Processor Selection Options
3462 \layout List
3463 \labelwidthstring 00.00.0000
3464
3465
3466 \series bold
3467 -mmcs51
3468 \series default
3469  Generate code for the MCS51 (8051) family of processors.
3470  This is the default processor target.
3471 \layout List
3472 \labelwidthstring 00.00.0000
3473
3474
3475 \series bold
3476 -mds390
3477 \series default
3478  Generate code for the DS80C390 processor.
3479 \layout List
3480 \labelwidthstring 00.00.0000
3481
3482
3483 \series bold
3484 -mz80
3485 \series default
3486  Generate code for the Z80 family of processors.
3487 \layout List
3488 \labelwidthstring 00.00.0000
3489
3490
3491 \series bold
3492 -mgbz80
3493 \series default
3494  Generate code for the GameBoy Z80 processor.
3495 \layout List
3496 \labelwidthstring 00.00.0000
3497
3498
3499 \series bold
3500 -mavr
3501 \series default
3502  Generate code for the Atmel AVR processor (In development, not complete).
3503 \layout List
3504 \labelwidthstring 00.00.0000
3505
3506
3507 \series bold
3508 -mpic14
3509 \series default
3510  Generate code for the PIC 14-bit processors (In development, not complete).
3511 \layout List
3512 \labelwidthstring 00.00.0000
3513
3514
3515 \series bold
3516 -mtlcs900h
3517 \series default
3518  Generate code for the Toshiba TLCS-900H processor (In development, not
3519  complete).
3520 \layout List
3521 \labelwidthstring 00.00.0000
3522
3523
3524 \series bold
3525 -mxa51
3526 \series default
3527  Generate code for the Philips XA51 processor (In development, not complete).
3528 \layout Subsubsection
3529
3530 Preprocessor Options
3531 \layout List
3532 \labelwidthstring 00.00.0000
3533
3534
3535 \series bold
3536 -I<path>
3537 \series default
3538  The additional location where the pre processor will look for <..h> or
3539 \begin_inset Quotes eld
3540 \end_inset
3541
3542 ..h
3543 \begin_inset Quotes erd
3544 \end_inset
3545
3546  files.
3547 \layout List
3548 \labelwidthstring 00.00.0000
3549
3550
3551 \series bold
3552 -D<macro[=value]>
3553 \series default
3554  Command line definition of macros.
3555  Passed to the pre processor.
3556 \layout List
3557 \labelwidthstring 00.00.0000
3558
3559
3560 \series bold
3561 -M
3562 \series default
3563  Tell the preprocessor to output a rule suitable for make describing the
3564  dependencies of each object file.
3565  For each source file, the preprocessor outputs one make-rule whose target
3566  is the object file name for that source file and whose dependencies are
3567  all the files `#include'd in it.
3568  This rule may be a single line or may be continued with `
3569 \backslash
3570 '-newline if it is long.
3571  The list of rules is printed on standard output instead of the preprocessed
3572  C program.
3573  `-M' implies `-E'.
3574 \layout List
3575 \labelwidthstring 00.00.0000
3576
3577
3578 \series bold
3579 -C
3580 \series default
3581  Tell the preprocessor not to discard comments.
3582  Used with the `-E' option.
3583 \layout List
3584 \labelwidthstring 00.00.0000
3585
3586
3587 \series bold
3588 -MM
3589 \size large
3590 \bar under
3591
3592 \series default
3593 \size default
3594 \bar default
3595 Like `-M' but the output mentions only the user header files included with
3596  `#include
3597 \begin_inset Quotes eld
3598 \end_inset
3599
3600 file"'.
3601  System header files included with `#include <file>' are omitted.
3602 \layout List
3603 \labelwidthstring 00.00.0000
3604
3605
3606 \series bold
3607 -Aquestion(answer)
3608 \series default
3609  Assert the answer answer for question, in case it is tested with a preprocessor
3610  conditional such as `#if #question(answer)'.
3611  `-A-' disables the standard assertions that normally describe the target
3612  machine.
3613 \layout List
3614 \labelwidthstring 00.00.0000
3615
3616
3617 \series bold
3618 -Aquestion
3619 \series default
3620  (answer) Assert the answer answer for question, in case it is tested with
3621  a preprocessor conditional such as `#if #question(answer)'.
3622  `-A-' disables the standard assertions that normally describe the target
3623  machine.
3624 \layout List
3625 \labelwidthstring 00.00.0000
3626
3627
3628 \series bold
3629 -Umacro
3630 \series default
3631  Undefine macro macro.
3632  `-U' options are evaluated after all `-D' options, but before any `-include'
3633  and `-imacros' options.
3634 \layout List
3635 \labelwidthstring 00.00.0000
3636
3637
3638 \series bold
3639 -dM
3640 \series default
3641  Tell the preprocessor to output only a list of the macro definitions that
3642  are in effect at the end of preprocessing.
3643  Used with the `-E' option.
3644 \layout List
3645 \labelwidthstring 00.00.0000
3646
3647
3648 \series bold
3649 -dD
3650 \series default
3651  Tell the preprocessor to pass all macro definitions into the output, in
3652  their proper sequence in the rest of the output.
3653 \layout List
3654 \labelwidthstring 00.00.0000
3655
3656
3657 \series bold
3658 -dN
3659 \size large
3660 \bar under
3661
3662 \series default
3663 \size default
3664 \bar default
3665 Like `-dD' except that the macro arguments and contents are omitted.
3666  Only `#define name' is included in the output.
3667 \layout Subsubsection
3668
3669 Linker Options
3670 \layout List
3671 \labelwidthstring 00.00.0000
3672
3673
3674 \series bold
3675 -L\SpecialChar ~
3676 ---lib-path
3677 \bar under
3678
3679 \series default
3680 \bar default
3681 <absolute path to additional libraries> This option is passed to the linkage
3682  editor's additional libraries search path.
3683  The path name must be absolute.
3684  Additional library files may be specified in the command line.
3685  See section Compiling programs for more details.
3686 \layout List
3687 \labelwidthstring 00.00.0000
3688
3689
3690 \series bold
3691 ---xram-loc
3692 \series default
3693 <Value> The start location of the external ram, default value is 0.
3694  The value entered can be in Hexadecimal or Decimal format, e.g.: ---xram-loc
3695  0x8000 or ---xram-loc 32768.
3696 \layout List
3697 \labelwidthstring 00.00.0000
3698
3699
3700 \series bold
3701 ---code-loc
3702 \series default
3703 <Value> The start location of the code segment, default value 0.
3704  Note when this option is used the interrupt vector table is also relocated
3705  to the given address.
3706  The value entered can be in Hexadecimal or Decimal format, e.g.: ---code-loc
3707  0x8000 or ---code-loc 32768.
3708 \layout List
3709 \labelwidthstring 00.00.0000
3710
3711
3712 \series bold
3713 ---stack-loc
3714 \series default
3715 <Value> By default the stack is placed after the data segment.
3716  Using this option the stack can be placed anywhere in the internal memory
3717  space of the 8051.
3718  The value entered can be in Hexadecimal or Decimal format, e.g.
3719  ---stack-loc 0x20 or ---stack-loc 32.
3720  Since the sp register is incremented before a push or call, the initial
3721  sp will be set to one byte prior the provided value.
3722  The provided value should not overlap any other memory areas such as used
3723  register banks or the data segment and with enough space for the current
3724  application.
3725 \layout List
3726 \labelwidthstring 00.00.0000
3727
3728
3729 \series bold
3730 ---data-loc
3731 \series default
3732 <Value> The start location of the internal ram data segment.
3733  The value entered can be in Hexadecimal or Decimal format, eg.
3734  ---data-loc 0x20 or ---data-loc 32.
3735  (By default, the start location of the internal ram data segment  is set
3736  as low as possible in memory, taking into account the used register banks
3737  and the bit segment at address 0x20.
3738  For example if register banks 0 and 1 are used without bit variables, the
3739  data segment will be set, if ---data-loc is not used, to location 0x10.)
3740 \layout List
3741 \labelwidthstring 00.00.0000
3742
3743
3744 \series bold
3745 ---idata-loc
3746 \series default
3747 <Value> The start location of the indirectly addressable internal ram, default
3748  value is 0x80.
3749  The value entered can be in Hexadecimal or Decimal format, eg.
3750  ---idata-loc 0x88 or ---idata-loc 136.
3751 \layout List
3752 \labelwidthstring 00.00.0000
3753
3754
3755 \series bold
3756 ---out-fmt-ihx
3757 \bar under
3758
3759 \series default
3760 \bar default
3761 The linker output (final object code) is in Intel Hex format.
3762  (This is the default option).
3763 \layout List
3764 \labelwidthstring 00.00.0000
3765
3766
3767 \series bold
3768 ---out-fmt-s19
3769 \bar under
3770
3771 \series default
3772 \bar default
3773 The linker output (final object code) is in Motorola S19 format.
3774 \layout Subsubsection
3775
3776 MCS51 Options
3777 \layout List
3778 \labelwidthstring 00.00.0000
3779
3780
3781 \series bold
3782 ---model-large
3783 \series default
3784  Generate code for Large model programs see section Memory Models for more
3785  details.
3786  If this option is used all source files in the project should be compiled
3787  with this option.
3788  In addition the standard library routines are compiled with small model,
3789  they will need to be recompiled.
3790 \layout List
3791 \labelwidthstring 00.00.0000
3792
3793
3794 \series bold
3795 ---model-small
3796 \series default
3797 \size large
3798 \emph on
3799
3800 \size default
3801 \emph default
3802 Generate code for Small Model programs see section Memory Models for more
3803  details.
3804  This is the default model.
3805 \layout Subsubsection
3806
3807 DS390 Options
3808 \layout List
3809 \labelwidthstring 00.00.0000
3810
3811
3812 \series bold
3813 ---model-flat24
3814 \series default
3815 \size large
3816 \emph on
3817
3818 \size default
3819 \emph default
3820 Generate 24-bit flat mode code.
3821  This is the one and only that the ds390 code generator supports right now
3822  and is default when using
3823 \emph on
3824 -mds390
3825 \emph default
3826 .
3827  See section Memory Models for more details.
3828 \layout List
3829 \labelwidthstring 00.00.0000
3830
3831
3832 \series bold
3833 ---stack-10bit
3834 \series default
3835  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
3836  This is the one and only that the ds390 code generator supports right now
3837  and is default when using
3838 \emph on
3839 -mds390
3840 \emph default
3841 .
3842  In this mode, the stack is located in the lower 1K of the internal RAM,
3843  which is mapped to 0x400000.
3844  Note that the support is incomplete, since it still uses a single byte
3845  as the stack pointer.
3846  This means that only the lower 256 bytes of the potential 1K stack space
3847  will actually be used.
3848  However, this does allow you to reclaim the precious 256 bytes of low RAM
3849  for use for the DATA and IDATA segments.
3850  The compiler will not generate any code to put the processor into 10 bit
3851  stack mode.
3852  It is important to ensure that the processor is in this mode before calling
3853  any re-entrant functions compiled with this option.
3854  In principle, this should work with the
3855 \emph on
3856 ---stack-auto
3857 \emph default
3858  option, but that has not been tested.
3859  It is incompatible with the
3860 \emph on
3861 ---xstack
3862 \emph default
3863  option.
3864  It also only makes sense if the processor is in 24 bit contiguous addressing
3865  mode (see the
3866 \emph on
3867 ---model-flat24 option
3868 \emph default
3869 ).
3870 \layout Subsubsection
3871
3872 Optimization Options
3873 \layout List
3874 \labelwidthstring 00.00.0000
3875
3876
3877 \series bold
3878 ---nogcse
3879 \series default
3880  Will not do global subexpression elimination, this option may be used when
3881  the compiler creates undesirably large stack/data spaces to store compiler
3882  temporaries.
3883  A warning message will be generated when this happens and the compiler
3884  will indicate the number of extra bytes it allocated.
3885  It recommended that this option NOT be used, #pragma\SpecialChar ~
3886 NOGCSE can be used
3887  to turn off global subexpression elimination for a given function only.
3888 \layout List
3889 \labelwidthstring 00.00.0000
3890
3891
3892 \series bold
3893 ---noinvariant
3894 \series default
3895  Will not do loop invariant optimizations, this may be turned off for reasons
3896  explained for the previous option.
3897  For more details of loop optimizations performed see section Loop Invariants.It
3898  recommended that this option NOT be used, #pragma\SpecialChar ~
3899 NOINVARIANT can be used
3900  to turn off invariant optimizations for a given function only.
3901 \layout List
3902 \labelwidthstring 00.00.0000
3903
3904
3905 \series bold
3906 ---noinduction
3907 \series default
3908  Will not do loop induction optimizations, see section strength reduction
3909  for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
3910 NOINDUCT
3911 ION can be used to turn off induction optimizations for a given function
3912  only.
3913 \layout List
3914 \labelwidthstring 00.00.0000
3915
3916
3917 \series bold
3918 ---nojtbound
3919 \size large
3920 \bar under
3921
3922 \series default
3923 \size default
3924 \bar default
3925  Will not generate boundary condition check when switch statements are implement
3926 ed using jump-tables.
3927  See section Switch Statements for more details.
3928  It is recommended that this option is NOT used, #pragma\SpecialChar ~
3929 NOJTBOUND can be
3930  used to turn off boundary checking for jump tables for a given function
3931  only.
3932 \layout List
3933 \labelwidthstring 00.00.0000
3934
3935
3936 \series bold
3937 ---noloopreverse
3938 \series default
3939 \size large
3940
3941 \size default
3942 Will not do loop reversal optimization.
3943 \layout List
3944 \labelwidthstring 00.00.0000
3945
3946 ---
3947 \series bold
3948 nolabelopt
3949 \series default
3950  Will not optimize labels (makes the dumpfiles more readable).
3951 \layout List
3952 \labelwidthstring 00.00.0000
3953
3954
3955 \series bold
3956 ---no-xinit-opt
3957 \series default
3958  Will not memcpy initialized data in far space from code space.
3959  This saves a few bytes in code space if you don't have initialized data.
3960 \layout Subsubsection
3961
3962 Other Options
3963 \layout List
3964 \labelwidthstring 00.00.0000
3965
3966
3967 \series bold
3968 -c\SpecialChar ~
3969 ---compile-only
3970 \series default
3971  will compile and assemble the source, but will not call the linkage editor.
3972 \layout List
3973 \labelwidthstring 00.00.0000
3974
3975
3976 \series bold
3977 --c1mode
3978 \series default
3979  reads the preprocessed source from standard input and compiles it.
3980  The file name for the assembler output must be specified using the -o option.
3981 \layout List
3982 \labelwidthstring 00.00.0000
3983
3984
3985 \series bold
3986 -E
3987 \series default
3988  Run only the C preprocessor.
3989  Preprocess all the C source files specified and output the results to standard
3990  output.
3991 \layout List
3992 \labelwidthstring 00.00.0000
3993
3994
3995 \series bold
3996 -o\SpecialChar ~
3997 <path/file>
3998 \series default
3999 The output path resp.
4000  file where everything will be placed.
4001  If the parameter is a path, it must have a trailing slash (or backslash
4002  for the Windows binaries) to be recognized as a path.
4003
4004 \layout List
4005 \labelwidthstring 00.00.0000
4006
4007
4008 \series bold
4009 ---stack-auto
4010 \series default
4011 \size large
4012 \emph on
4013
4014 \size default
4015 \emph default
4016 All functions in the source file will be compiled as
4017 \emph on
4018 reentrant
4019 \emph default
4020 , i.e.
4021  the parameters and local variables will be allocated on the stack.
4022  see section Parameters and Local Variables for more details.
4023  If this option is used all source files in the project should be compiled
4024  with this option.
4025
4026 \layout List
4027 \labelwidthstring 00.00.0000
4028
4029
4030 \series bold
4031 ---xstack
4032 \series default
4033  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
4034  variables and passing parameters.
4035  See section on external stack for more details.
4036 \layout List
4037 \labelwidthstring 00.00.0000
4038
4039
4040 \series bold
4041 ---callee-saves function1[,function2][,function3]....
4042
4043 \series default
4044  The compiler by default uses a caller saves convention for register saving
4045  across function calls, however this can cause unneccessary register pushing
4046  & popping when calling small functions from larger functions.
4047  This option can be used to switch the register saving convention for the
4048  function names specified.
4049  The compiler will not save registers when calling these functions, no extra
4050  code will be generated at the entry & exit for these functions to save
4051  & restore the registers used by these functions, this can SUBSTANTIALLY
4052  reduce code & improve run time performance of the generated code.
4053  In the future the compiler (with interprocedural analysis) will be able
4054  to determine the appropriate scheme to use for each function call.
4055  DO NOT use this option for built-in functions such as _muluint..., if this
4056  option is used for a library function the appropriate library function
4057  needs to be recompiled with the same option.
4058  If the project consists of multiple source files then all the source file
4059  should be compiled with the same ---callee-saves option string.
4060  Also see #pragma\SpecialChar ~
4061 CALLEE-SAVES.
4062 \layout List
4063 \labelwidthstring 00.00.0000
4064
4065
4066 \series bold
4067 ---debug
4068 \bar under
4069
4070 \series default
4071 \bar default
4072 When this option is used the compiler will generate debug information, that
4073  can be used with the SDCDB.
4074  The debug information is collected in a file with .cdb extension.
4075  For more information see documentation for SDCDB.
4076 \layout List
4077 \labelwidthstring 00.00.0000
4078
4079
4080 \series bold
4081 ---peep-file
4082 \series default
4083 <filename> This option can be used to use additional rules to be used by
4084  the peep hole optimizer.
4085  See section Peep Hole optimizations for details on how to write these rules.
4086 \layout List
4087 \labelwidthstring 00.00.0000
4088
4089
4090 \series bold
4091 -S
4092 \size large
4093 \bar under
4094
4095 \series default
4096 \size default
4097 \bar default
4098 Stop after the stage of compilation proper; do not assemble.
4099  The output is an assembler code file for the input file specified.
4100 \layout List
4101 \labelwidthstring 00.00.0000
4102
4103
4104 \series bold
4105 -Wa_asmOption[,asmOption]
4106 \series default
4107 ...
4108  Pass the asmOption to the assembler.
4109 \layout List
4110 \labelwidthstring 00.00.0000
4111
4112
4113 \series bold
4114 -Wl_linkOption[,linkOption]
4115 \series default
4116 ...
4117  Pass the linkOption to the linker.
4118 \layout List
4119 \labelwidthstring 00.00.0000
4120
4121
4122 \series bold
4123 ---int-long-reent
4124 \series default
4125 \size large
4126
4127 \size default
4128  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
4129  Note by default these libraries are compiled as non-reentrant.
4130  See section Installation for more details.
4131 \layout List
4132 \labelwidthstring 00.00.0000
4133
4134
4135 \series bold
4136 ---cyclomatic
4137 \bar under
4138
4139 \series default
4140 \bar default
4141 This option will cause the compiler to generate an information message for
4142  each function in the source file.
4143  The message contains some
4144 \emph on
4145 important
4146 \emph default
4147  information about the function.
4148  The number of edges and nodes the compiler detected in the control flow
4149  graph of the function, and most importantly the
4150 \emph on
4151 cyclomatic complexity
4152 \emph default
4153  see section on Cyclomatic Complexity for more details.
4154 \layout List
4155 \labelwidthstring 00.00.0000
4156
4157
4158 \series bold
4159 ---float-reent
4160 \bar under
4161
4162 \series default
4163 \bar default
4164  Floating point library is compiled as reentrant.See section Installation
4165  for more details.
4166 \layout List
4167 \labelwidthstring 00.00.0000
4168
4169
4170 \series bold
4171 ---nooverlay
4172 \series default
4173   The compiler will not overlay parameters and local variables of any function,
4174  see section Parameters and local variables for more details.
4175 \layout List
4176 \labelwidthstring 00.00.0000
4177
4178
4179 \series bold
4180 ---main-return
4181 \series default
4182  This option can be used when the code generated is called by a monitor
4183  program.
4184  The compiler will generate a 'ret' upon return from the 'main' function.
4185  The default option is to lock up i.e.
4186  generate a 'ljmp '.
4187 \layout List
4188 \labelwidthstring 00.00.0000
4189
4190
4191 \series bold
4192 ---no-peep
4193 \series default
4194   Disable peep-hole optimization.
4195 \layout List
4196 \labelwidthstring 00.00.0000
4197
4198
4199 \series bold
4200 ---peep-asm
4201 \series default
4202   Pass the inline assembler code through the peep hole optimizer.
4203  This can cause unexpected changes to inline assembler code, please go through
4204  the peephole optimizer rules defined in the source file tree '<target>/peeph.def
4205 ' before using this option.
4206 \layout List
4207 \labelwidthstring 00.00.0000
4208
4209
4210 \series bold
4211 ---iram-size
4212 \series default
4213 <Value> Causes the linker to check if the internal ram usage is within limits
4214  of the given value.
4215 \layout List
4216 \labelwidthstring 00.00.0000
4217
4218
4219 \series bold
4220 ---xram-size
4221 \series default
4222 <Value> Causes the linker to check if the external ram usage is within limits
4223  of the given value.
4224 \layout List
4225 \labelwidthstring 00.00.0000
4226
4227
4228 \series bold
4229 ---code-size
4230 \series default
4231 <Value> Causes the linker to check if the code usage is within limits of
4232  the given value.
4233 \layout List
4234 \labelwidthstring 00.00.0000
4235
4236
4237 \series bold
4238 ---nostdincl
4239 \series default
4240  This will prevent the compiler from passing on the default include path
4241  to the preprocessor.
4242 \layout List
4243 \labelwidthstring 00.00.0000
4244
4245
4246 \series bold
4247 ---nostdlib
4248 \series default
4249  This will prevent the compiler from passing on the default library path
4250  to the linker.
4251 \layout List
4252 \labelwidthstring 00.00.0000
4253
4254
4255 \series bold
4256 ---verbose
4257 \series default
4258  Shows the various actions the compiler is performing.
4259 \layout List
4260 \labelwidthstring 00.00.0000
4261
4262
4263 \series bold
4264 -V
4265 \series default
4266  Shows the actual commands the compiler is executing.
4267 \layout List
4268 \labelwidthstring 00.00.0000
4269
4270
4271 \series bold
4272 ---no-c-code-in-asm
4273 \series default
4274  Hides your ugly and inefficient c-code from the asm file, so you can always
4275  blame the compiler :).
4276 \layout List
4277 \labelwidthstring 00.00.0000
4278
4279
4280 \series bold
4281 ---i-code-in-asm
4282 \series default
4283  Include i-codes in the asm file.
4284  Sounds like noise but is most helpfull for debugging the compiler itself.
4285 \layout List
4286 \labelwidthstring 00.00.0000
4287
4288
4289 \series bold
4290 ---less-pedantic
4291 \series default
4292  Disable some of the more pedantic warnings (jwk burps: please be more specific
4293  here, please!)
4294 \layout Subsubsection
4295
4296 Intermediate Dump Options
4297 \layout Standard
4298
4299 The following options are provided for the purpose of retargetting and debugging
4300  the compiler.
4301  These provided a means to dump the intermediate code (iCode) generated
4302  by the compiler in human readable form at various stages of the compilation
4303  process.
4304
4305 \layout List
4306 \labelwidthstring 00.00.0000
4307
4308
4309 \series bold
4310 ---dumpraw
4311 \series default
4312  This option will cause the compiler to dump the intermediate code into
4313  a file of named
4314 \emph on
4315 <source filename>.dumpraw
4316 \emph default
4317  just after the intermediate code has been generated for a function, i.e.
4318  before any optimizations are done.
4319  The basic blocks at this stage ordered in the depth first number, so they
4320  may not be in sequence of execution.
4321 \layout List
4322 \labelwidthstring 00.00.0000
4323
4324
4325 \series bold
4326 ---dumpgcse
4327 \series default
4328  Will create a dump of iCode's, after global subexpression elimination,
4329  into a file named
4330 \emph on
4331 <source filename>.dumpgcse.
4332 \layout List
4333 \labelwidthstring 00.00.0000
4334
4335
4336 \series bold
4337 ---dumpdeadcode
4338 \series default
4339  Will create a dump of iCode's, after deadcode elimination, into a file
4340  named
4341 \emph on
4342 <source filename>.dumpdeadcode.
4343 \layout List
4344 \labelwidthstring 00.00.0000
4345
4346
4347 \series bold
4348 ---dumploop
4349 \series default
4350 \size large
4351
4352 \size default
4353 Will create a dump of iCode's, after loop optimizations, into a file named
4354
4355 \emph on
4356 <source filename>.dumploop.
4357 \layout List
4358 \labelwidthstring 00.00.0000
4359
4360
4361 \series bold
4362 ---dumprange
4363 \series default
4364 \size large
4365
4366 \size default
4367 Will create a dump of iCode's, after live range analysis, into a file named
4368
4369 \emph on
4370 <source filename>.dumprange.
4371 \layout List
4372 \labelwidthstring 00.00.0000
4373
4374
4375 \series bold
4376 ---dumlrange
4377 \series default
4378  Will dump the life ranges for all symbols.
4379 \layout List
4380 \labelwidthstring 00.00.0000
4381
4382
4383 \series bold
4384 ---dumpregassign
4385 \bar under
4386
4387 \series default
4388 \bar default
4389 Will create a dump of iCode's, after register assignment, into a file named
4390
4391 \emph on
4392 <source filename>.dumprassgn.
4393 \layout List
4394 \labelwidthstring 00.00.0000
4395
4396
4397 \series bold
4398 ---dumplrange
4399 \series default
4400  Will create a dump of the live ranges of iTemp's
4401 \layout List
4402 \labelwidthstring 00.00.0000
4403
4404
4405 \series bold
4406 ---dumpall
4407 \size large
4408 \bar under
4409
4410 \series default
4411 \size default
4412 \bar default
4413 Will cause all the above mentioned dumps to be created.
4414 \layout Subsection
4415
4416 Environment variables
4417 \layout Standard
4418
4419 SDCC recognizes the following environment variables:
4420 \layout List
4421 \labelwidthstring 00.00.0000
4422
4423
4424 \series bold
4425 SDCC_LEAVE_SIGNALS
4426 \series default
4427  SDCC installs a signal handler to be able to delete temporary files after
4428  an user break (^C) or an exception.
4429  If this environment variable is set, SDCC won't install the signal handler
4430  in order to be able to debug SDCC.
4431 \layout List
4432 \labelwidthstring 00.00.0000
4433
4434
4435 \series bold
4436 TMP,\SpecialChar ~
4437 TEMP,\SpecialChar ~
4438 TMPDIR
4439 \series default
4440  Path, where temporary files will be created.
4441  The order of the variables is the search order.
4442  In a standard *nix environment these variables are not set, and there's
4443  no need to set them.
4444  On Windows it's recommended to set one of them.
4445 \layout List
4446 \labelwidthstring 00.00.0000
4447
4448
4449 \series bold
4450 SDCC_HOME
4451 \series default
4452  Path, see
4453 \begin_inset Quotes sld
4454 \end_inset
4455
4456 2.3 Install and search paths
4457 \begin_inset Quotes srd
4458 \end_inset
4459
4460 .
4461 \layout List
4462 \labelwidthstring 00.00.0000
4463
4464
4465 \series bold
4466 SDCC_INCLUDE
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_LIB
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 Standard
4494
4495 There are some more environment variables recognized by SDCC, but these
4496  are solely used for debugging purposes.
4497  They can change or disappear very quickly, and will never be documentated.
4498 \layout Subsection
4499
4500 MCS51/DS390 Storage Class Language Extensions
4501 \layout Standard
4502
4503 In addition to the ANSI storage classes SDCC allows the following MCS51
4504  specific storage classes.
4505 \layout Subsubsection
4506
4507 xdata
4508 \layout Standard
4509
4510 Variables declared with this storage class will be placed in the extern
4511  RAM.
4512  This is the
4513 \series bold
4514 default
4515 \series default
4516  storage class for Large Memory model, e.g.:
4517 \newline
4518
4519 \newline
4520
4521 \family typewriter
4522 xdata unsigned char xduc;
4523 \layout Subsubsection
4524
4525 data
4526 \layout Standard
4527
4528 This is the
4529 \series bold
4530 default
4531 \series default
4532  storage class for Small Memory model.
4533  Variables declared with this storage class will be allocated in the internal
4534  RAM, e.g.:
4535 \newline
4536
4537 \newline
4538
4539 \family typewriter
4540 data int iramdata;
4541 \layout Subsubsection
4542
4543 idata
4544 \layout Standard
4545
4546 Variables declared with this storage class will be allocated into the indirectly
4547  addressable portion of the internal ram of a 8051, e.g.:
4548 \newline
4549
4550 \newline
4551
4552 \family typewriter
4553 idata int idi;
4554 \layout Subsubsection
4555
4556 bit
4557 \layout Standard
4558
4559 This is a data-type and a storage class specifier.
4560  When a variable is declared as a bit, it is allocated into the bit addressable
4561  memory of 8051, e.g.:
4562 \newline
4563
4564 \newline
4565
4566 \family typewriter
4567 bit iFlag;
4568 \layout Subsubsection
4569
4570 sfr / sbit
4571 \layout Standard
4572
4573 Like the bit keyword,
4574 \emph on
4575 sfr / sbit
4576 \emph default
4577 signifies both a data-type and storage class, they are used to describe
4578  the special function registers and special bit variables of a 8051, eg:
4579 \newline
4580
4581 \newline
4582
4583 \family typewriter
4584 sfr at 0x80 P0; /* special function register P0 at location 0x80 */
4585 \newline
4586 sbit at 0xd7 CY; /* CY (Carry Flag) */
4587 \layout Subsection
4588
4589 Pointers
4590 \layout Standard
4591
4592 SDCC allows (via language extensions) pointers to explicitly point to any
4593  of the memory spaces of the 8051.
4594  In addition to the explicit pointers, the compiler uses (by default) generic
4595  pointers which can be used to point to any of the memory spaces.
4596 \newline
4597
4598 \newline
4599 Pointer declaration examples:
4600 \newline
4601
4602 \size small
4603
4604 \newline
4605
4606 \family typewriter
4607 \size default
4608 /* pointer physically in xternal ram pointing to object in internal ram
4609  */
4610 \newline
4611 data unsigned char * xdata p;
4612 \newline
4613
4614 \newline
4615 /* pointer physically in code rom pointing to data in xdata space */
4616 \newline
4617 xdata unsigned char * code p;
4618 \newline
4619
4620 \newline
4621 /* pointer physically in code space pointing to data in code space */
4622 \newline
4623 code unsigned char * code p;
4624 \newline
4625
4626 \newline
4627 /* the folowing is a generic pointer physically located in xdata space */
4628 \newline
4629 char * xdata p;
4630 \family default
4631 \size small
4632
4633 \newline
4634
4635 \newline
4636
4637 \size default
4638 Well you get the idea.
4639
4640 \newline
4641
4642 \newline
4643 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
4644 \emph on
4645 generic
4646 \emph default
4647  pointers.
4648
4649 \size small
4650
4651 \newline
4652
4653 \newline
4654
4655 \size default
4656 The highest order byte of the
4657 \emph on
4658 generic
4659 \emph default
4660  pointers contains the data space information.
4661  Assembler support routines are called whenever data is stored or retrieved
4662  using
4663 \emph on
4664 generic
4665 \emph default
4666  pointers.
4667  These are useful for developing reusable library routines.
4668  Explicitly specifying the pointer type will generate the most efficient
4669  code.
4670 \layout Subsection
4671
4672 Parameters & Local Variables
4673 \layout Standard
4674
4675 Automatic (local) variables and parameters to functions can either be placed
4676  on the stack or in data-space.
4677  The default action of the compiler is to place these variables in the internal
4678  RAM (for small model) or external RAM (for large model).
4679  This in fact makes them
4680 \emph on
4681 static
4682 \emph default
4683  so by default functions are non-reentrant.
4684 \newline
4685
4686 \newline
4687 They can be placed on the stack either by using the
4688 \emph on
4689  ---stack-auto
4690 \emph default
4691  option or by using the
4692 \emph on
4693 reentrant
4694 \emph default
4695  keyword in the function declaration, e.g.:
4696 \newline
4697
4698 \size small
4699
4700 \newline
4701
4702 \family typewriter
4703 \size default
4704 unsigned char foo(char i) reentrant
4705 \newline
4706 {
4707 \newline
4708 ...
4709
4710 \newline
4711 }
4712 \newline
4713
4714 \family default
4715
4716 \newline
4717 Since stack space on 8051 is limited, the
4718 \emph on
4719 reentrant
4720 \emph default
4721 keyword or the
4722 \emph on
4723  ---stack-auto
4724 \emph default
4725  option should be used sparingly.
4726  Note that the reentrant keyword just means that the parameters & local
4727  variables will be allocated to the stack, it
4728 \emph on
4729 does not
4730 \emph default
4731  mean that the function is register bank independent.
4732 \newline
4733
4734 \newline
4735 Local variables can be assigned storage classes and absolute addresses,
4736  e.g.:
4737 \newline
4738
4739 \newline
4740
4741 \family typewriter
4742 unsigned char foo() {
4743 \newline
4744 \SpecialChar ~
4745 \SpecialChar ~
4746 \SpecialChar ~
4747 \SpecialChar ~
4748 xdata unsigned char i;
4749 \newline
4750 \SpecialChar ~
4751 \SpecialChar ~
4752 \SpecialChar ~
4753 \SpecialChar ~
4754 bit bvar;
4755 \newline
4756 \SpecialChar ~
4757 \SpecialChar ~
4758 \SpecialChar ~
4759 \SpecialChar ~
4760 data at 0x31 unsiged char j;
4761 \newline
4762 \SpecialChar ~
4763 \SpecialChar ~
4764 \SpecialChar ~
4765 \SpecialChar ~
4766 ...
4767
4768 \newline
4769 }
4770 \newline
4771
4772 \newline
4773
4774 \family default
4775 In the above example the variable
4776 \emph on
4777 i
4778 \emph default
4779  will be allocated in the external ram,
4780 \emph on
4781 bvar
4782 \emph default
4783  in bit addressable space and
4784 \emph on
4785  j
4786 \emph default
4787  in internal ram.
4788  When compiled with
4789 \emph on
4790 ---stack-auto
4791 \emph default
4792  or when a function is declared as
4793 \emph on
4794 reentrant
4795 \emph default
4796  this should only be done for static variables.
4797 \layout Standard
4798
4799 Parameters however are not allowed any storage class, (storage classes for
4800  parameters will be ignored), their allocation is governed by the memory
4801  model in use, and the reentrancy options.
4802 \layout Subsection
4803
4804 Overlaying
4805 \layout Standard
4806
4807 For non-reentrant functions SDCC will try to reduce internal ram space usage
4808  by overlaying parameters and local variables of a function (if possible).
4809  Parameters and local variables of a function will be allocated to an overlayabl
4810 e segment if the function has
4811 \emph on
4812 no other function calls and the function is non-reentrant and the memory
4813  model is small.
4814
4815 \emph default
4816  If an explicit storage class is specified for a local variable, it will
4817  NOT be overlayed.
4818 \layout Standard
4819
4820 Note that the compiler (not the linkage editor) makes the decision for overlayin
4821 g the data items.
4822  Functions that are called from an interrupt service routine should be preceded
4823  by a #pragma\SpecialChar ~
4824 NOOVERLAY if they are not reentrant.
4825 \layout Standard
4826
4827 Also note that the compiler does not do any processing of inline assembler
4828  code, so the compiler might incorrectly assign local variables and parameters
4829  of a function into the overlay segment if the inline assembler code calls
4830  other c-functions that might use the overlay.
4831  In that case the #pragma\SpecialChar ~
4832 NOOVERLAY should be used.
4833 \layout Standard
4834
4835 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
4836 tion or division will NOT be overlayed since these are implemented using
4837  external functions, e.g.:
4838 \newline
4839
4840 \newline
4841
4842 \family typewriter
4843 #pragma SAVE
4844 \newline
4845 #pragma NOOVERLAY
4846 \newline
4847 void set_error(unsigned char errcd)
4848 \newline
4849 {
4850 \newline
4851 \SpecialChar ~
4852 \SpecialChar ~
4853 \SpecialChar ~
4854 \SpecialChar ~
4855 P3 = errcd;
4856 \newline
4857 }
4858 \newline
4859 #pragma RESTORE
4860 \newline
4861
4862 \newline
4863 void some_isr () interrupt 2 using 1
4864 \newline
4865 {
4866 \newline
4867 \SpecialChar ~
4868 \SpecialChar ~
4869 \SpecialChar ~
4870 \SpecialChar ~
4871 ...
4872 \newline
4873 \SpecialChar ~
4874 \SpecialChar ~
4875 \SpecialChar ~
4876 \SpecialChar ~
4877 set_error(10);
4878 \newline
4879 \SpecialChar ~
4880 \SpecialChar ~
4881 \SpecialChar ~
4882 \SpecialChar ~
4883 ...
4884
4885 \newline
4886 }
4887 \newline
4888
4889 \newline
4890
4891 \family default
4892 In the above example the parameter
4893 \emph on
4894 errcd
4895 \emph default
4896  for the function
4897 \emph on
4898 set_error
4899 \emph default
4900  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
4901 NOOVERLAY was
4902  not present, this could cause unpredictable runtime behavior when called
4903  from an ISR.
4904  The #pragma\SpecialChar ~
4905 NOOVERLAY ensures that the parameters and local variables for
4906  the function are NOT overlayed.
4907 \layout Subsection
4908
4909 Interrupt Service Routines
4910 \layout Standard
4911
4912 SDCC allows interrupt service routines to be coded in C, with some extended
4913  keywords.
4914 \newline
4915
4916 \newline
4917
4918 \family typewriter
4919 void timer_isr (void) interrupt 2 using 1
4920 \newline
4921 {
4922 \newline
4923 ..
4924
4925 \newline
4926 }
4927 \newline
4928
4929 \newline
4930
4931 \family default
4932 The number following the
4933 \emph on
4934 interrupt
4935 \emph default
4936  keyword is the interrupt number this routine will service.
4937  The compiler will insert a call to this routine in the interrupt vector
4938  table for the interrupt number specified.
4939  The
4940 \emph on
4941 using
4942 \emph default
4943  keyword is used to tell the compiler to use the specified register bank
4944  (8051 specific) when generating code for this function.
4945  Note that when some function is called from an interrupt service routine
4946  it should be preceded by a #pragma\SpecialChar ~
4947 NOOVERLAY if it is not reentrant.
4948  A special note here, int (16 bit) and long (32 bit) integer division, multiplic
4949 ation & modulus operations are implemented using external support routines
4950  developed in ANSI-C, if an interrupt service routine needs to do any of
4951  these operations then the support routines (as mentioned in a following
4952  section) will have to be recompiled using the
4953 \emph on
4954  ---stack-auto
4955 \emph default
4956  option and the source file will need to be compiled using the
4957 \emph on
4958 ---int-long-ren
4959 \emph default
4960 t compiler option.
4961 \layout Standard
4962
4963 If you have multiple source files in your project, interrupt service routines
4964  can be present in any of them, but a prototype of the isr MUST be present
4965  or included in the file that contains the function
4966 \emph on
4967 main
4968 \emph default
4969 .
4970 \layout Standard
4971
4972 Interrupt Numbers and the corresponding address & descriptions for the Standard
4973  8051 are listed below.
4974  SDCC will automatically adjust the interrupt vector table to the maximum
4975  interrupt number specified.
4976 \newline
4977
4978 \layout Standard
4979
4980
4981 \begin_inset  Tabular
4982 <lyxtabular version="3" rows="6" columns="3">
4983 <features>
4984 <column alignment="center" valignment="top" leftline="true" width="0in">
4985 <column alignment="center" valignment="top" leftline="true" width="0in">
4986 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
4987 <row topline="true" bottomline="true">
4988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4989 \begin_inset Text
4990
4991 \layout Standard
4992
4993 Interrupt #
4994 \end_inset
4995 </cell>
4996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
4997 \begin_inset Text
4998
4999 \layout Standard
5000
5001 Description
5002 \end_inset
5003 </cell>
5004 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5005 \begin_inset Text
5006
5007 \layout Standard
5008
5009 Vector Address
5010 \end_inset
5011 </cell>
5012 </row>
5013 <row topline="true">
5014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5015 \begin_inset Text
5016
5017 \layout Standard
5018
5019 0
5020 \end_inset
5021 </cell>
5022 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5023 \begin_inset Text
5024
5025 \layout Standard
5026
5027 External 0
5028 \end_inset
5029 </cell>
5030 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5031 \begin_inset Text
5032
5033 \layout Standard
5034
5035 0x0003
5036 \end_inset
5037 </cell>
5038 </row>
5039 <row topline="true">
5040 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5041 \begin_inset Text
5042
5043 \layout Standard
5044
5045 1
5046 \end_inset
5047 </cell>
5048 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5049 \begin_inset Text
5050
5051 \layout Standard
5052
5053 Timer 0
5054 \end_inset
5055 </cell>
5056 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5057 \begin_inset Text
5058
5059 \layout Standard
5060
5061 0x000B
5062 \end_inset
5063 </cell>
5064 </row>
5065 <row topline="true">
5066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5067 \begin_inset Text
5068
5069 \layout Standard
5070
5071 2
5072 \end_inset
5073 </cell>
5074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5075 \begin_inset Text
5076
5077 \layout Standard
5078
5079 External 1
5080 \end_inset
5081 </cell>
5082 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5083 \begin_inset Text
5084
5085 \layout Standard
5086
5087 0x0013
5088 \end_inset
5089 </cell>
5090 </row>
5091 <row topline="true">
5092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5093 \begin_inset Text
5094
5095 \layout Standard
5096
5097 3
5098 \end_inset
5099 </cell>
5100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5101 \begin_inset Text
5102
5103 \layout Standard
5104
5105 Timer 1
5106 \end_inset
5107 </cell>
5108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5109 \begin_inset Text
5110
5111 \layout Standard
5112
5113 0x001B
5114 \end_inset
5115 </cell>
5116 </row>
5117 <row topline="true" bottomline="true">
5118 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5119 \begin_inset Text
5120
5121 \layout Standard
5122
5123 4
5124 \end_inset
5125 </cell>
5126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
5127 \begin_inset Text
5128
5129 \layout Standard
5130
5131 Serial
5132 \end_inset
5133 </cell>
5134 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
5135 \begin_inset Text
5136
5137 \layout Standard
5138
5139 0x0023
5140 \end_inset
5141 </cell>
5142 </row>
5143 </lyxtabular>
5144
5145 \end_inset
5146
5147
5148 \newline
5149
5150 \newline
5151 If the interrupt service routine is defined without
5152 \emph on
5153 using
5154 \emph default
5155  a register bank or with register bank 0 (using 0), the compiler will save
5156  the registers used by itself on the stack upon entry and restore them at
5157  exit, however if such an interrupt service routine calls another function
5158  then the entire register bank will be saved on the stack.
5159  This scheme may be advantageous for small interrupt service routines which
5160  have low register usage.
5161 \layout Standard
5162
5163 If the interrupt service routine is defined to be using a specific register
5164  bank then only
5165 \emph on
5166 a, b & dptr
5167 \emph default
5168  are save and restored, if such an interrupt service routine calls another
5169  function (using another register bank) then the entire register bank of
5170  the called function will be saved on the stack.
5171  This scheme is recommended for larger interrupt service routines.
5172 \layout Standard
5173
5174 Calling other functions from an interrupt service routine is not recommended,
5175  avoid it if possible.
5176 \newline
5177
5178 \newline
5179 Also see the _naked modifier.
5180 \layout Subsection
5181
5182 Critical Functions
5183 \layout Standard
5184
5185
5186 \shape italic
5187 <TODO: this isn't implemented at all!>
5188 \shape default
5189
5190 \newline
5191
5192 \newline
5193 A special keyword may be associated with a function declaring it as
5194 \emph on
5195 critical
5196 \emph default
5197 .
5198  SDCC will generate code to disable all interrupts upon entry to a critical
5199  function and enable them back before returning.
5200  Note that nesting critical functions may cause unpredictable results.
5201 \newline
5202
5203 \size small
5204
5205 \newline
5206
5207 \family typewriter
5208 \size default
5209 int foo () critical
5210 \newline
5211 {
5212 \newline
5213 ...
5214
5215 \newline
5216 ...
5217
5218 \newline
5219 }
5220 \newline
5221
5222 \family default
5223
5224 \newline
5225 The critical attribute maybe used with other attributes like
5226 \emph on
5227 reentrant.
5228 \layout Subsection
5229
5230 Naked Functions
5231 \layout Standard
5232
5233 A special keyword may be associated with a function declaring it as
5234 \emph on
5235 _naked.
5236
5237 \emph default
5238 The
5239 \emph on
5240 _naked
5241 \emph default
5242  function modifier attribute prevents the compiler from generating prologue
5243  and epilogue code for that function.
5244  This means that the user is entirely responsible for such things as saving
5245  any registers that may need to be preserved, selecting the proper register
5246  bank, generating the
5247 \emph on
5248 return
5249 \emph default
5250  instruction at the end, etc.
5251  Practically, this means that the contents of the function must be written
5252  in inline assembler.
5253  This is particularly useful for interrupt functions, which can have a large
5254  (and often unnecessary) prologue/epilogue.
5255  For example, compare the code generated by these two functions:
5256 \newline
5257
5258 \newline
5259
5260 \family typewriter
5261 data unsigned char counter;
5262 \newline
5263 void simpleInterrupt(void) interrupt 1
5264 \newline
5265 {
5266 \newline
5267 \SpecialChar ~
5268 \SpecialChar ~
5269 \SpecialChar ~
5270 \SpecialChar ~
5271 counter++;
5272 \newline
5273 }
5274 \newline
5275
5276 \newline
5277 void nakedInterrupt(void) interrupt 2 _naked
5278 \newline
5279 {
5280 \newline
5281 \SpecialChar ~
5282 \SpecialChar ~
5283 \SpecialChar ~
5284 \SpecialChar ~
5285 _asm
5286 \newline
5287 \SpecialChar ~
5288 \SpecialChar ~
5289 \SpecialChar ~
5290 \SpecialChar ~
5291 \SpecialChar ~
5292 \SpecialChar ~
5293 inc\SpecialChar ~
5294 \SpecialChar ~
5295 \SpecialChar ~
5296 \SpecialChar ~
5297 \SpecialChar ~
5298 _counter
5299 \newline
5300 \SpecialChar ~
5301 \SpecialChar ~
5302 \SpecialChar ~
5303 \SpecialChar ~
5304 \SpecialChar ~
5305 \SpecialChar ~
5306 reti\SpecialChar ~
5307 \SpecialChar ~
5308 \SpecialChar ~
5309 \SpecialChar ~
5310 ; MUST explicitly include ret in _naked function.
5311 \newline
5312 \SpecialChar ~
5313 \SpecialChar ~
5314 \SpecialChar ~
5315 \SpecialChar ~
5316 _endasm;
5317 \newline
5318 }
5319 \family default
5320
5321 \newline
5322
5323 \newline
5324 For an 8051 target, the generated simpleInterrupt looks like:
5325 \newline
5326
5327 \newline
5328
5329 \family typewriter
5330 _simpleIterrupt:
5331 \newline
5332 \SpecialChar ~
5333 \SpecialChar ~
5334 \SpecialChar ~
5335 \SpecialChar ~
5336 push\SpecialChar ~
5337 \SpecialChar ~
5338 \SpecialChar ~
5339 \SpecialChar ~
5340 acc
5341 \newline
5342 \SpecialChar ~
5343 \SpecialChar ~
5344 \SpecialChar ~
5345 \SpecialChar ~
5346 push\SpecialChar ~
5347 \SpecialChar ~
5348 \SpecialChar ~
5349 \SpecialChar ~
5350 b
5351 \newline
5352 \SpecialChar ~
5353 \SpecialChar ~
5354 \SpecialChar ~
5355 \SpecialChar ~
5356 push\SpecialChar ~
5357 \SpecialChar ~
5358 \SpecialChar ~
5359 \SpecialChar ~
5360 dpl
5361 \newline
5362 \SpecialChar ~
5363 \SpecialChar ~
5364 \SpecialChar ~
5365 \SpecialChar ~
5366 push\SpecialChar ~
5367 \SpecialChar ~
5368 \SpecialChar ~
5369 \SpecialChar ~
5370 dph
5371 \newline
5372 \SpecialChar ~
5373 \SpecialChar ~
5374 \SpecialChar ~
5375 \SpecialChar ~
5376 push\SpecialChar ~
5377 \SpecialChar ~
5378 \SpecialChar ~
5379 \SpecialChar ~
5380 psw
5381 \newline
5382 \SpecialChar ~
5383 \SpecialChar ~
5384 \SpecialChar ~
5385 \SpecialChar ~
5386 mov\SpecialChar ~
5387 \SpecialChar ~
5388 \SpecialChar ~
5389 \SpecialChar ~
5390 \SpecialChar ~
5391 psw,#0x00
5392 \newline
5393 \SpecialChar ~
5394 \SpecialChar ~
5395 \SpecialChar ~
5396 \SpecialChar ~
5397 inc\SpecialChar ~
5398 \SpecialChar ~
5399 \SpecialChar ~
5400 \SpecialChar ~
5401 \SpecialChar ~
5402 _counter
5403 \newline
5404 \SpecialChar ~
5405 \SpecialChar ~
5406 \SpecialChar ~
5407 \SpecialChar ~
5408 pop\SpecialChar ~
5409 \SpecialChar ~
5410 \SpecialChar ~
5411 \SpecialChar ~
5412 \SpecialChar ~
5413 psw
5414 \newline
5415 \SpecialChar ~
5416 \SpecialChar ~
5417 \SpecialChar ~
5418 \SpecialChar ~
5419 pop\SpecialChar ~
5420 \SpecialChar ~
5421 \SpecialChar ~
5422 \SpecialChar ~
5423 \SpecialChar ~
5424 dph
5425 \newline
5426 \SpecialChar ~
5427 \SpecialChar ~
5428 \SpecialChar ~
5429 \SpecialChar ~
5430 pop\SpecialChar ~
5431 \SpecialChar ~
5432 \SpecialChar ~
5433 \SpecialChar ~
5434 \SpecialChar ~
5435 dpl
5436 \newline
5437 \SpecialChar ~
5438 \SpecialChar ~
5439 \SpecialChar ~
5440 \SpecialChar ~
5441 pop\SpecialChar ~
5442 \SpecialChar ~
5443 \SpecialChar ~
5444 \SpecialChar ~
5445 \SpecialChar ~
5446 b
5447 \newline
5448 \SpecialChar ~
5449 \SpecialChar ~
5450 \SpecialChar ~
5451 \SpecialChar ~
5452 pop\SpecialChar ~
5453 \SpecialChar ~
5454 \SpecialChar ~
5455 \SpecialChar ~
5456 \SpecialChar ~
5457 acc
5458 \newline
5459 \SpecialChar ~
5460 \SpecialChar ~
5461 \SpecialChar ~
5462 \SpecialChar ~
5463 reti
5464 \family default
5465
5466 \newline
5467
5468 \newline
5469 whereas nakedInterrupt looks like:
5470 \newline
5471
5472 \newline
5473
5474 \family typewriter
5475 _nakedInterrupt:
5476 \newline
5477 \SpecialChar ~
5478 \SpecialChar ~
5479 \SpecialChar ~
5480 \SpecialChar ~
5481 inc\SpecialChar ~
5482 \SpecialChar ~
5483 \SpecialChar ~
5484 \SpecialChar ~
5485 _counter
5486 \newline
5487 \SpecialChar ~
5488 \SpecialChar ~
5489 \SpecialChar ~
5490 \SpecialChar ~
5491 reti\SpecialChar ~
5492 \SpecialChar ~
5493 \SpecialChar ~
5494 ; MUST explicitly include ret(i) in _naked function.
5495 \family default
5496
5497 \newline
5498
5499 \newline
5500 While there is nothing preventing you from writing C code inside a _naked
5501  function, there are many ways to shoot yourself in the foot doing this,
5502  and it is recommended that you stick to inline assembler.
5503 \layout Subsection
5504
5505 Functions using private banks
5506 \layout Standard
5507
5508 The
5509 \emph on
5510 using
5511 \emph default
5512  attribute (which tells the compiler to use a register bank other than the
5513  default bank zero) should only be applied to
5514 \emph on
5515 interrupt
5516 \emph default
5517  functions (see note 1 below).
5518  This will in most circumstances make the generated ISR code more efficient
5519  since it will not have to save registers on the stack.
5520 \layout Standard
5521
5522 The
5523 \emph on
5524 using
5525 \emph default
5526  attribute will have no effect on the generated code for a
5527 \emph on
5528 non-interrupt
5529 \emph default
5530  function (but may occasionally be useful anyway
5531 \begin_inset Foot
5532 collapsed true
5533
5534 \layout Standard
5535
5536 possible exception: if a function is called ONLY from 'interrupt' functions
5537  using a particular bank, it can be declared with the same 'using' attribute
5538  as the calling 'interrupt' functions.
5539  For instance, if you have several ISRs using bank one, and all of them
5540  call memcpy(), it might make sense to create a specialized version of memcpy()
5541  'using 1', since this would prevent the ISR from having to save bank zero
5542  to the stack on entry and switch to bank zero before calling the function
5543 \end_inset
5544
5545 ).
5546 \newline
5547
5548 \emph on
5549 (pending: I don't think this has been done yet)
5550 \layout Standard
5551
5552 An
5553 \emph on
5554 interrupt
5555 \emph default
5556  function using a non-zero bank will assume that it can trash that register
5557  bank, and will not save it.
5558  Since high-priority interrupts can interrupt low-priority ones on the 8051
5559  and friends, this means that if a high-priority ISR
5560 \emph on
5561 using
5562 \emph default
5563  a particular bank occurs while processing a low-priority ISR
5564 \emph on
5565 using
5566 \emph default
5567  the same bank, terrible and bad things can happen.
5568  To prevent this, no single register bank should be
5569 \emph on
5570 used
5571 \emph default
5572  by both a high priority and a low priority ISR.
5573  This is probably most easily done by having all high priority ISRs use
5574  one bank and all low priority ISRs use another.
5575  If you have an ISR which can change priority at runtime, you're on your
5576  own: I suggest using the default bank zero and taking the small performance
5577  hit.
5578 \layout Standard
5579
5580 It is most efficient if your ISR calls no other functions.
5581  If your ISR must call other functions, it is most efficient if those functions
5582  use the same bank as the ISR (see note 1 below); the next best is if the
5583  called functions use bank zero.
5584  It is very inefficient to call a function using a different, non-zero bank
5585  from an ISR.
5586
5587 \layout Subsection
5588
5589 Absolute Addressing
5590 \layout Standard
5591
5592 Data items can be assigned an absolute address with the
5593 \emph on
5594 at <address>
5595 \emph default
5596  keyword, in addition to a storage class, e.g.:
5597 \newline
5598
5599 \newline
5600
5601 \family typewriter
5602 xdata at 0x8000 unsigned char PORTA_8255 ;
5603 \newline
5604
5605 \family default
5606
5607 \newline
5608 In the above example the PORTA_8255 will be allocated to the location 0x8000
5609  of the external ram.
5610  Note that this feature is provided to give the programmer access to
5611 \emph on
5612 memory mapped
5613 \emph default
5614  devices attached to the controller.
5615  The compiler does not actually reserve any space for variables declared
5616  in this way (they are implemented with an equate in the assembler).
5617  Thus it is left to the programmer to make sure there are no overlaps with
5618  other variables that are declared without the absolute address.
5619  The assembler listing file (.lst) and the linker output files (.rst) and
5620  (.map) are a good places to look for such overlaps.
5621 \newline
5622
5623 \newline
5624 Absolute address can be specified for variables in all storage classes,
5625  e.g.:
5626 \newline
5627
5628 \newline
5629
5630 \family typewriter
5631 bit at 0x02 bvar;
5632 \newline
5633
5634 \newline
5635
5636 \family default
5637 The above example will allocate the variable at offset 0x02 in the bit-addressab
5638 le space.
5639  There is no real advantage to assigning absolute addresses to variables
5640  in this manner, unless you want strict control over all the variables allocated.
5641 \layout Subsection
5642
5643 Startup Code
5644 \layout Standard
5645
5646 The compiler inserts a call to the C routine
5647 \emph on
5648 _sdcc__external__startup()
5649 \series bold
5650 \emph default
5651
5652 \series default
5653 at the start of the CODE area.
5654  This routine is in the runtime library.
5655  By default this routine returns 0, if this routine returns a non-zero value,
5656  the static & global variable initialization will be skipped and the function
5657  main will be invoked Other wise static & global variables will be initialized
5658  before the function main is invoked.
5659  You could add a
5660 \emph on
5661 _sdcc__external__startup()
5662 \emph default
5663  routine to your program to override the default if you need to setup hardware
5664  or perform some other critical operation prior to static & global variable
5665  initialization.
5666 \layout Subsection
5667
5668 Inline Assembler Code
5669 \layout Standard
5670
5671 SDCC allows the use of in-line assembler with a few restriction as regards
5672  labels.
5673  All labels defined within inline assembler code
5674 \emph on
5675 has to be
5676 \emph default
5677  of the form
5678 \emph on
5679 nnnnn$
5680 \emph default
5681  where nnnn is a number less than 100 (which implies a limit of utmost 100
5682  inline assembler labels
5683 \emph on
5684 per function
5685 \emph default
5686 \noun on
5687 )
5688 \noun default
5689 .
5690  It is strongly recommended that each assembly instruction (including labels)
5691  be placed in a separate line (as the example shows).
5692  When the
5693 \emph on
5694 ---peep-asm
5695 \emph default
5696  command line option is used, the inline assembler code will be passed through
5697  the peephole optimizer.
5698  This might cause some unexpected changes in the inline assembler code.
5699  Please go throught the peephole optimizer rules defined in file
5700 \emph on
5701 SDCCpeeph.def
5702 \emph default
5703  carefully before using this option.
5704 \newline
5705
5706 \newline
5707
5708 \family typewriter
5709 _asm
5710 \newline
5711 \SpecialChar ~
5712 \SpecialChar ~
5713 \SpecialChar ~
5714 \SpecialChar ~
5715 mov\SpecialChar ~
5716 \SpecialChar ~
5717 \SpecialChar ~
5718 \SpecialChar ~
5719 \SpecialChar ~
5720 b,#10
5721 \newline
5722 00001$:
5723 \newline
5724 \SpecialChar ~
5725 \SpecialChar ~
5726 \SpecialChar ~
5727 \SpecialChar ~
5728 djnz\SpecialChar ~
5729 \SpecialChar ~
5730 \SpecialChar ~
5731 \SpecialChar ~
5732 b,00001$
5733 \newline
5734 _endasm ;
5735 \family default
5736 \size small
5737
5738 \newline
5739
5740 \newline
5741
5742 \size default
5743 The inline assembler code can contain any valid code understood by the assembler
5744 , this includes any assembler directives and comment lines.
5745  The compiler does not do any validation of the code within the
5746 \family typewriter
5747 _asm ...
5748  _endasm;
5749 \family default
5750  keyword pair.
5751
5752 \newline
5753
5754 \newline
5755 Inline assembler code cannot reference any C-Labels, however it can reference
5756  labels defined by the inline assembler, e.g.:
5757 \newline
5758
5759 \newline
5760
5761 \family typewriter
5762 foo() {
5763 \newline
5764 \SpecialChar ~
5765 \SpecialChar ~
5766 \SpecialChar ~
5767 \SpecialChar ~
5768 /* some c code */
5769 \newline
5770 \SpecialChar ~
5771 \SpecialChar ~
5772 \SpecialChar ~
5773 \SpecialChar ~
5774 _asm
5775 \newline
5776 \SpecialChar ~
5777 \SpecialChar ~
5778 \SpecialChar ~
5779 \SpecialChar ~
5780 \SpecialChar ~
5781 \SpecialChar ~
5782 ; some assembler code
5783 \newline
5784 \SpecialChar ~
5785 \SpecialChar ~
5786 \SpecialChar ~
5787 \SpecialChar ~
5788 \SpecialChar ~
5789 \SpecialChar ~
5790 ljmp $0003
5791 \newline
5792 \SpecialChar ~
5793 \SpecialChar ~
5794 \SpecialChar ~
5795 \SpecialChar ~
5796 _endasm;
5797 \newline
5798 \SpecialChar ~
5799 \SpecialChar ~
5800 \SpecialChar ~
5801 \SpecialChar ~
5802 /* some more c code */
5803 \newline
5804 clabel:\SpecialChar ~
5805 \SpecialChar ~
5806 /* inline assembler cannot reference this label */
5807 \newline
5808 \SpecialChar ~
5809 \SpecialChar ~
5810 \SpecialChar ~
5811 \SpecialChar ~
5812 _asm
5813 \newline
5814 \SpecialChar ~
5815 \SpecialChar ~
5816 \SpecialChar ~
5817 \SpecialChar ~
5818 $0003: ;label (can be reference by inline assembler only)
5819 \newline
5820 \SpecialChar ~
5821 \SpecialChar ~
5822 \SpecialChar ~
5823 \SpecialChar ~
5824 _endasm ;
5825 \newline
5826 \SpecialChar ~
5827 \SpecialChar ~
5828 \SpecialChar ~
5829 \SpecialChar ~
5830 /* some more c code */
5831 \newline
5832 }
5833 \newline
5834
5835 \newline
5836
5837 \family default
5838 In other words inline assembly code can access labels defined in inline
5839  assembly within the scope of the funtion.
5840
5841 \layout Standard
5842
5843 The same goes the other way, ie.
5844  labels defines in inline assembly CANNOT be accessed by C statements.
5845 \layout Subsection
5846
5847 int (16 bit) and long (32 bit) Support
5848 \layout Standard
5849
5850 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
5851  multiplication and modulus operations are implemented by support routines.
5852  These support routines are all developed in ANSI-C to facilitate porting
5853  to other MCUs, although some model specific assembler optimations are used.
5854  The following files contain the described routine, all of them can be found
5855  in <installdir>/share/sdcc/lib.
5856 \newline
5857
5858 \newline
5859
5860 \emph on
5861 <pending: tabularise this>
5862 \emph default
5863
5864 \newline
5865
5866 \newline
5867 _mulsint.c - signed 16 bit multiplication (calls _muluint)
5868 \newline
5869 _muluint.c - unsigned 16 bit multiplication
5870 \newline
5871 _divsint.c - signed 16 bit division (calls _divuint)
5872 \newline
5873 _divuint.c - unsigned 16 bit division
5874 \newline
5875 _modsint.c - signed 16 bit modulus (call _moduint)
5876 \newline
5877 _moduint.c - unsigned 16 bit modulus
5878 \newline
5879 _mulslong.c - signed 32 bit multiplication (calls _mululong)
5880 \newline
5881 _mululong.c - unsigned32 bit multiplication
5882 \newline
5883 _divslong.c - signed 32 division (calls _divulong)
5884 \newline
5885 _divulong.c - unsigned 32 division
5886 \newline
5887 _modslong.c - signed 32 bit modulus (calls _modulong)
5888 \newline
5889 _modulong.c - unsigned 32 bit modulus
5890 \size footnotesize
5891
5892 \newline
5893
5894 \newline
5895
5896 \size default
5897 Since they are compiled as
5898 \emph on
5899 non-reentrant
5900 \emph default
5901 , interrupt service routines should not do any of the above operations.
5902  If this is unavoidable then the above routines will need to be compiled
5903  with the
5904 \emph on
5905 ---stack-auto
5906 \emph default
5907  option, after which the source program will have to be compiled with
5908 \emph on
5909 ---int-long-rent
5910 \emph default
5911  option.
5912 \layout Subsection
5913
5914 Floating Point Support
5915 \layout Standard
5916
5917 SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
5918  point support routines are derived from gcc's floatlib.c and consists of
5919  the following routines:
5920 \newline
5921
5922 \newline
5923
5924 \emph on
5925 <pending: tabularise this>
5926 \emph default
5927
5928 \newline
5929
5930 \newline
5931 _fsadd.c - add floating point numbers
5932 \newline
5933 _fssub.c - subtract floating point numbers
5934 \newline
5935 _fsdiv.c - divide floating point numbers
5936 \newline
5937 _fsmul.c - multiply floating point numbers
5938 \newline
5939 _fs2uchar.c - convert floating point to unsigned char
5940 \newline
5941 _fs2char.c - convert floating point to signed char
5942 \newline
5943 _fs2uint.c - convert floating point to unsigned int
5944 \newline
5945 _fs2int.c - convert floating point to signed int
5946 \newline
5947 _fs2ulong.c - convert floating point to unsigned long
5948 \newline
5949 _fs2long.c - convert floating point to signed long
5950 \newline
5951 _uchar2fs.c - convert unsigned char to floating point
5952 \newline
5953 _char2fs.c - convert char to floating point number
5954 \newline
5955 _uint2fs.c - convert unsigned int to floating point
5956 \newline
5957 _int2fs.c - convert int to floating point numbers
5958 \newline
5959 _ulong2fs.c - convert unsigned long to floating point number
5960 \newline
5961 _long2fs.c - convert long to floating point number
5962 \size footnotesize
5963
5964 \newline
5965
5966 \newline
5967
5968 \size default
5969 Note if all these routines are used simultaneously the data space might
5970  overflow.
5971  For serious floating point usage it is strongly recommended that the large
5972  model be used.
5973 \layout Subsection
5974
5975 MCS51 Memory Models
5976 \layout Standard
5977
5978 SDCC allows two memory models for MCS51 code, small and large.
5979  Modules compiled with different memory models should
5980 \emph on
5981 never
5982 \emph default
5983  be combined together or the results would be unpredictable.
5984  The library routines supplied with the compiler are compiled as both small
5985  and large.
5986  The compiled library modules are contained in seperate directories as small
5987  and large so that you can link to either set.
5988
5989 \layout Standard
5990
5991 When the large model is used all variables declared without a storage class
5992  will be allocated into the external ram, this includes all parameters and
5993  local variables (for non-reentrant functions).
5994  When the small model is used variables without storage class are allocated
5995  in the internal ram.
5996 \layout Standard
5997
5998 Judicious usage of the processor specific storage classes and the 'reentrant'
5999  function type will yield much more efficient code, than using the large
6000  model.
6001  Several optimizations are disabled when the program is compiled using the
6002  large model, it is therefore strongly recommdended that the small model
6003  be used unless absolutely required.
6004 \layout Subsection
6005
6006 DS390 Memory Models
6007 \layout Standard
6008
6009 The only model supported is Flat 24.
6010  This generates code for the 24 bit contiguous addressing mode of the Dallas
6011  DS80C390 part.
6012  In this mode, up to four meg of external RAM or code space can be directly
6013  addressed.
6014  See the data sheets at www.dalsemi.com for further information on this part.
6015 \newline
6016
6017 \newline
6018 In older versions of the compiler, this option was used with the MCS51 code
6019  generator (
6020 \emph on
6021 -mmcs51
6022 \emph default
6023 ).
6024  Now, however, the '390 has it's own code generator, selected by the
6025 \emph on
6026 -mds390
6027 \emph default
6028  switch.
6029
6030 \newline
6031
6032 \newline
6033 Note that the compiler does not generate any code to place the processor
6034  into 24 bitmode (although
6035 \emph on
6036 tinibios
6037 \emph default
6038  in the ds390 libraries will do that for you).
6039  If you don't use
6040 \emph on
6041 tinibios
6042 \emph default
6043 , the boot loader or similar code must ensure that the processor is in 24
6044  bit contiguous addressing mode before calling the SDCC startup code.
6045 \newline
6046
6047 \newline
6048 Like the
6049 \emph on
6050 ---model-large
6051 \emph default
6052  option, variables will by default be placed into the XDATA segment.
6053
6054 \newline
6055
6056 \newline
6057 Segments may be placed anywhere in the 4 meg address space using the usual
6058  ---*-loc options.
6059  Note that if any segments are located above 64K, the -r flag must be passed
6060  to the linker to generate the proper segment relocations, and the Intel
6061  HEX output format must be used.
6062  The -r flag can be passed to the linker by using the option
6063 \emph on
6064 -Wl-r
6065 \emph default
6066  on the sdcc command line.
6067  However, currently the linker can not handle code segments > 64k.
6068 \layout Subsection
6069
6070 Defines Created by the Compiler
6071 \layout Standard
6072
6073 The compiler creates the following #defines.
6074 \layout Itemize
6075
6076 SDCC - this Symbol is always defined.
6077 \layout Itemize
6078
6079 SDCC_mcs51 or SDCC_ds390 or SDCC_z80, etc - depending on the model used
6080  (e.g.: -mds390)
6081 \layout Itemize
6082
6083 __mcs51 or __ds390 or __z80, etc - depending on the model used (e.g.
6084  -mz80)
6085 \layout Itemize
6086
6087 SDCC_STACK_AUTO - this symbol is defined when
6088 \emph on
6089 ---stack-auto
6090 \emph default
6091  option is used.
6092 \layout Itemize
6093
6094 SDCC_MODEL_SMALL - when
6095 \emph on
6096 ---model-small
6097 \emph default
6098  is used.
6099 \layout Itemize
6100
6101 SDCC_MODEL_LARGE - when
6102 \emph on
6103 ---model-large
6104 \emph default
6105  is used.
6106 \layout Itemize
6107
6108 SDCC_USE_XSTACK - when
6109 \emph on
6110 ---xstack
6111 \emph default
6112  option is used.
6113 \layout Itemize
6114
6115 SDCC_STACK_TENBIT - when
6116 \emph on
6117 -mds390
6118 \emph default
6119  is used
6120 \layout Itemize
6121
6122 SDCC_MODEL_FLAT24 - when
6123 \emph on
6124 -mds390
6125 \emph default
6126  is used
6127 \layout Section
6128
6129 SDCC Technical Data
6130 \layout Subsection
6131
6132 Optimizations
6133 \layout Standard
6134
6135 SDCC performs a host of standard optimizations in addition to some MCU specific
6136  optimizations.
6137
6138 \layout Subsubsection
6139
6140 Sub-expression Elimination
6141 \layout Standard
6142
6143 The compiler does local and global common subexpression elimination, e.g.:
6144
6145 \newline
6146
6147 \newline
6148
6149 \family typewriter
6150 i = x + y + 1;
6151 \newline
6152 j = x + y;
6153 \family default
6154
6155 \newline
6156
6157 \newline
6158 will be translated to
6159 \newline
6160
6161 \newline
6162
6163 \family typewriter
6164 iTemp = x + y
6165 \newline
6166 i = iTemp + 1
6167 \newline
6168 j = iTemp
6169 \newline
6170
6171 \family default
6172
6173 \newline
6174 Some subexpressions are not as obvious as the above example, e.g.:
6175 \newline
6176
6177 \newline
6178
6179 \family typewriter
6180 a->b[i].c = 10;
6181 \newline
6182 a->b[i].d = 11;
6183 \family default
6184
6185 \newline
6186
6187 \newline
6188 In this case the address arithmetic a->b[i] will be computed only once;
6189  the equivalent code in C would be.
6190 \newline
6191
6192 \newline
6193
6194 \family typewriter
6195 iTemp = a->b[i];
6196 \newline
6197 iTemp.c = 10;
6198 \newline
6199 iTemp.d = 11;
6200 \family default
6201
6202 \newline
6203
6204 \newline
6205 The compiler will try to keep these temporary variables in registers.
6206 \layout Subsubsection
6207
6208 Dead-Code Elimination
6209 \layout Standard
6210
6211
6212 \family typewriter
6213 int global;
6214 \newline
6215 void f () {
6216 \newline
6217 \SpecialChar ~
6218 \SpecialChar ~
6219 int i;
6220 \newline
6221 \SpecialChar ~
6222 \SpecialChar ~
6223 i = 1; \SpecialChar ~
6224 /* dead store */
6225 \newline
6226 \SpecialChar ~
6227 \SpecialChar ~
6228 global = 1;\SpecialChar ~
6229 /* dead store */
6230 \newline
6231 \SpecialChar ~
6232 \SpecialChar ~
6233 global = 2;
6234 \newline
6235 \SpecialChar ~
6236 \SpecialChar ~
6237 return;
6238 \newline
6239 \SpecialChar ~
6240 \SpecialChar ~
6241 global = 3;\SpecialChar ~
6242 /* unreachable */
6243 \newline
6244 }
6245 \family default
6246
6247 \newline
6248
6249 \newline
6250 will be changed to
6251 \newline
6252
6253 \newline
6254
6255 \family typewriter
6256 int global; void f ()
6257 \newline
6258 {
6259 \newline
6260 \SpecialChar ~
6261 \SpecialChar ~
6262 global = 2;
6263 \newline
6264 \SpecialChar ~
6265 \SpecialChar ~
6266 return;
6267 \newline
6268 }
6269 \layout Subsubsection
6270
6271 Copy-Propagation
6272 \layout Standard
6273
6274
6275 \family typewriter
6276 int f() {
6277 \newline
6278 \SpecialChar ~
6279 \SpecialChar ~
6280 int i, j;
6281 \newline
6282 \SpecialChar ~
6283 \SpecialChar ~
6284 i = 10;
6285 \newline
6286 \SpecialChar ~
6287 \SpecialChar ~
6288 j = i;
6289 \newline
6290 \SpecialChar ~
6291 \SpecialChar ~
6292 return j;
6293 \newline
6294 }
6295 \family default
6296
6297 \newline
6298
6299 \newline
6300 will be changed to
6301 \newline
6302
6303 \newline
6304
6305 \family typewriter
6306 int f() {
6307 \newline
6308 \SpecialChar ~
6309  \SpecialChar ~
6310  int i,j;
6311 \newline
6312 \SpecialChar ~
6313  \SpecialChar ~
6314  i = 10;
6315 \newline
6316 \SpecialChar ~
6317  \SpecialChar ~
6318  j = 10;
6319 \newline
6320 \SpecialChar ~
6321  \SpecialChar ~
6322  return 10;
6323 \newline
6324 }
6325 \newline
6326
6327 \newline
6328
6329 \family default
6330 Note: the dead stores created by this copy propagation will be eliminated
6331  by dead-code elimination.
6332 \layout Subsubsection
6333
6334 Loop Optimizations
6335 \layout Standard
6336
6337 Two types of loop optimizations are done by SDCC loop invariant lifting
6338  and strength reduction of loop induction variables.
6339  In addition to the strength reduction the optimizer marks the induction
6340  variables and the register allocator tries to keep the induction variables
6341  in registers for the duration of the loop.
6342  Because of this preference of the register allocator, loop induction optimizati
6343 on causes an increase in register pressure, which may cause unwanted spilling
6344  of other temporary variables into the stack / data space.
6345  The compiler will generate a warning message when it is forced to allocate
6346  extra space either on the stack or data space.
6347  If this extra space allocation is undesirable then induction optimization
6348  can be eliminated either for the entire source file (with ---noinduction
6349  option) or for a given function only using #pragma\SpecialChar ~
6350 NOINDUCTION.
6351 \newline
6352
6353 \newline
6354 Loop Invariant:
6355 \newline
6356
6357 \newline
6358
6359 \family typewriter
6360 for (i = 0 ; i < 100 ; i ++)
6361 \newline
6362  \SpecialChar ~
6363  \SpecialChar ~
6364 f += k + l;
6365 \family default
6366
6367 \newline
6368
6369 \newline
6370 changed to
6371 \newline
6372
6373 \newline
6374
6375 \family typewriter
6376 itemp = k + l;
6377 \newline
6378 for (i = 0; i < 100; i++)
6379 \newline
6380 \SpecialChar ~
6381 \SpecialChar ~
6382 f += itemp;
6383 \family default
6384
6385 \newline
6386
6387 \newline
6388 As mentioned previously some loop invariants are not as apparent, all static
6389  address computations are also moved out of the loop.
6390 \newline
6391
6392 \newline
6393 Strength Reduction, this optimization substitutes an expression by a cheaper
6394  expression:
6395 \newline
6396
6397 \newline
6398
6399 \family typewriter
6400 for (i=0;i < 100; i++)
6401 \newline
6402 \SpecialChar ~
6403 \SpecialChar ~
6404 ar[i*5] = i*3;
6405 \family default
6406
6407 \newline
6408
6409 \newline
6410 changed to
6411 \newline
6412
6413 \newline
6414
6415 \family typewriter
6416 itemp1 = 0;
6417 \newline
6418 itemp2 = 0;
6419 \newline
6420 for (i=0;i< 100;i++) {
6421 \newline
6422  \SpecialChar ~
6423  \SpecialChar ~
6424 ar[itemp1] = itemp2;
6425 \newline
6426  \SpecialChar ~
6427  \SpecialChar ~
6428 itemp1 += 5;
6429 \newline
6430  \SpecialChar ~
6431  \SpecialChar ~
6432 itemp2 += 3;
6433 \newline
6434 }
6435 \family default
6436
6437 \newline
6438
6439 \newline
6440 The more expensive multiplication is changed to a less expensive addition.
6441 \layout Subsubsection
6442
6443 Loop Reversing
6444 \layout Standard
6445
6446 This optimization is done to reduce the overhead of checking loop boundaries
6447  for every iteration.
6448  Some simple loops can be reversed and implemented using a
6449 \begin_inset Quotes eld
6450 \end_inset
6451
6452 decrement and jump if not zero
6453 \begin_inset Quotes erd
6454 \end_inset
6455
6456  instruction.
6457  SDCC checks for the following criterion to determine if a loop is reversible
6458  (note: more sophisticated compilers use data-dependency analysis to make
6459  this determination, SDCC uses a more simple minded analysis).
6460 \layout Itemize
6461
6462 The 'for' loop is of the form
6463 \newline
6464
6465 \newline
6466
6467 \family typewriter
6468 for (<symbol> = <expression> ; <sym> [< | <=] <expression> ; [<sym>++ |
6469  <sym> += 1])
6470 \newline
6471 \SpecialChar ~
6472 \SpecialChar ~
6473 \SpecialChar ~
6474 \SpecialChar ~
6475 <for body>
6476 \layout Itemize
6477
6478 The <for body> does not contain
6479 \begin_inset Quotes eld
6480 \end_inset
6481
6482 continue
6483 \begin_inset Quotes erd
6484 \end_inset
6485
6486  or 'break
6487 \begin_inset Quotes erd
6488 \end_inset
6489
6490 .
6491 \layout Itemize
6492
6493 All goto's are contained within the loop.
6494 \layout Itemize
6495
6496 No function calls within the loop.
6497 \layout Itemize
6498
6499 The loop control variable <sym> is not assigned any value within the loop
6500 \layout Itemize
6501
6502 The loop control variable does NOT participate in any arithmetic operation
6503  within the loop.
6504 \layout Itemize
6505
6506 There are NO switch statements in the loop.
6507 \layout Subsubsection
6508
6509 Algebraic Simplifications
6510 \layout Standard
6511
6512 SDCC does numerous algebraic simplifications, the following is a small sub-set
6513  of these optimizations.
6514 \newline
6515
6516 \newline
6517
6518 \family typewriter
6519 i = j + 0 ; /* changed to */ i = j;
6520 \newline
6521 i /= 2; /* changed to */ i >>= 1;
6522 \newline
6523 i = j - j ; /* changed to */ i = 0;
6524 \newline
6525 i = j / 1 ; /* changed to */ i = j;
6526 \family default
6527
6528 \newline
6529
6530 \newline
6531 Note the subexpressions given above are generally introduced by macro expansions
6532  or as a result of copy/constant propagation.
6533 \layout Subsubsection
6534
6535 'switch' Statements
6536 \layout Standard
6537
6538 SDCC changes switch statements to jump tables when the following conditions
6539  are true.
6540
6541 \layout Itemize
6542
6543 The case labels are in numerical sequence, the labels need not be in order,
6544  and the starting number need not be one or zero.
6545 \newline
6546
6547 \newline
6548
6549 \family typewriter
6550 switch(i) {\SpecialChar ~
6551  \SpecialChar ~
6552  \SpecialChar ~
6553  \SpecialChar ~
6554  \SpecialChar ~
6555  \SpecialChar ~
6556  \SpecialChar ~
6557  \SpecialChar ~
6558  \SpecialChar ~
6559  \SpecialChar ~
6560  \SpecialChar ~
6561  \SpecialChar ~
6562  \SpecialChar ~
6563 switch (i) {
6564 \newline
6565 case 4:...
6566  \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 case 1: ...
6580
6581 \newline
6582 case 5:...
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  \SpecialChar ~
6596 case 2: ...
6597
6598 \newline
6599 case 3:...
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  \SpecialChar ~
6613 case 3: ...
6614
6615 \newline
6616 case 6:...
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  \SpecialChar ~
6630 case 4: ...
6631
6632 \newline
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  \SpecialChar ~
6647  \SpecialChar ~
6648  \SpecialChar ~
6649  \SpecialChar ~
6650  \SpecialChar ~
6651 }
6652 \newline
6653
6654 \newline
6655
6656 \family default
6657 Both the above switch statements will be implemented using a jump-table.
6658 \layout Itemize
6659
6660 The number of case labels is at least three, since it takes two conditional
6661  statements to handle the boundary conditions.
6662 \layout Itemize
6663
6664 The number of case labels is less than 84, since each label takes 3 bytes
6665  and a jump-table can be utmost 256 bytes long.
6666
6667 \layout Standard
6668
6669 Switch statements which have gaps in the numeric sequence or those that
6670  have more that 84 case labels can be split into more than one switch statement
6671  for efficient code generation, e.g.:
6672 \newline
6673
6674 \newline
6675
6676 \family typewriter
6677 switch (i) {
6678 \newline
6679 case 1: ...
6680
6681 \newline
6682 case 2: ...
6683
6684 \newline
6685 case 3: ...
6686
6687 \newline
6688 case 4: ...
6689
6690 \newline
6691 case 9: ...
6692
6693 \newline
6694 case 10: ...
6695
6696 \newline
6697 case 11: ...
6698
6699 \newline
6700 case 12: ...
6701
6702 \newline
6703 }
6704 \family default
6705
6706 \newline
6707
6708 \newline
6709 If the above switch statement is broken down into two switch statements
6710 \newline
6711
6712 \newline
6713
6714 \family typewriter
6715 switch (i) {
6716 \newline
6717 case 1: ...
6718
6719 \newline
6720 case 2: ...
6721
6722 \newline
6723 case 3: ...
6724
6725 \newline
6726 case 4: ...
6727
6728 \newline
6729 }
6730 \newline
6731
6732 \newline
6733
6734 \family default
6735 and
6736 \family typewriter
6737
6738 \newline
6739
6740 \newline
6741 switch (i) {
6742 \newline
6743 case 9: \SpecialChar ~
6744 ...
6745
6746 \newline
6747 case 10: ...
6748
6749 \newline
6750 case 11: ...
6751
6752 \newline
6753 case 12:\SpecialChar ~
6754 ...
6755
6756 \newline
6757 }
6758 \newline
6759
6760 \newline
6761
6762 \family default
6763 then both the switch statements will be implemented using jump-tables whereas
6764  the unmodified switch statement will not be.
6765 \layout Subsubsection
6766
6767 Bit-shifting Operations.
6768 \layout Standard
6769
6770 Bit shifting is one of the most frequently used operation in embedded programmin
6771 g.
6772  SDCC tries to implement bit-shift operations in the most efficient way
6773  possible, e.g.:
6774 \newline
6775
6776 \family typewriter
6777
6778 \newline
6779 unsigned char i;
6780 \newline
6781 ...
6782
6783 \newline
6784 i>>= 4;
6785 \newline
6786 ...
6787 \newline
6788
6789 \family default
6790
6791 \newline
6792 generates the following code:
6793 \newline
6794
6795 \family typewriter
6796
6797 \newline
6798 mov a,_i
6799 \newline
6800 swap a
6801 \newline
6802 anl a,#0x0f
6803 \newline
6804 mov _i,a
6805 \family default
6806
6807 \newline
6808
6809 \newline
6810 In general SDCC will never setup a loop if the shift count is known.
6811  Another example:
6812 \newline
6813
6814 \newline
6815
6816 \family typewriter
6817 unsigned int i;
6818 \newline
6819 ...
6820
6821 \newline
6822 i >>= 9;
6823 \newline
6824 ...
6825 \family default
6826
6827 \newline
6828
6829 \newline
6830 will generate:
6831 \newline
6832
6833 \newline
6834
6835 \family typewriter
6836 mov a,(_i + 1)
6837 \newline
6838 mov (_i + 1),#0x00
6839 \newline
6840 clr c
6841 \newline
6842 rrc a
6843 \newline
6844 mov _i,a
6845 \family default
6846
6847 \newline
6848
6849 \newline
6850 Note that SDCC stores numbers in little-endian format (i.e.
6851  lowest order first).
6852 \layout Subsubsection
6853
6854 Bit-rotation
6855 \layout Standard
6856
6857 A special case of the bit-shift operation is bit rotation, SDCC recognizes
6858  the following expression to be a left bit-rotation:
6859 \newline
6860
6861 \newline
6862
6863 \family typewriter
6864 unsigned char i;
6865 \newline
6866 ...
6867
6868 \newline
6869 i = ((i << 1) | (i >> 7));
6870 \family default
6871
6872 \newline
6873 ...
6874 \newline
6875
6876 \newline
6877 will generate the following code:
6878 \newline
6879
6880 \newline
6881
6882 \family typewriter
6883 mov a,_i
6884 \newline
6885 rl a
6886 \newline
6887 mov _i,a
6888 \family default
6889
6890 \newline
6891
6892 \newline
6893 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
6894 ns of this case will also be recognized as bit-rotation, i.e.:
6895 \newline
6896
6897 \newline
6898
6899 \family typewriter
6900 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
6901 \layout Subsubsection
6902
6903 Highest Order Bit
6904 \layout Standard
6905
6906 It is frequently required to obtain the highest order bit of an integral
6907  type (long, int, short or char types).
6908  SDCC recognizes the following expression to yield the highest order bit
6909  and generates optimized code for it, e.g.:
6910 \newline
6911
6912 \newline
6913
6914 \family typewriter
6915 unsigned int gint;
6916 \newline
6917
6918 \newline
6919 foo () {
6920 \newline
6921 unsigned char hob;
6922 \newline
6923 \SpecialChar ~
6924 \SpecialChar ~
6925 ...
6926
6927 \newline
6928 \SpecialChar ~
6929 \SpecialChar ~
6930 hob = (gint >> 15) & 1;
6931 \newline
6932 \SpecialChar ~
6933 \SpecialChar ~
6934 ..
6935
6936 \newline
6937 }
6938 \family default
6939
6940 \newline
6941
6942 \newline
6943 will generate the following code:
6944 \newline
6945
6946 \family typewriter
6947
6948 \newline
6949 \SpecialChar ~
6950 \SpecialChar ~
6951 \SpecialChar ~
6952 \SpecialChar ~
6953 \SpecialChar ~
6954 \SpecialChar ~
6955 \SpecialChar ~
6956 \SpecialChar ~
6957 \SpecialChar ~
6958 \SpecialChar ~
6959 \SpecialChar ~
6960 \SpecialChar ~
6961 \SpecialChar ~
6962 \SpecialChar ~
6963 \SpecialChar ~
6964 \SpecialChar ~
6965 \SpecialChar ~
6966 \SpecialChar ~
6967 \SpecialChar ~
6968 \SpecialChar ~
6969 \SpecialChar ~
6970 \SpecialChar ~
6971 \SpecialChar ~
6972 \SpecialChar ~
6973 \SpecialChar ~
6974 \SpecialChar ~
6975 \SpecialChar ~
6976 \SpecialChar ~
6977  61 ;\SpecialChar ~
6978  hob.c 7
6979 \newline
6980 \SpecialChar ~
6981 \SpecialChar ~
6982  000A E5*01\SpecialChar ~
6983 \SpecialChar ~
6984 \SpecialChar ~
6985 \SpecialChar ~
6986 \SpecialChar ~
6987 \SpecialChar ~
6988 \SpecialChar ~
6989 \SpecialChar ~
6990 \SpecialChar ~
6991 \SpecialChar ~
6992 \SpecialChar ~
6993 \SpecialChar ~
6994 \SpecialChar ~
6995 \SpecialChar ~
6996 \SpecialChar ~
6997  62\SpecialChar ~
6998 \SpecialChar ~
6999 \SpecialChar ~
7000 \SpecialChar ~
7001 \SpecialChar ~
7002 \SpecialChar ~
7003 \SpecialChar ~
7004 \SpecialChar ~
7005  mov\SpecialChar ~
7006  a,(_gint + 1)
7007 \newline
7008 \SpecialChar ~
7009 \SpecialChar ~
7010  000C 33\SpecialChar ~
7011 \SpecialChar ~
7012 \SpecialChar ~
7013 \SpecialChar ~
7014 \SpecialChar ~
7015 \SpecialChar ~
7016 \SpecialChar ~
7017 \SpecialChar ~
7018 \SpecialChar ~
7019 \SpecialChar ~
7020 \SpecialChar ~
7021 \SpecialChar ~
7022 \SpecialChar ~
7023 \SpecialChar ~
7024 \SpecialChar ~
7025 \SpecialChar ~
7026 \SpecialChar ~
7027 \SpecialChar ~
7028  63\SpecialChar ~
7029 \SpecialChar ~
7030 \SpecialChar ~
7031 \SpecialChar ~
7032 \SpecialChar ~
7033 \SpecialChar ~
7034 \SpecialChar ~
7035 \SpecialChar ~
7036  rlc\SpecialChar ~
7037  a
7038 \newline
7039 \SpecialChar ~
7040 \SpecialChar ~
7041  000D E4\SpecialChar ~
7042 \SpecialChar ~
7043 \SpecialChar ~
7044 \SpecialChar ~
7045 \SpecialChar ~
7046 \SpecialChar ~
7047 \SpecialChar ~
7048 \SpecialChar ~
7049 \SpecialChar ~
7050 \SpecialChar ~
7051 \SpecialChar ~
7052 \SpecialChar ~
7053 \SpecialChar ~
7054 \SpecialChar ~
7055 \SpecialChar ~
7056 \SpecialChar ~
7057 \SpecialChar ~
7058 \SpecialChar ~
7059  64\SpecialChar ~
7060 \SpecialChar ~
7061 \SpecialChar ~
7062 \SpecialChar ~
7063 \SpecialChar ~
7064 \SpecialChar ~
7065 \SpecialChar ~
7066 \SpecialChar ~
7067  clr\SpecialChar ~
7068  a
7069 \newline
7070 \SpecialChar ~
7071 \SpecialChar ~
7072  000E 13\SpecialChar ~
7073 \SpecialChar ~
7074 \SpecialChar ~
7075 \SpecialChar ~
7076 \SpecialChar ~
7077 \SpecialChar ~
7078 \SpecialChar ~
7079 \SpecialChar ~
7080 \SpecialChar ~
7081 \SpecialChar ~
7082 \SpecialChar ~
7083 \SpecialChar ~
7084 \SpecialChar ~
7085 \SpecialChar ~
7086 \SpecialChar ~
7087 \SpecialChar ~
7088 \SpecialChar ~
7089 \SpecialChar ~
7090  65\SpecialChar ~
7091 \SpecialChar ~
7092 \SpecialChar ~
7093 \SpecialChar ~
7094 \SpecialChar ~
7095 \SpecialChar ~
7096 \SpecialChar ~
7097 \SpecialChar ~
7098  rrc\SpecialChar ~
7099  a
7100 \newline
7101 \SpecialChar ~
7102 \SpecialChar ~
7103  000F F5*02\SpecialChar ~
7104 \SpecialChar ~
7105 \SpecialChar ~
7106 \SpecialChar ~
7107 \SpecialChar ~
7108 \SpecialChar ~
7109 \SpecialChar ~
7110 \SpecialChar ~
7111 \SpecialChar ~
7112 \SpecialChar ~
7113 \SpecialChar ~
7114 \SpecialChar ~
7115 \SpecialChar ~
7116 \SpecialChar ~
7117 \SpecialChar ~
7118  66\SpecialChar ~
7119 \SpecialChar ~
7120 \SpecialChar ~
7121 \SpecialChar ~
7122 \SpecialChar ~
7123 \SpecialChar ~
7124 \SpecialChar ~
7125 \SpecialChar ~
7126  mov\SpecialChar ~
7127  _foo_hob_1_1,a
7128 \newline
7129
7130 \newline
7131
7132 \family default
7133 Variations of this case however will
7134 \emph on
7135 not
7136 \emph default
7137  be recognized.
7138  It is a standard C expression, so I heartily recommend this be the only
7139  way to get the highest order bit, (it is portable).
7140  Of course it will be recognized even if it is embedded in other expressions,
7141  e.g.:
7142 \newline
7143
7144 \newline
7145
7146 \family typewriter
7147 xyz = gint + ((gint >> 15) & 1);
7148 \family default
7149
7150 \newline
7151
7152 \newline
7153 will still be recognized.
7154 \layout Subsubsection
7155
7156 Peep-hole Optimizer
7157 \layout Standard
7158
7159 The compiler uses a rule based, pattern matching and re-writing mechanism
7160  for peep-hole optimization.
7161  It is inspired by
7162 \emph on
7163 copt
7164 \emph default
7165  a peep-hole optimizer by Christopher W.
7166  Fraser (cwfraser@microsoft.com).
7167  A default set of rules are compiled into the compiler, additional rules
7168  may be added with the
7169 \emph on
7170 ---peep-file <filename>
7171 \emph default
7172  option.
7173  The rule language is best illustrated with examples.
7174 \newline
7175
7176 \newline
7177
7178 \family typewriter
7179 replace {
7180 \newline
7181 \SpecialChar ~
7182 \SpecialChar ~
7183 mov %1,a
7184 \newline
7185 \SpecialChar ~
7186 \SpecialChar ~
7187 mov a,%1
7188 \newline
7189 } by {
7190 \newline
7191 \SpecialChar ~
7192 \SpecialChar ~
7193 mov %1,a
7194 \newline
7195 }
7196 \family default
7197
7198 \newline
7199
7200 \newline
7201 The above rule will change the following assembly sequence:
7202 \newline
7203
7204 \newline
7205
7206 \family typewriter
7207 \SpecialChar ~
7208 \SpecialChar ~
7209 mov r1,a
7210 \newline
7211 \SpecialChar ~
7212 \SpecialChar ~
7213 mov a,r1
7214 \family default
7215
7216 \newline
7217
7218 \newline
7219 to
7220 \newline
7221
7222 \newline
7223
7224 \family typewriter
7225 mov r1,a
7226 \family default
7227
7228 \newline
7229
7230 \newline
7231 Note: All occurrences of a
7232 \emph on
7233 %n
7234 \emph default
7235  (pattern variable) must denote the same string.
7236  With the above rule, the assembly sequence:
7237 \newline
7238
7239 \newline
7240
7241 \family typewriter
7242 \SpecialChar ~
7243 \SpecialChar ~
7244 mov r1,a
7245 \newline
7246 \SpecialChar ~
7247 \SpecialChar ~
7248 mov a,r2
7249 \family default
7250
7251 \newline
7252
7253 \newline
7254 will remain unmodified.
7255 \newline
7256
7257 \newline
7258 Other special case optimizations may be added by the user (via
7259 \emph on
7260 ---peep-file option
7261 \emph default
7262 ).
7263  E.g.
7264  some variants of the 8051 MCU allow only
7265 \family typewriter
7266 ajmp
7267 \family default
7268  and
7269 \family typewriter
7270 acall
7271 \family default
7272 .
7273  The following two rules will change all
7274 \family typewriter
7275 ljmp
7276 \family default
7277  and
7278 \family typewriter
7279 lcall
7280 \family default
7281  to
7282 \family typewriter
7283 ajmp
7284 \family default
7285  and
7286 \family typewriter
7287 acall
7288 \family default
7289
7290 \newline
7291
7292 \newline
7293
7294 \family typewriter
7295 replace { lcall %1 } by { acall %1 }
7296 \newline
7297 replace { ljmp %1 } by { ajmp %1 }
7298 \family default
7299
7300 \newline
7301
7302 \newline
7303 The
7304 \emph on
7305 inline-assembler code
7306 \emph default
7307  is also passed through the peep hole optimizer, thus the peephole optimizer
7308  can also be used as an assembly level macro expander.
7309  The rules themselves are MCU dependent whereas the rule language infra-structur
7310 e is MCU independent.
7311  Peephole optimization rules for other MCU can be easily programmed using
7312  the rule language.
7313 \newline
7314
7315 \newline
7316 The syntax for a rule is as follows:
7317 \newline
7318
7319 \newline
7320
7321 \family typewriter
7322 rule := replace [ restart ] '{' <assembly sequence> '
7323 \backslash
7324 n'
7325 \newline
7326 \SpecialChar ~
7327  \SpecialChar ~
7328  \SpecialChar ~
7329  \SpecialChar ~
7330  \SpecialChar ~
7331  \SpecialChar ~
7332  \SpecialChar ~
7333  \SpecialChar ~
7334  \SpecialChar ~
7335  \SpecialChar ~
7336  \SpecialChar ~
7337  \SpecialChar ~
7338  \SpecialChar ~
7339  \SpecialChar ~
7340  '}' by '{' '
7341 \backslash
7342 n'
7343 \newline
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  \SpecialChar ~
7357  \SpecialChar ~
7358  \SpecialChar ~
7359  \SpecialChar ~
7360  <assembly sequence> '
7361 \backslash
7362 n'
7363 \newline
7364 \SpecialChar ~
7365  \SpecialChar ~
7366  \SpecialChar ~
7367  \SpecialChar ~
7368  \SpecialChar ~
7369  \SpecialChar ~
7370  \SpecialChar ~
7371  \SpecialChar ~
7372  \SpecialChar ~
7373  \SpecialChar ~
7374  \SpecialChar ~
7375  \SpecialChar ~
7376  \SpecialChar ~
7377  \SpecialChar ~
7378  '}' [if <functionName> ] '
7379 \backslash
7380 n'
7381 \newline
7382
7383 \family default
7384
7385 \newline
7386 <assembly sequence> := assembly instruction (each instruction including
7387  labels must be on a separate line).
7388 \newline
7389
7390 \newline
7391 The optimizer will apply to the rules one by one from the top in the sequence
7392  of their appearance, it will terminate when all rules are exhausted.
7393  If the 'restart' option is specified, then the optimizer will start matching
7394  the rules again from the top, this option for a rule is expensive (performance)
7395 , it is intended to be used in situations where a transformation will trigger
7396  the same rule again.
7397  An example of this (not a good one, it has side effects) is the following
7398  rule:
7399 \newline
7400
7401 \newline
7402
7403 \family typewriter
7404 replace restart {
7405 \newline
7406 \SpecialChar ~
7407 \SpecialChar ~
7408 pop %1
7409 \newline
7410 \SpecialChar ~
7411 \SpecialChar ~
7412 push %1 } by {
7413 \newline
7414 \SpecialChar ~
7415 \SpecialChar ~
7416 ; nop
7417 \newline
7418 }
7419 \family default
7420
7421 \newline
7422
7423 \newline
7424 Note that the replace pattern cannot be a blank, but can be a comment line.
7425  Without the 'restart' option only the inner most 'pop' 'push' pair would
7426  be eliminated, i.e.:
7427 \newline
7428
7429 \newline
7430
7431 \family typewriter
7432 \SpecialChar ~
7433 \SpecialChar ~
7434 pop ar1
7435 \newline
7436 \SpecialChar ~
7437 \SpecialChar ~
7438 pop ar2
7439 \newline
7440 \SpecialChar ~
7441 \SpecialChar ~
7442 push ar2
7443 \newline
7444 \SpecialChar ~
7445 \SpecialChar ~
7446 push ar1
7447 \family default
7448
7449 \newline
7450
7451 \newline
7452 would result in:
7453 \newline
7454
7455 \newline
7456
7457 \family typewriter
7458 \SpecialChar ~
7459 \SpecialChar ~
7460 pop ar1
7461 \newline
7462 \SpecialChar ~
7463 \SpecialChar ~
7464 ; nop
7465 \newline
7466 \SpecialChar ~
7467 \SpecialChar ~
7468 push ar1
7469 \family default
7470
7471 \newline
7472
7473 \newline
7474
7475 \emph on
7476 with
7477 \emph default
7478  the restart option the rule will be applied again to the resulting code
7479  and then all the pop-push pairs will be eliminated to yield:
7480 \newline
7481
7482 \newline
7483
7484 \family typewriter
7485 \SpecialChar ~
7486 \SpecialChar ~
7487 ; nop
7488 \newline
7489 \SpecialChar ~
7490 \SpecialChar ~
7491 ; nop
7492 \family default
7493
7494 \newline
7495
7496 \newline
7497 A conditional function can be attached to a rule.
7498  Attaching rules are somewhat more involved, let me illustrate this with
7499  an example.
7500 \newline
7501
7502 \newline
7503
7504 \family typewriter
7505 replace {
7506 \newline
7507 \SpecialChar ~
7508  \SpecialChar ~
7509  \SpecialChar ~
7510 ljmp %5
7511 \newline
7512 %2:
7513 \newline
7514 } by {
7515 \newline
7516 \SpecialChar ~
7517  \SpecialChar ~
7518  \SpecialChar ~
7519 sjmp %5
7520 \newline
7521 %2:
7522 \newline
7523 } if labelInRange
7524 \family default
7525
7526 \newline
7527
7528 \newline
7529 The optimizer does a look-up of a function name table defined in function
7530
7531 \emph on
7532 callFuncByName
7533 \emph default
7534  in the source file SDCCpeeph.c, with the name
7535 \emph on
7536 labelInRange
7537 \emph default
7538 .
7539  If it finds a corresponding entry the function is called.
7540  Note there can be no parameters specified for these functions, in this
7541  case the use of
7542 \emph on
7543 %5
7544 \emph default
7545  is crucial, since the function
7546 \emph on
7547 labelInRange
7548 \emph default
7549  expects to find the label in that particular variable (the hash table containin
7550 g the variable bindings is passed as a parameter).
7551  If you want to code more such functions, take a close look at the function
7552  labelInRange and the calling mechanism in source file SDCCpeeph.c.
7553  I know this whole thing is a little kludgey, but maybe some day we will
7554  have some better means.
7555  If you are looking at this file, you will also see the default rules that
7556  are compiled into the compiler, you can add your own rules in the default
7557  set there if you get tired of specifying the ---peep-file option.
7558 \layout Subsection
7559
7560 Pragmas
7561 \layout Standard
7562
7563 SDCC supports the following #pragma directives.
7564 \layout Itemize
7565
7566 SAVE - this will save all current options to the SAVE/RESTORE stack.
7567  See RESTORE.
7568 \layout Itemize
7569
7570 RESTORE - will restore saved options from the last save.
7571  SAVEs & RESTOREs can be nested.
7572  SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
7573  RESTORE pulls current options from the stack.
7574  See SAVE.
7575 \layout Itemize
7576
7577 NOGCSE - will stop global subexpression elimination.
7578 \layout Itemize
7579
7580 NOINDUCTION - will stop loop induction optimizations.
7581 \layout Itemize
7582
7583 NOJTBOUND - will not generate code for boundary value checking, when switch
7584  statements are turned into jump-tables.
7585 \layout Itemize
7586
7587 NOOVERLAY - the compiler will not overlay the parameters and local variables
7588  of a function.
7589 \layout Itemize
7590
7591 LESS_PEDANTIC - the compiler will not warn you anymore for obvious mistakes,
7592  you'r on your own now ;-(
7593 \layout Itemize
7594
7595 NOLOOPREVERSE - Will not do loop reversal optimization
7596 \layout Itemize
7597
7598 EXCLUDE NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation
7599  of pair of push/pop instruction in ISR function (using interrupt keyword).
7600  The directive should be placed immediately before the ISR function definition
7601  and it affects ALL ISR functions following it.
7602  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
7603 EXCLUDE\SpecialChar ~
7604 none.
7605 \layout Itemize
7606
7607 NOIV - Do not generate interrupt vector table entries for all ISR functions
7608  defined after the pragma.
7609  This is useful in cases where the interrupt vector table must be defined
7610  manually, or when there is a secondary, manually defined interrupt vector
7611  table (e.g.
7612  for the autovector feature of the Cypress EZ-USB FX2).
7613 \layout Itemize
7614
7615 CALLEE-SAVES function1[,function2[,function3...]] - The compiler by default
7616  uses a caller saves convention for register saving across function calls,
7617  however this can cause unneccessary register pushing & popping when calling
7618  small functions from larger functions.
7619  This option can be used to switch off the register saving convention for
7620  the function names specified.
7621  The compiler will not save registers when calling these functions, extra
7622  code need to be manually inserted at the entry & exit for these functions
7623  to save & restore the registers used by these functions, this can SUBSTANTIALLY
7624  reduce code & improve run time performance of the generated code.
7625  In the future the compiler (with interprocedural analysis) may be able
7626  to determine the appropriate scheme to use for each function call.
7627  If ---callee-saves command line option is used, the function names specified
7628  in #pragma\SpecialChar ~
7629 CALLEE-SAVES is appended to the list of functions specified in
7630  the command line.
7631 \layout Standard
7632
7633 The pragma's are intended to be used to turn-off certain optimizations which
7634  might cause the compiler to generate extra stack / data space to store
7635  compiler generated temporary variables.
7636  This usually happens in large functions.
7637  Pragma directives should be used as shown in the following example, they
7638  are used to control options & optimizations for a given function; pragmas
7639  should be placed before and/or after a function, placing pragma's inside
7640  a function body could have unpredictable results.
7641 \newline
7642
7643 \newline
7644
7645 \family typewriter
7646 #pragma SAVE /* save the current settings */
7647 \newline
7648 #pragma NOGCSE /* turnoff global subexpression elimination */
7649 \newline
7650 #pragma NOINDUCTION /* turn off induction optimizations */
7651 \newline
7652 int foo ()
7653 \newline
7654 {
7655 \newline
7656 \SpecialChar ~
7657  \SpecialChar ~
7658  ...
7659
7660 \newline
7661 \SpecialChar ~
7662  \SpecialChar ~
7663  /* large code */
7664 \newline
7665 \SpecialChar ~
7666  \SpecialChar ~
7667  ...
7668
7669 \newline
7670 }
7671 \newline
7672 #pragma RESTORE /* turn the optimizations back on */
7673 \family default
7674
7675 \newline
7676
7677 \newline
7678 The compiler will generate a warning message when extra space is allocated.
7679  It is strongly recommended that the SAVE and RESTORE pragma's be used when
7680  changing options for a function.
7681 \layout Subsection
7682
7683
7684 \emph on
7685 <pending: this is messy and incomplete>
7686 \emph default
7687  Library Routines
7688 \layout Enumerate
7689
7690 Compiler support routines (_gptrget, _mulint etc)
7691 \layout Enumerate
7692
7693 Stdclib functions (puts, printf, strcat etc)
7694 \layout Enumerate
7695
7696 Math functions (sin, pow, sqrt etc)
7697 \layout Subsection
7698
7699 Interfacing with Assembly Routines
7700 \layout Subsubsection
7701
7702 Global Registers used for Parameter Passing
7703 \layout Standard
7704
7705 The compiler always uses the global registers
7706 \emph on
7707 DPL,DPH,B
7708 \emph default
7709 and
7710 \emph on
7711  ACC
7712 \emph default
7713  to pass the first parameter to a routine.
7714  The second parameter onwards is either allocated on the stack (for reentrant
7715  routines or if ---stack-auto is used) or in the internal / external ram
7716  (depending on the memory model).
7717
7718 \layout Subsubsection
7719
7720 Assembler Routine(non-reentrant)
7721 \layout Standard
7722
7723 In the following example the function cfunc calls an assembler routine asm_func,
7724  which takes two parameters.
7725 \newline
7726
7727 \newline
7728
7729 \family typewriter
7730 extern int asm_func(unsigned char, unsigned char);
7731 \newline
7732
7733 \newline
7734 int c_func (unsigned char i, unsigned char j)
7735 \newline
7736 {
7737 \newline
7738 \SpecialChar ~
7739 \SpecialChar ~
7740 \SpecialChar ~
7741 \SpecialChar ~
7742 return asm_func(i,j);
7743 \newline
7744 }
7745 \newline
7746
7747 \newline
7748 int main()
7749 \newline
7750 {
7751 \newline
7752 \SpecialChar ~
7753 \SpecialChar ~
7754 \SpecialChar ~
7755 \SpecialChar ~
7756 return c_func(10,9);
7757 \newline
7758 }
7759 \newline
7760
7761 \newline
7762
7763 \family default
7764 The corresponding assembler function is:
7765 \newline
7766
7767 \newline
7768
7769 \family typewriter
7770 .globl _asm_func_PARM_2
7771 \newline
7772 \SpecialChar ~
7773 \SpecialChar ~
7774 \SpecialChar ~
7775 \SpecialChar ~
7776 \SpecialChar ~
7777 \SpecialChar ~
7778 \SpecialChar ~
7779 \SpecialChar ~
7780 .globl _asm_func
7781 \newline
7782 \SpecialChar ~
7783 \SpecialChar ~
7784 \SpecialChar ~
7785 \SpecialChar ~
7786 \SpecialChar ~
7787 \SpecialChar ~
7788 \SpecialChar ~
7789 \SpecialChar ~
7790 .area OSEG
7791 \newline
7792 _asm_func_PARM_2:
7793 \newline
7794 \SpecialChar ~
7795 \SpecialChar ~
7796 \SpecialChar ~
7797 \SpecialChar ~
7798 \SpecialChar ~
7799 \SpecialChar ~
7800 \SpecialChar ~
7801 \SpecialChar ~
7802 .ds      1
7803 \newline
7804 \SpecialChar ~
7805 \SpecialChar ~
7806 \SpecialChar ~
7807 \SpecialChar ~
7808 \SpecialChar ~
7809 \SpecialChar ~
7810 \SpecialChar ~
7811 \SpecialChar ~
7812 .area CSEG
7813 \newline
7814 _asm_func:
7815 \newline
7816 \SpecialChar ~
7817 \SpecialChar ~
7818 \SpecialChar ~
7819 \SpecialChar ~
7820 \SpecialChar ~
7821 \SpecialChar ~
7822 \SpecialChar ~
7823 \SpecialChar ~
7824 mov     a,dpl
7825 \newline
7826 \SpecialChar ~
7827 \SpecialChar ~
7828 \SpecialChar ~
7829 \SpecialChar ~
7830 \SpecialChar ~
7831 \SpecialChar ~
7832 \SpecialChar ~
7833 \SpecialChar ~
7834 add     a,_asm_func_PARM_2
7835 \newline
7836 \SpecialChar ~
7837 \SpecialChar ~
7838 \SpecialChar ~
7839 \SpecialChar ~
7840 \SpecialChar ~
7841 \SpecialChar ~
7842 \SpecialChar ~
7843 \SpecialChar ~
7844 mov     dpl,a
7845 \newline
7846 \SpecialChar ~
7847 \SpecialChar ~
7848 \SpecialChar ~
7849 \SpecialChar ~
7850 \SpecialChar ~
7851 \SpecialChar ~
7852 \SpecialChar ~
7853 \SpecialChar ~
7854 mov     dpl,#0x00
7855 \newline
7856 \SpecialChar ~
7857 \SpecialChar ~
7858 \SpecialChar ~
7859 \SpecialChar ~
7860 \SpecialChar ~
7861 \SpecialChar ~
7862 \SpecialChar ~
7863 \SpecialChar ~
7864 ret
7865 \newline
7866
7867 \newline
7868
7869 \family default
7870 Note here that the return values are placed in 'dpl' - One byte return value,
7871  'dpl' LSB & 'dph' MSB for two byte values.
7872  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
7873 b' & 'acc' for four byte values.
7874 \layout Standard
7875
7876 The parameter naming convention is _<function_name>_PARM_<n>, where n is
7877  the parameter number starting from 1, and counting from the left.
7878  The first parameter is passed in
7879 \begin_inset Quotes eld
7880 \end_inset
7881
7882 dpl
7883 \begin_inset Quotes erd
7884 \end_inset
7885
7886  for One bye parameter,
7887 \begin_inset Quotes eld
7888 \end_inset
7889
7890 dptr
7891 \begin_inset Quotes erd
7892 \end_inset
7893
7894  if two bytes,
7895 \begin_inset Quotes eld
7896 \end_inset
7897
7898 b,dptr
7899 \begin_inset Quotes erd
7900 \end_inset
7901
7902  for three bytes and
7903 \begin_inset Quotes eld
7904 \end_inset
7905
7906 acc,b,dptr
7907 \begin_inset Quotes erd
7908 \end_inset
7909
7910  for four bytes, the varible name for the second parameter will be _<function_na
7911 me>_PARM_2.
7912 \newline
7913
7914 \newline
7915 Assemble the assembler routine with the following command:
7916 \newline
7917
7918 \newline
7919
7920 \family sans
7921 \series bold
7922 asx8051 -losg asmfunc.asm
7923 \newline
7924
7925 \newline
7926
7927 \family default
7928 \series default
7929 Then compile and link the assembler routine to the C source file with the
7930  following command:
7931 \newline
7932
7933 \newline
7934
7935 \family sans
7936 \series bold
7937 sdcc cfunc.c asmfunc.rel
7938 \layout Subsubsection
7939
7940 Assembler Routine(reentrant)
7941 \layout Standard
7942
7943 In this case the second parameter onwards will be passed on the stack, the
7944  parameters are pushed from right to left i.e.
7945  after the call the left most parameter will be on the top of the stack.
7946  Here is an example:
7947 \newline
7948
7949 \newline
7950
7951 \family typewriter
7952 extern int asm_func(unsigned char, unsigned char);
7953 \newline
7954
7955 \newline
7956 int c_func (unsigned char i, unsigned char j) reentrant
7957 \newline
7958 {
7959 \newline
7960 \SpecialChar ~
7961 \SpecialChar ~
7962 \SpecialChar ~
7963 \SpecialChar ~
7964 return asm_func(i,j);
7965 \newline
7966 }
7967 \newline
7968
7969 \newline
7970 int main()
7971 \newline
7972 {
7973 \newline
7974 \SpecialChar ~
7975 \SpecialChar ~
7976 \SpecialChar ~
7977 \SpecialChar ~
7978 return c_func(10,9);
7979 \newline
7980 }
7981 \newline
7982
7983 \family default
7984
7985 \newline
7986 The corresponding assembler routine is:
7987 \newline
7988
7989 \newline
7990
7991 \family typewriter
7992 .globl _asm_func
7993 \newline
7994 _asm_func:
7995 \newline
7996 \SpecialChar ~
7997 \SpecialChar ~
7998 \SpecialChar ~
7999 \SpecialChar ~
8000 push  _bp
8001 \newline
8002 \SpecialChar ~
8003 \SpecialChar ~
8004 \SpecialChar ~
8005 \SpecialChar ~
8006 mov  _bp,sp
8007 \newline
8008 \SpecialChar ~
8009 \SpecialChar ~
8010 \SpecialChar ~
8011 \SpecialChar ~
8012 mov  r2,dpl
8013 \newline
8014 \SpecialChar ~
8015 \SpecialChar ~
8016 \SpecialChar ~
8017 \SpecialChar ~
8018 mov  a,_bp
8019 \newline
8020 \SpecialChar ~
8021 \SpecialChar ~
8022 \SpecialChar ~
8023 \SpecialChar ~
8024 clr  c
8025 \newline
8026 \SpecialChar ~
8027 \SpecialChar ~
8028 \SpecialChar ~
8029 \SpecialChar ~
8030 add  a,#0xfd
8031 \newline
8032 \SpecialChar ~
8033 \SpecialChar ~
8034 \SpecialChar ~
8035 \SpecialChar ~
8036 mov  r0,a
8037 \newline
8038 \SpecialChar ~
8039 \SpecialChar ~
8040 \SpecialChar ~
8041 \SpecialChar ~
8042 add  a,#0xfc
8043 \newline
8044 \SpecialChar ~
8045 \SpecialChar ~
8046 \SpecialChar ~
8047 \SpecialChar ~
8048 mov  r1,a
8049 \newline
8050 \SpecialChar ~
8051 \SpecialChar ~
8052 \SpecialChar ~
8053 \SpecialChar ~
8054 mov  a,@r0
8055 \newline
8056 \SpecialChar ~
8057 \SpecialChar ~
8058 \SpecialChar ~
8059 \SpecialChar ~
8060 add  a,r2
8061 \newline
8062 \SpecialChar ~
8063 \SpecialChar ~
8064 \SpecialChar ~
8065 \SpecialChar ~
8066 mov  dpl,a
8067 \newline
8068 \SpecialChar ~
8069 \SpecialChar ~
8070 \SpecialChar ~
8071 \SpecialChar ~
8072 mov  dph,#0x00
8073 \newline
8074 \SpecialChar ~
8075 \SpecialChar ~
8076 \SpecialChar ~
8077 \SpecialChar ~
8078 mov  sp,_bp
8079 \newline
8080 \SpecialChar ~
8081 \SpecialChar ~
8082 \SpecialChar ~
8083 \SpecialChar ~
8084 pop  _bp
8085 \newline
8086 \SpecialChar ~
8087 \SpecialChar ~
8088 \SpecialChar ~
8089 \SpecialChar ~
8090 ret
8091 \newline
8092
8093 \newline
8094
8095 \family default
8096 The compiling and linking procedure remains the same, however note the extra
8097  entry & exit linkage required for the assembler code, _bp is the stack
8098  frame pointer and is used to compute the offset into the stack for parameters
8099  and local variables.
8100 \layout Subsection
8101
8102 External Stack
8103 \layout Standard
8104
8105 The external stack is located at the start of the external ram segment,
8106  and is 256 bytes in size.
8107  When ---xstack option is used to compile the program, the parameters and
8108  local variables of all reentrant functions are allocated in this area.
8109  This option is provided for programs with large stack space requirements.
8110  When used with the ---stack-auto option, all parameters and local variables
8111  are allocated on the external stack (note support libraries will need to
8112  be recompiled with the same options).
8113 \layout Standard
8114
8115 The compiler outputs the higher order address byte of the external ram segment
8116  into PORT P2, therefore when using the External Stack option, this port
8117  MAY NOT be used by the application program.
8118 \layout Subsection
8119
8120 ANSI-Compliance
8121 \layout Standard
8122
8123 Deviations from the compliancy.
8124 \layout Itemize
8125
8126 functions are not always reentrant.
8127 \layout Itemize
8128
8129 structures cannot be assigned values directly, cannot be passed as function
8130  parameters or assigned to each other and cannot be a return value from
8131  a function, e.g.:
8132 \family typewriter
8133
8134 \newline
8135
8136 \newline
8137 struct s { ...
8138  };
8139 \newline
8140 struct s s1, s2;
8141 \newline
8142 foo()
8143 \newline
8144 {
8145 \newline
8146 \SpecialChar ~
8147 \SpecialChar ~
8148 \SpecialChar ~
8149 \SpecialChar ~
8150 ...
8151
8152 \newline
8153 \SpecialChar ~
8154 \SpecialChar ~
8155 \SpecialChar ~
8156 \SpecialChar ~
8157 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
8158 \newline
8159 \SpecialChar ~
8160 \SpecialChar ~
8161 \SpecialChar ~
8162 \SpecialChar ~
8163 ...
8164
8165 \newline
8166 }
8167 \newline
8168 struct s foo1 (struct s parms) /* is invalid in SDCC although allowed in
8169  ANSI */
8170 \newline
8171 {
8172 \newline
8173 \SpecialChar ~
8174 \SpecialChar ~
8175 \SpecialChar ~
8176 \SpecialChar ~
8177 struct s rets;
8178 \newline
8179 \SpecialChar ~
8180 \SpecialChar ~
8181 \SpecialChar ~
8182 \SpecialChar ~
8183 ...
8184
8185 \newline
8186 \SpecialChar ~
8187 \SpecialChar ~
8188 \SpecialChar ~
8189 \SpecialChar ~
8190 return rets;/* is invalid in SDCC although allowed in ANSI */
8191 \newline
8192 }
8193 \layout Itemize
8194
8195 'long long' (64 bit integers) not supported.
8196 \layout Itemize
8197
8198 'double' precision floating point not supported.
8199 \layout Itemize
8200
8201 No support for setjmp and longjmp (for now).
8202 \layout Itemize
8203
8204 Old K&R style function declarations are NOT allowed.
8205 \newline
8206
8207 \family typewriter
8208
8209 \newline
8210 foo(i,j) /* this old style of function declarations */
8211 \newline
8212 int i,j; /* are valid in ANSI but not valid in SDCC */
8213 \newline
8214 {
8215 \newline
8216 \SpecialChar ~
8217 \SpecialChar ~
8218 \SpecialChar ~
8219 \SpecialChar ~
8220 ...
8221
8222 \newline
8223 }
8224 \layout Itemize
8225
8226 functions declared as pointers must be dereferenced during the call.
8227 \newline
8228
8229 \family typewriter
8230
8231 \newline
8232 int (*foo)();
8233 \newline
8234 ...
8235
8236 \newline
8237 /* has to be called like this */
8238 \newline
8239 (*foo)(); /* ansi standard allows calls to be made like 'foo()' */
8240 \layout Subsection
8241
8242 Cyclomatic Complexity
8243 \layout Standard
8244
8245 Cyclomatic complexity of a function is defined as the number of independent
8246  paths the program can take during execution of the function.
8247  This is an important number since it defines the number test cases you
8248  have to generate to validate the function.
8249  The accepted industry standard for complexity number is 10, if the cyclomatic
8250  complexity reported by SDCC exceeds 10 you should think about simplification
8251  of the function logic.
8252  Note that the complexity level is not related to the number of lines of
8253  code in a function.
8254  Large functions can have low complexity, and small functions can have large
8255  complexity levels.
8256
8257 \newline
8258
8259 \newline
8260 SDCC uses the following formula to compute the complexity:
8261 \newline
8262
8263 \layout Standard
8264
8265 complexity = (number of edges in control flow graph) - (number of nodes
8266  in control flow graph) + 2;
8267 \newline
8268
8269 \newline
8270 Having said that the industry standard is 10, you should be aware that in
8271  some cases it be may unavoidable to have a complexity level of less than
8272  10.
8273  For example if you have switch statement with more than 10 case labels,
8274  each case label adds one to the complexity level.
8275  The complexity level is by no means an absolute measure of the algorithmic
8276  complexity of the function, it does however provide a good starting point
8277  for which functions you might look at for further optimization.
8278 \layout Section
8279
8280 TIPS
8281 \layout Standard
8282
8283 Here are a few guidelines that will help the compiler generate more efficient
8284  code, some of the tips are specific to this compiler others are generally
8285  good programming practice.
8286 \layout Itemize
8287
8288 Use the smallest data type to represent your data-value.
8289  If it is known in advance that the value is going to be less than 256 then
8290  use an 'unsigned char' instead of a 'short' or 'int'.
8291 \layout Itemize
8292
8293 Use unsigned when it is known in advance that the value is not going to
8294  be negative.
8295  This helps especially if you are doing division or multiplication.
8296 \layout Itemize
8297
8298 NEVER jump into a LOOP.
8299 \layout Itemize
8300
8301 Declare the variables to be local whenever possible, especially loop control
8302  variables (induction).
8303 \layout Itemize
8304
8305 Since the compiler does not always do implicit integral promotion, the programme
8306 r should do an explicit cast when integral promotion is required.
8307 \layout Itemize
8308
8309 Reducing the size of division, multiplication & modulus operations can reduce
8310  code size substantially.
8311  Take the following code for example.
8312 \family typewriter
8313
8314 \newline
8315
8316 \newline
8317 foobar(unsigned int p1, unsigned char ch)
8318 \newline
8319 {
8320 \newline
8321     unsigned char ch1 = p1 % ch ;
8322 \newline
8323     ....
8324
8325 \newline
8326 }
8327 \newline
8328
8329 \family default
8330
8331 \newline
8332 For the modulus operation the variable ch will be promoted to unsigned int
8333  first then the modulus operation will be performed (this will lead to a
8334  call to support routine _moduint()), and the result will be casted to a
8335  char.
8336  If the code is changed to
8337 \newline
8338
8339 \family typewriter
8340
8341 \newline
8342 foobar(unsigned int p1, unsigned char ch)
8343 \newline
8344 {
8345 \newline
8346     unsigned char ch1 = (unsigned char)p1 % ch ;
8347 \newline
8348     ....
8349
8350 \newline
8351 }
8352 \newline
8353
8354 \family default
8355
8356 \newline
8357 It would substantially reduce the code generated (future versions of the
8358  compiler will be smart enough to detect such optimization oppurtunities).
8359 \layout Subsection
8360
8361 Notes on MCS51 memory layout
8362 \layout Standard
8363
8364 The 8051 family of micro controller have a minimum of 128 bytes of internal
8365  memory which is structured as follows
8366 \newline
8367
8368 \newline
8369 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R7 to R7
8370
8371 \newline
8372 - Bytes 20-2F - 16 bytes to hold 128 bit variables and
8373 \newline
8374 - Bytes 30-7F - 60 bytes for general purpose use.
8375 \newline
8376
8377 \newline
8378 Normally the SDCC compiler will only utilise the first bank of registers,
8379  but it is possible to specify that other banks of registers should be used
8380  in interrupt routines.
8381  By default, the compiler will place the stack after the last bank of used
8382  registers, i.e.
8383  if the first 2 banks of registers are used, it will position the base of
8384  the internal stack at address 16 (0X10).
8385  This implies that as the stack grows, it will use up the remaining register
8386  banks, and the 16 bytes used by the 128 bit variables, and 60 bytes for
8387  general purpose use.
8388 \layout Standard
8389
8390 By default, the compiler uses the 60 general purpose bytes to hold "near
8391  data".
8392  The compiler/optimiser may also declare some Local Variables in this area
8393  to hold local data.
8394
8395 \layout Standard
8396
8397 If any of the 128 bit variables are used, or near data is being used then
8398  care needs to be taken to ensure that the stack does not grow so much that
8399  it starts to over write either your bit variables or "near data".
8400  There is no runtime checking to prevent this from happening.
8401 \layout Standard
8402
8403 The amount of stack being used is affected by the use of the "internal stack"
8404  to save registers before a subroutine call is made (---stack-auto will
8405  declare parameters and local variables on the stack) and the number of
8406  nested subroutines.
8407 \layout Standard
8408
8409 If you detect that the stack is over writing you data, then the following
8410  can be done.
8411  ---xstack will cause an external stack to be used for saving registers
8412  and (if ---stack-auto is being used) storing parameters and local variables.
8413  However this will produce more code which will be slower to execute.
8414
8415 \layout Standard
8416
8417 ---stack-loc will allow you specify the start of the stack, i.e.
8418  you could start it after any data in the general purpose area.
8419  However this may waste the memory not used by the register banks and if
8420  the size of the "near data" increases, it may creep into the bottom of
8421  the stack.
8422 \layout Standard
8423
8424 ---stack-after-data, similar to the ---stack-loc, but it automatically places
8425  the stack after the end of the "near data".
8426  Again this could waste any spare register space.
8427 \layout Standard
8428
8429 ---data-loc allows you to specify the start address of the near data.
8430  This could be used to move the "near data" further away from the stack
8431  giving it more room to grow.
8432  This will only work if no bit variables are being used and the stack can
8433  grow to use the bit variable space.
8434 \newline
8435
8436 \newline
8437 Conclusion.
8438 \newline
8439
8440 \newline
8441 If you find that the stack is over writing your bit variables or "near data"
8442  then the approach which best utilised the internal memory is to position
8443  the "near data" after the last bank of used registers or, if you use bit
8444  variables, after the last bit variable by using the ---data-loc, e.g.
8445  if two register banks are being used and no bit variables, ---data-loc
8446  16, and use the ---stack-after-data option.
8447 \layout Standard
8448
8449 If bit variables are being used, another method would be to try and squeeze
8450  the data area in the unused register banks if it will fit, and start the
8451  stack after the last bit variable.
8452 \layout Section
8453
8454 Retargetting for other MCUs.
8455 \layout Standard
8456
8457 The issues for retargetting the compiler are far too numerous to be covered
8458  by this document.
8459  What follows is a brief description of each of the seven phases of the
8460  compiler and its MCU dependency.
8461 \layout Itemize
8462
8463 Parsing the source and building the annotated parse tree.
8464  This phase is largely MCU independent (except for the language extensions).
8465  Syntax & semantic checks are also done in this phase, along with some initial
8466  optimizations like back patching labels and the pattern matching optimizations
8467  like bit-rotation etc.
8468 \layout Itemize
8469
8470 The second phase involves generating an intermediate code which can be easy
8471  manipulated during the later phases.
8472  This phase is entirely MCU independent.
8473  The intermediate code generation assumes the target machine has unlimited
8474  number of registers, and designates them with the name iTemp.
8475  The compiler can be made to dump a human readable form of the code generated
8476  by using the ---dumpraw option.
8477 \layout Itemize
8478
8479 This phase does the bulk of the standard optimizations and is also MCU independe
8480 nt.
8481  This phase can be broken down into several sub-phases:
8482 \newline
8483
8484 \newline
8485 Break down intermediate code (iCode) into basic blocks.
8486 \newline
8487 Do control flow & data flow analysis on the basic blocks.
8488 \newline
8489 Do local common subexpression elimination, then global subexpression elimination
8490 \newline
8491 Dead code elimination
8492 \newline
8493 Loop optimizations
8494 \newline
8495 If loop optimizations caused any changes then do 'global subexpression eliminati
8496 on' and 'dead code elimination' again.
8497 \layout Itemize
8498
8499 This phase determines the live-ranges; by live range I mean those iTemp
8500  variables defined by the compiler that still survive after all the optimization
8501 s.
8502  Live range analysis is essential for register allocation, since these computati
8503 on determines which of these iTemps will be assigned to registers, and for
8504  how long.
8505 \layout Itemize
8506
8507 Phase five is register allocation.
8508  There are two parts to this process.
8509 \newline
8510
8511 \newline
8512 The first part I call 'register packing' (for lack of a better term).
8513  In this case several MCU specific expression folding is done to reduce
8514  register pressure.
8515 \newline
8516
8517 \newline
8518 The second part is more MCU independent and deals with allocating registers
8519  to the remaining live ranges.
8520  A lot of MCU specific code does creep into this phase because of the limited
8521  number of index registers available in the 8051.
8522 \layout Itemize
8523
8524 The Code generation phase is (unhappily), entirely MCU dependent and very
8525  little (if any at all) of this code can be reused for other MCU.
8526  However the scheme for allocating a homogenized assembler operand for each
8527  iCode operand may be reused.
8528 \layout Itemize
8529
8530 As mentioned in the optimization section the peep-hole optimizer is rule
8531  based system, which can reprogrammed for other MCUs.
8532 \layout Section
8533
8534 SDCDB - Source Level Debugger
8535 \layout Standard
8536
8537 SDCC is distributed with a source level debugger.
8538  The debugger uses a command line interface, the command repertoire of the
8539  debugger has been kept as close to gdb (the GNU debugger) as possible.
8540  The configuration and build process is part of the standard compiler installati
8541 on, which also builds and installs the debugger in the target directory
8542  specified during configuration.
8543  The debugger allows you debug BOTH at the C source and at the ASM source
8544  level.
8545 \layout Subsection
8546
8547 Compiling for Debugging
8548 \layout Standard
8549
8550 The \SpecialChar \-
8551 \SpecialChar \-
8552 debug option must be specified for all files for which debug information
8553  is to be generated.
8554  The complier generates a .cdb file for each of these files.
8555  The linker updates the .cdb file with the address information.
8556  This .cdb is used by the debugger.
8557 \layout Subsection
8558
8559 How the Debugger Works
8560 \layout Standard
8561
8562 When the ---debug option is specified the compiler generates extra symbol
8563  information some of which are put into the the assembler source and some
8564  are put into the .cdb file, the linker updates the .cdb file with the address
8565  information for the symbols.
8566  The debugger reads the symbolic information generated by the compiler &
8567  the address information generated by the linker.
8568  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
8569  execution is controlled by the debugger.
8570  When a command is issued for the debugger, it translates it into appropriate
8571  commands for the simulator.
8572 \layout Subsection
8573
8574 Starting the Debugger
8575 \layout Standard
8576
8577 The debugger can be started using the following command line.
8578  (Assume the file you are debugging has the file name foo).
8579 \newline
8580
8581 \newline
8582
8583 \family sans
8584 \series bold
8585 sdcdb foo
8586 \newline
8587
8588 \family default
8589 \series default
8590
8591 \newline
8592 The debugger will look for the following files.
8593 \layout Itemize
8594
8595 foo.c - the source file.
8596 \layout Itemize
8597
8598 foo.cdb - the debugger symbol information file.
8599 \layout Itemize
8600
8601 foo.ihx - the intel hex format object file.
8602 \layout Subsection
8603
8604 Command Line Options.
8605 \layout Itemize
8606
8607 ---directory=<source file directory> this option can used to specify the
8608  directory search list.
8609  The debugger will look into the directory list specified for source, cdb
8610  & ihx files.
8611  The items in the directory list must be separated by ':', e.g.
8612  if the source files can be in the directories /home/src1 and /home/src2,
8613  the ---directory option should be ---directory=/home/src1:/home/src2.
8614  Note there can be no spaces in the option.
8615
8616 \layout Itemize
8617
8618 -cd <directory> - change to the <directory>.
8619 \layout Itemize
8620
8621 -fullname - used by GUI front ends.
8622 \layout Itemize
8623
8624 -cpu <cpu-type> - this argument is passed to the simulator please see the
8625  simulator docs for details.
8626 \layout Itemize
8627
8628 -X <Clock frequency > this options is passed to the simulator please see
8629  the simulator docs for details.
8630 \layout Itemize
8631
8632 -s <serial port file> passed to simulator see the simulator docs for details.
8633 \layout Itemize
8634
8635 -S <serial in,out> passed to simulator see the simulator docs for details.
8636 \layout Subsection
8637
8638 Debugger Commands.
8639 \layout Standard
8640
8641 As mention earlier the command interface for the debugger has been deliberately
8642  kept as close the GNU debugger gdb, as possible.
8643  This will help the integration with existing graphical user interfaces
8644  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
8645 \layout Subsubsection
8646
8647 break [line | file:line | function | file:function]
8648 \layout Standard
8649
8650 Set breakpoint at specified line or function:
8651 \newline
8652
8653 \newline
8654
8655 \family sans
8656 \series bold
8657 sdcdb>break 100
8658 \newline
8659 sdcdb>break foo.c:100
8660 \newline
8661 sdcdb>break funcfoo
8662 \newline
8663 sdcdb>break foo.c:funcfoo
8664 \layout Subsubsection
8665
8666 clear [line | file:line | function | file:function ]
8667 \layout Standard
8668
8669 Clear breakpoint at specified line or function:
8670 \newline
8671
8672 \newline
8673
8674 \family sans
8675 \series bold
8676 sdcdb>clear 100
8677 \newline
8678 sdcdb>clear foo.c:100
8679 \newline
8680 sdcdb>clear funcfoo
8681 \newline
8682 sdcdb>clear foo.c:funcfoo
8683 \layout Subsubsection
8684
8685 continue
8686 \layout Standard
8687
8688 Continue program being debugged, after breakpoint.
8689 \layout Subsubsection
8690
8691 finish
8692 \layout Standard
8693
8694 Execute till the end of the current function.
8695 \layout Subsubsection
8696
8697 delete [n]
8698 \layout Standard
8699
8700 Delete breakpoint number 'n'.
8701  If used without any option clear ALL user defined break points.
8702 \layout Subsubsection
8703
8704 info [break | stack | frame | registers ]
8705 \layout Itemize
8706
8707 info break - list all breakpoints
8708 \layout Itemize
8709
8710 info stack - show the function call stack.
8711 \layout Itemize
8712
8713 info frame - show information about the current execution frame.
8714 \layout Itemize
8715
8716 info registers - show content of all registers.
8717 \layout Subsubsection
8718
8719 step
8720 \layout Standard
8721
8722 Step program until it reaches a different source line.
8723 \layout Subsubsection
8724
8725 next
8726 \layout Standard
8727
8728 Step program, proceeding through subroutine calls.
8729 \layout Subsubsection
8730
8731 run
8732 \layout Standard
8733
8734 Start debugged program.
8735 \layout Subsubsection
8736
8737 ptype variable
8738 \layout Standard
8739
8740 Print type information of the variable.
8741 \layout Subsubsection
8742
8743 print variable
8744 \layout Standard
8745
8746 print value of variable.
8747 \layout Subsubsection
8748
8749 file filename
8750 \layout Standard
8751
8752 load the given file name.
8753  Note this is an alternate method of loading file for debugging.
8754 \layout Subsubsection
8755
8756 frame
8757 \layout Standard
8758
8759 print information about current frame.
8760 \layout Subsubsection
8761
8762 set srcmode
8763 \layout Standard
8764
8765 Toggle between C source & assembly source.
8766 \layout Subsubsection
8767
8768 ! simulator command
8769 \layout Standard
8770
8771 Send the string following '!' to the simulator, the simulator response is
8772  displayed.
8773  Note the debugger does not interpret the command being sent to the simulator,
8774  so if a command like 'go' is sent the debugger can loose its execution
8775  context and may display incorrect values.
8776 \layout Subsubsection
8777
8778 quit.
8779 \layout Standard
8780
8781 "Watch me now.
8782  Iam going Down.
8783  My name is Bobby Brown"
8784 \layout Subsection
8785
8786 Interfacing with XEmacs.
8787 \layout Standard
8788
8789 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
8790  sdcdb.el and sdcdbsrc.el.
8791  These two files can be found in the $(prefix)/bin directory after the installat
8792 ion is complete.
8793  These files need to be loaded into XEmacs for the interface to work.
8794  This can be done at XEmacs startup time by inserting the following into
8795  your '.xemacs' file (which can be found in your HOME directory):
8796 \newline
8797
8798 \newline
8799
8800 \family typewriter
8801 (load-file sdcdbsrc.el)
8802 \family default
8803
8804 \newline
8805
8806 \newline
8807 .xemacs is a lisp file so the () around the command is REQUIRED.
8808  The files can also be loaded dynamically while XEmacs is running, set the
8809  environment variable 'EMACSLOADPATH' to the installation bin directory
8810  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
8811  To start the interface enter the following command:
8812 \newline
8813
8814 \newline
8815
8816 \family sans
8817 \series bold
8818 ESC-x sdcdbsrc
8819 \family default
8820 \series default
8821
8822 \newline
8823
8824 \newline
8825 You will prompted to enter the file name to be debugged.
8826
8827 \newline
8828
8829 \newline
8830 The command line options that are passed to the simulator directly are bound
8831  to default values in the file sdcdbsrc.el.
8832  The variables are listed below, these values maybe changed as required.
8833 \layout Itemize
8834
8835 sdcdbsrc-cpu-type '51
8836 \layout Itemize
8837
8838 sdcdbsrc-frequency '11059200
8839 \layout Itemize
8840
8841 sdcdbsrc-serial nil
8842 \layout Standard
8843
8844 The following is a list of key mapping for the debugger interface.
8845 \layout Standard
8846
8847 \SpecialChar ~
8848
8849 \family typewriter
8850
8851 \newline
8852 ;; Current Listing ::
8853 \newline
8854 ;;key\SpecialChar ~
8855 \SpecialChar ~
8856 \SpecialChar ~
8857 \SpecialChar ~
8858 \SpecialChar ~
8859 \SpecialChar ~
8860 \SpecialChar ~
8861 \SpecialChar ~
8862 \SpecialChar ~
8863 \SpecialChar ~
8864 \SpecialChar ~
8865 \SpecialChar ~
8866 \SpecialChar ~
8867 \SpecialChar ~
8868 \SpecialChar ~
8869 binding\SpecialChar ~
8870 \SpecialChar ~
8871 \SpecialChar ~
8872 \SpecialChar ~
8873 \SpecialChar ~
8874 \SpecialChar ~
8875 \SpecialChar ~
8876 \SpecialChar ~
8877 \SpecialChar ~
8878 \SpecialChar ~
8879 \SpecialChar ~
8880 \SpecialChar ~
8881 \SpecialChar ~
8882 \SpecialChar ~
8883 \SpecialChar ~
8884 \SpecialChar ~
8885 \SpecialChar ~
8886 \SpecialChar ~
8887 \SpecialChar ~
8888 \SpecialChar ~
8889 \SpecialChar ~
8890 \SpecialChar ~
8891 Comment
8892 \newline
8893 ;;---\SpecialChar ~
8894 \SpecialChar ~
8895 \SpecialChar ~
8896 \SpecialChar ~
8897 \SpecialChar ~
8898 \SpecialChar ~
8899 \SpecialChar ~
8900 \SpecialChar ~
8901 \SpecialChar ~
8902 \SpecialChar ~
8903 \SpecialChar ~
8904 \SpecialChar ~
8905 \SpecialChar ~
8906 \SpecialChar ~
8907 \SpecialChar ~
8908 ------\SpecialChar ~
8909 \SpecialChar ~
8910 \SpecialChar ~
8911 \SpecialChar ~
8912 \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 --------
8931 \newline
8932 ;;
8933 \newline
8934 ;; n\SpecialChar ~
8935 \SpecialChar ~
8936 \SpecialChar ~
8937 \SpecialChar ~
8938 \SpecialChar ~
8939 \SpecialChar ~
8940 \SpecialChar ~
8941 \SpecialChar ~
8942 \SpecialChar ~
8943 \SpecialChar ~
8944 \SpecialChar ~
8945 \SpecialChar ~
8946 \SpecialChar ~
8947 \SpecialChar ~
8948  sdcdb-next-from-src\SpecialChar ~
8949 \SpecialChar ~
8950 \SpecialChar ~
8951 \SpecialChar ~
8952 \SpecialChar ~
8953 \SpecialChar ~
8954 \SpecialChar ~
8955 \SpecialChar ~
8956 \SpecialChar ~
8957 \SpecialChar ~
8958 SDCDB next command
8959 \newline
8960 ;; b\SpecialChar ~
8961 \SpecialChar ~
8962 \SpecialChar ~
8963 \SpecialChar ~
8964 \SpecialChar ~
8965 \SpecialChar ~
8966 \SpecialChar ~
8967 \SpecialChar ~
8968 \SpecialChar ~
8969 \SpecialChar ~
8970 \SpecialChar ~
8971 \SpecialChar ~
8972 \SpecialChar ~
8973 \SpecialChar ~
8974  sdcdb-back-from-src\SpecialChar ~
8975 \SpecialChar ~
8976 \SpecialChar ~
8977 \SpecialChar ~
8978 \SpecialChar ~
8979 \SpecialChar ~
8980 \SpecialChar ~
8981 \SpecialChar ~
8982 \SpecialChar ~
8983 \SpecialChar ~
8984 SDCDB back command
8985 \newline
8986 ;; c\SpecialChar ~
8987 \SpecialChar ~
8988 \SpecialChar ~
8989 \SpecialChar ~
8990 \SpecialChar ~
8991 \SpecialChar ~
8992 \SpecialChar ~
8993 \SpecialChar ~
8994 \SpecialChar ~
8995 \SpecialChar ~
8996 \SpecialChar ~
8997 \SpecialChar ~
8998 \SpecialChar ~
8999 \SpecialChar ~
9000  sdcdb-cont-from-src\SpecialChar ~
9001 \SpecialChar ~
9002 \SpecialChar ~
9003 \SpecialChar ~
9004 \SpecialChar ~
9005 \SpecialChar ~
9006 \SpecialChar ~
9007 \SpecialChar ~
9008 \SpecialChar ~
9009 \SpecialChar ~
9010 SDCDB continue command
9011 \newline
9012 ;; s\SpecialChar ~
9013 \SpecialChar ~
9014 \SpecialChar ~
9015 \SpecialChar ~
9016 \SpecialChar ~
9017 \SpecialChar ~
9018 \SpecialChar ~
9019 \SpecialChar ~
9020 \SpecialChar ~
9021 \SpecialChar ~
9022 \SpecialChar ~
9023 \SpecialChar ~
9024 \SpecialChar ~
9025 \SpecialChar ~
9026  sdcdb-step-from-src\SpecialChar ~
9027 \SpecialChar ~
9028 \SpecialChar ~
9029 \SpecialChar ~
9030 \SpecialChar ~
9031 \SpecialChar ~
9032 \SpecialChar ~
9033 \SpecialChar ~
9034 \SpecialChar ~
9035 \SpecialChar ~
9036 SDCDB step command
9037 \newline
9038 ;; ?\SpecialChar ~
9039 \SpecialChar ~
9040 \SpecialChar ~
9041 \SpecialChar ~
9042 \SpecialChar ~
9043 \SpecialChar ~
9044 \SpecialChar ~
9045 \SpecialChar ~
9046 \SpecialChar ~
9047 \SpecialChar ~
9048 \SpecialChar ~
9049 \SpecialChar ~
9050 \SpecialChar ~
9051 \SpecialChar ~
9052  sdcdb-whatis-c-sexp\SpecialChar ~
9053 \SpecialChar ~
9054 \SpecialChar ~
9055 \SpecialChar ~
9056 \SpecialChar ~
9057 \SpecialChar ~
9058 \SpecialChar ~
9059 \SpecialChar ~
9060 \SpecialChar ~
9061 \SpecialChar ~
9062 SDCDB ptypecommand for data at
9063 \newline
9064 ;;\SpecialChar ~
9065 \SpecialChar ~
9066 \SpecialChar ~
9067 \SpecialChar ~
9068 \SpecialChar ~
9069 \SpecialChar ~
9070 \SpecialChar ~
9071 \SpecialChar ~
9072 \SpecialChar ~
9073 \SpecialChar ~
9074 \SpecialChar ~
9075 \SpecialChar ~
9076 \SpecialChar ~
9077 \SpecialChar ~
9078 \SpecialChar ~
9079 \SpecialChar ~
9080 \SpecialChar ~
9081 \SpecialChar ~
9082 \SpecialChar ~
9083 \SpecialChar ~
9084 \SpecialChar ~
9085 \SpecialChar ~
9086 \SpecialChar ~
9087 \SpecialChar ~
9088 \SpecialChar ~
9089 \SpecialChar ~
9090 \SpecialChar ~
9091 \SpecialChar ~
9092 \SpecialChar ~
9093 \SpecialChar ~
9094 \SpecialChar ~
9095 \SpecialChar ~
9096 \SpecialChar ~
9097 \SpecialChar ~
9098 \SpecialChar ~
9099 \SpecialChar ~
9100 \SpecialChar ~
9101 \SpecialChar ~
9102 \SpecialChar ~
9103 \SpecialChar ~
9104 \SpecialChar ~
9105 \SpecialChar ~
9106 \SpecialChar ~
9107 \SpecialChar ~
9108 \SpecialChar ~
9109 \SpecialChar ~
9110  buffer point
9111 \newline
9112 ;; x\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  sdcdbsrc-delete\SpecialChar ~
9127 \SpecialChar ~
9128 \SpecialChar ~
9129 \SpecialChar ~
9130 \SpecialChar ~
9131 \SpecialChar ~
9132 \SpecialChar ~
9133 \SpecialChar ~
9134 \SpecialChar ~
9135 \SpecialChar ~
9136 \SpecialChar ~
9137 \SpecialChar ~
9138 \SpecialChar ~
9139 \SpecialChar ~
9140 SDCDB Delete all breakpoints if no arg
9141 \newline
9142 ;;\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 \SpecialChar ~
9157 \SpecialChar ~
9158 \SpecialChar ~
9159 \SpecialChar ~
9160 \SpecialChar ~
9161 \SpecialChar ~
9162 \SpecialChar ~
9163 \SpecialChar ~
9164 \SpecialChar ~
9165 \SpecialChar ~
9166 \SpecialChar ~
9167 \SpecialChar ~
9168 \SpecialChar ~
9169 \SpecialChar ~
9170 \SpecialChar ~
9171 \SpecialChar ~
9172 \SpecialChar ~
9173 \SpecialChar ~
9174 \SpecialChar ~
9175 \SpecialChar ~
9176 \SpecialChar ~
9177 \SpecialChar ~
9178 \SpecialChar ~
9179 \SpecialChar ~
9180 \SpecialChar ~
9181 \SpecialChar ~
9182 \SpecialChar ~
9183 \SpecialChar ~
9184 \SpecialChar ~
9185 \SpecialChar ~
9186 \SpecialChar ~
9187 \SpecialChar ~
9188 given or delete arg (C-u arg x)
9189 \newline
9190 ;; m\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  sdcdbsrc-frame\SpecialChar ~
9205 \SpecialChar ~
9206 \SpecialChar ~
9207 \SpecialChar ~
9208 \SpecialChar ~
9209 \SpecialChar ~
9210 \SpecialChar ~
9211 \SpecialChar ~
9212 \SpecialChar ~
9213 \SpecialChar ~
9214 \SpecialChar ~
9215 \SpecialChar ~
9216 \SpecialChar ~
9217 \SpecialChar ~
9218 \SpecialChar ~
9219 SDCDB Display current frame if no arg,
9220 \newline
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 \SpecialChar ~
9236 \SpecialChar ~
9237 \SpecialChar ~
9238 \SpecialChar ~
9239 \SpecialChar ~
9240 \SpecialChar ~
9241 \SpecialChar ~
9242 \SpecialChar ~
9243 \SpecialChar ~
9244 \SpecialChar ~
9245 \SpecialChar ~
9246 \SpecialChar ~
9247 \SpecialChar ~
9248 \SpecialChar ~
9249 \SpecialChar ~
9250 \SpecialChar ~
9251 \SpecialChar ~
9252 \SpecialChar ~
9253 \SpecialChar ~
9254 \SpecialChar ~
9255 \SpecialChar ~
9256 \SpecialChar ~
9257 \SpecialChar ~
9258 \SpecialChar ~
9259 \SpecialChar ~
9260 \SpecialChar ~
9261 \SpecialChar ~
9262 \SpecialChar ~
9263 \SpecialChar ~
9264 \SpecialChar ~
9265 \SpecialChar ~
9266 \SpecialChar ~
9267 \SpecialChar ~
9268 given or display frame arg
9269 \newline
9270 ;;\SpecialChar ~
9271 \SpecialChar ~
9272 \SpecialChar ~
9273 \SpecialChar ~
9274 \SpecialChar ~
9275 \SpecialChar ~
9276 \SpecialChar ~
9277 \SpecialChar ~
9278 \SpecialChar ~
9279 \SpecialChar ~
9280 \SpecialChar ~
9281 \SpecialChar ~
9282 \SpecialChar ~
9283 \SpecialChar ~
9284 \SpecialChar ~
9285 \SpecialChar ~
9286 \SpecialChar ~
9287 \SpecialChar ~
9288 \SpecialChar ~
9289 \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 buffer point
9318 \newline
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  sdcdbsrc-goto-sdcdb\SpecialChar ~
9334 \SpecialChar ~
9335 \SpecialChar ~
9336 \SpecialChar ~
9337 \SpecialChar ~
9338 \SpecialChar ~
9339 \SpecialChar ~
9340 \SpecialChar ~
9341 \SpecialChar ~
9342 \SpecialChar ~
9343 Goto the SDCDB output buffer
9344 \newline
9345 ;; p\SpecialChar ~
9346 \SpecialChar ~
9347 \SpecialChar ~
9348 \SpecialChar ~
9349 \SpecialChar ~
9350 \SpecialChar ~
9351 \SpecialChar ~
9352 \SpecialChar ~
9353 \SpecialChar ~
9354 \SpecialChar ~
9355 \SpecialChar ~
9356 \SpecialChar ~
9357 \SpecialChar ~
9358 \SpecialChar ~
9359  sdcdb-print-c-sexp\SpecialChar ~
9360 \SpecialChar ~
9361 \SpecialChar ~
9362 \SpecialChar ~
9363 \SpecialChar ~
9364 \SpecialChar ~
9365 \SpecialChar ~
9366 \SpecialChar ~
9367 \SpecialChar ~
9368 \SpecialChar ~
9369 \SpecialChar ~
9370 SDCDB print command for data at
9371 \newline
9372 ;;\SpecialChar ~
9373 \SpecialChar ~
9374 \SpecialChar ~
9375 \SpecialChar ~
9376 \SpecialChar ~
9377 \SpecialChar ~
9378 \SpecialChar ~
9379 \SpecialChar ~
9380 \SpecialChar ~
9381 \SpecialChar ~
9382 \SpecialChar ~
9383 \SpecialChar ~
9384 \SpecialChar ~
9385 \SpecialChar ~
9386 \SpecialChar ~
9387 \SpecialChar ~
9388 \SpecialChar ~
9389 \SpecialChar ~
9390 \SpecialChar ~
9391 \SpecialChar ~
9392 \SpecialChar ~
9393 \SpecialChar ~
9394 \SpecialChar ~
9395 \SpecialChar ~
9396 \SpecialChar ~
9397 \SpecialChar ~
9398 \SpecialChar ~
9399 \SpecialChar ~
9400 \SpecialChar ~
9401 \SpecialChar ~
9402 \SpecialChar ~
9403 \SpecialChar ~
9404 \SpecialChar ~
9405 \SpecialChar ~
9406 \SpecialChar ~
9407 \SpecialChar ~
9408 \SpecialChar ~
9409 \SpecialChar ~
9410 \SpecialChar ~
9411 \SpecialChar ~
9412 \SpecialChar ~
9413 \SpecialChar ~
9414 \SpecialChar ~
9415 \SpecialChar ~
9416 \SpecialChar ~
9417 \SpecialChar ~
9418  buffer point
9419 \newline
9420 ;; g\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  sdcdbsrc-goto-sdcdb\SpecialChar ~
9435 \SpecialChar ~
9436 \SpecialChar ~
9437 \SpecialChar ~
9438 \SpecialChar ~
9439 \SpecialChar ~
9440 \SpecialChar ~
9441 \SpecialChar ~
9442 \SpecialChar ~
9443 \SpecialChar ~
9444 Goto the SDCDB output buffer
9445 \newline
9446 ;; t\SpecialChar ~
9447 \SpecialChar ~
9448 \SpecialChar ~
9449 \SpecialChar ~
9450 \SpecialChar ~
9451 \SpecialChar ~
9452 \SpecialChar ~
9453 \SpecialChar ~
9454 \SpecialChar ~
9455 \SpecialChar ~
9456 \SpecialChar ~
9457 \SpecialChar ~
9458 \SpecialChar ~
9459 \SpecialChar ~
9460  sdcdbsrc-mode\SpecialChar ~
9461 \SpecialChar ~
9462 \SpecialChar ~
9463 \SpecialChar ~
9464 \SpecialChar ~
9465 \SpecialChar ~
9466 \SpecialChar ~
9467 \SpecialChar ~
9468 \SpecialChar ~
9469 \SpecialChar ~
9470 \SpecialChar ~
9471 \SpecialChar ~
9472 \SpecialChar ~
9473 \SpecialChar ~
9474 \SpecialChar ~
9475 \SpecialChar ~
9476 Toggles Sdcdbsrc mode (turns it off)
9477 \newline
9478 ;;
9479 \newline
9480 ;; C-c C-f\SpecialChar ~
9481 \SpecialChar ~
9482 \SpecialChar ~
9483 \SpecialChar ~
9484 \SpecialChar ~
9485 \SpecialChar ~
9486 \SpecialChar ~
9487 \SpecialChar ~
9488  sdcdb-finish-from-src\SpecialChar ~
9489 \SpecialChar ~
9490 \SpecialChar ~
9491 \SpecialChar ~
9492 \SpecialChar ~
9493 \SpecialChar ~
9494 \SpecialChar ~
9495 \SpecialChar ~
9496 SDCDB finish command
9497 \newline
9498 ;;
9499 \newline
9500 ;; C-x SPC\SpecialChar ~
9501 \SpecialChar ~
9502 \SpecialChar ~
9503 \SpecialChar ~
9504 \SpecialChar ~
9505 \SpecialChar ~
9506 \SpecialChar ~
9507 \SpecialChar ~
9508  sdcdb-break\SpecialChar ~
9509 \SpecialChar ~
9510 \SpecialChar ~
9511 \SpecialChar ~
9512 \SpecialChar ~
9513 \SpecialChar ~
9514 \SpecialChar ~
9515 \SpecialChar ~
9516 \SpecialChar ~
9517 \SpecialChar ~
9518 \SpecialChar ~
9519 \SpecialChar ~
9520 \SpecialChar ~
9521 \SpecialChar ~
9522 \SpecialChar ~
9523 \SpecialChar ~
9524 \SpecialChar ~
9525 \SpecialChar ~
9526 Set break for line with point
9527 \newline
9528 ;; ESC t\SpecialChar ~
9529 \SpecialChar ~
9530 \SpecialChar ~
9531 \SpecialChar ~
9532 \SpecialChar ~
9533 \SpecialChar ~
9534 \SpecialChar ~
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 \SpecialChar ~
9538  sdcdbsrc-mode\SpecialChar ~
9539 \SpecialChar ~
9540 \SpecialChar ~
9541 \SpecialChar ~
9542 \SpecialChar ~
9543 \SpecialChar ~
9544 \SpecialChar ~
9545 \SpecialChar ~
9546 \SpecialChar ~
9547 \SpecialChar ~
9548 \SpecialChar ~
9549 \SpecialChar ~
9550 \SpecialChar ~
9551 \SpecialChar ~
9552 \SpecialChar ~
9553 \SpecialChar ~
9554 Toggle Sdcdbsrc mode
9555 \newline
9556 ;; ESC m\SpecialChar ~
9557 \SpecialChar ~
9558 \SpecialChar ~
9559 \SpecialChar ~
9560 \SpecialChar ~
9561 \SpecialChar ~
9562 \SpecialChar ~
9563 \SpecialChar ~
9564 \SpecialChar ~
9565 \SpecialChar ~
9566  sdcdbsrc-srcmode\SpecialChar ~
9567 \SpecialChar ~
9568 \SpecialChar ~
9569 \SpecialChar ~
9570 \SpecialChar ~
9571 \SpecialChar ~
9572 \SpecialChar ~
9573 \SpecialChar ~
9574 \SpecialChar ~
9575 \SpecialChar ~
9576 \SpecialChar ~
9577 \SpecialChar ~
9578  Toggle list mode
9579 \newline
9580 ;;
9581 \family default
9582
9583 \newline
9584
9585 \layout Section
9586
9587 Other Processors
9588 \layout Subsection
9589
9590 The Z80 and gbz80 port
9591 \layout Standard
9592
9593 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
9594  The port is incomplete - long support is incomplete (mul, div and mod are
9595  unimplimented), and both float and bitfield support is missing.
9596  Apart from that the code generated is correct.
9597 \layout Standard
9598
9599 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
9600  The stack frame is similar to that generated by the IAR Z80 compiler.
9601  IX is used as the base pointer, HL is used as a temporary register, and
9602  BC and DE are available for holding varibles.
9603  IY is currently unusued.
9604  Return values are stored in HL.
9605  One bad side effect of using IX as the base pointer is that a functions
9606  stack frame is limited to 127 bytes - this will be fixed in a later version.
9607 \layout Section
9608
9609 Support
9610 \layout Standard
9611
9612 SDCC has grown to be a large project.
9613  The compiler alone (without the preprocessor, assembler and linker) is
9614  about 40,000 lines of code (blank stripped).
9615  The open source nature of this project is a key to its continued growth
9616  and support.
9617  You gain the benefit and support of many active software developers and
9618  end users.
9619  Is SDCC perfect? No, that's why we need your help.
9620  The developers take pride in fixing reported bugs.
9621  You can help by reporting the bugs and helping other SDCC users.
9622  There are lots of ways to contribute, and we encourage you to take part
9623  in making SDCC a great software package.
9624 \layout Subsection
9625
9626 Reporting Bugs
9627 \layout Standard
9628
9629 Send an email to the mailing list at 'user-sdcc@sdcc.sourceforge.net' or 'devel-sd
9630 cc@sdcc.sourceforge.net'.
9631  Bugs will be fixed ASAP.
9632  When reporting a bug, it is very useful to include a small test program
9633  which reproduces the problem.
9634  If you can isolate the problem by looking at the generated assembly code,
9635  this can be very helpful.
9636  Compiling your program with the ---dumpall option can sometimes be useful
9637  in locating optimization problems.
9638 \layout Section
9639
9640 Compiler internals
9641 \layout Subsection
9642
9643 The anatomy of the compiler
9644 \layout Standard
9645
9646
9647 \shape italic
9648 This is an excerpt from an atricle published in Circuit Cellar MagaZine
9649  in august 2000.
9650  It's a little outdated (the compiler is much more efficient now and user/devell
9651 oper friendly), but pretty well exposes the guts of it all.
9652 \shape default
9653
9654 \newline
9655
9656 \newline
9657 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
9658  It is fairly easy to retarget for other 8-bit MCU.
9659  Here we take a look at some of the internals of the compiler.
9660
9661 \layout Paragraph*
9662
9663 Parsing
9664 \layout Standard
9665
9666 Parsing the input source file and creating an AST (Annotated Syntax Tree).
9667  This phase also involves propagating types (annotating each node of the
9668  parse tree with type information) and semantic analysis.
9669  There are some MCU specific parsing rules.
9670  For example the storage classes, the extended storage classes are MCU specific
9671  while there may be a xdata storage class for 8051 there is no such storage
9672  class for z80 or Atmel AVR.
9673  SDCC allows MCU specific storage class extensions, i.e.
9674  xdata will be treated as a storage class specifier when parsing 8051 C
9675  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
9676  C code.
9677 \layout Paragraph*
9678
9679 Generating iCode
9680 \layout Standard
9681
9682 Intermediate code generation.
9683  In this phase the AST is broken down into three-operand form (iCode).
9684  These three operand forms are represented as doubly linked lists.
9685  ICode is the term given to the intermediate form generated by the compiler.
9686  ICode example section shows some examples of iCode generated for some simple
9687  C source functions.
9688 \layout Paragraph*
9689
9690 Optimizations.
9691 \layout Standard
9692
9693 Bulk of the target independent optimizations is performed in this phase.
9694  The optimizations include constant propagation, common sub-expression eliminati
9695 on, loop invariant code movement, strength reduction of loop induction variables
9696  and dead-code elimination.
9697 \layout Paragraph*
9698
9699 Live range analysis
9700 \layout Standard
9701
9702 During intermediate code generation phase, the compiler assumes the target
9703  machine has infinite number of registers and generates a lot of temporary
9704  variables.
9705  The live range computation determines the lifetime of each of these compiler-ge
9706 nerated temporaries.
9707  A picture speaks a thousand words.
9708  ICode example sections show the live range annotations for each of the
9709  operand.
9710  It is important to note here, each iCode is assigned a number in the order
9711  of its execution in the function.
9712  The live ranges are computed in terms of these numbers.
9713  The from number is the number of the iCode which first defines the operand
9714  and the to number signifies the iCode which uses this operand last.
9715 \layout Paragraph*
9716
9717 Register Allocation
9718 \layout Standard
9719
9720 The register allocation determines the type and number of registers needed
9721  by each operand.
9722  In most MCUs only a few registers can be used for indirect addressing.
9723  In case of 8051 for example the registers R0 & R1 can be used to indirectly
9724  address the internal ram and DPTR to indirectly address the external ram.
9725  The compiler will try to allocate the appropriate register to pointer variables
9726  if it can.
9727  ICode example section shows the operands annotated with the registers assigned
9728  to them.
9729  The compiler will try to keep operands in registers as much as possible;
9730  there are several schemes the compiler uses to do achieve this.
9731  When the compiler runs out of registers the compiler will check to see
9732  if there are any live operands which is not used or defined in the current
9733  basic block being processed, if there are any found then it will push that
9734  operand and use the registers in this block, the operand will then be popped
9735  at the end of the basic block.
9736
9737 \layout Standard
9738
9739 There are other MCU specific considerations in this phase.
9740  Some MCUs have an accumulator; very short-lived operands could be assigned
9741  to the accumulator instead of general-purpose register.
9742 \layout Paragraph*
9743
9744 Code generation
9745 \layout Standard
9746
9747 Figure II gives a table of iCode operations supported by the compiler.
9748  The code generation involves translating these operations into corresponding
9749  assembly code for the processor.
9750  This sounds overly simple but that is the essence of code generation.
9751  Some of the iCode operations are generated on a MCU specific manner for
9752  example, the z80 port does not use registers to pass parameters so the
9753  SEND and RECV iCode operations will not be generated, and it also does
9754  not support JUMPTABLES.
9755
9756 \newline
9757
9758 \series bold
9759 \shape italic
9760 \color red
9761 <Where is Figure II ?>
9762 \layout Paragraph*
9763
9764 ICode Example
9765 \layout Standard
9766
9767 This section shows some details of iCode.
9768  The example C code does not do anything useful; it is used as an example
9769  to illustrate the intermediate code generated by the compiler.
9770 \newline
9771
9772 \newline
9773
9774 \family typewriter
9775 1.\SpecialChar ~
9776 xdata int * p;
9777 \newline
9778 2.\SpecialChar ~
9779 int gint;
9780 \newline
9781 3.\SpecialChar ~
9782 /* This function does nothing useful.
9783  It is used
9784 \newline
9785 4.\SpecialChar ~
9786 \SpecialChar ~
9787 \SpecialChar ~
9788 \SpecialChar ~
9789 for the purpose of explaining iCode */
9790 \newline
9791 5.\SpecialChar ~
9792 short function (data int *x)
9793 \newline
9794 6.\SpecialChar ~
9795 {
9796 \newline
9797 7.\SpecialChar ~
9798 \SpecialChar ~
9799 \SpecialChar ~
9800 short i=10; /* dead initialization eliminated */
9801 \newline
9802 8.\SpecialChar ~
9803 \SpecialChar ~
9804 \SpecialChar ~
9805 short sum=10; /* dead initialization eliminated */
9806 \newline
9807 9.\SpecialChar ~
9808 \SpecialChar ~
9809 \SpecialChar ~
9810 short mul;
9811 \newline
9812 10.\SpecialChar ~
9813 \SpecialChar ~
9814 int j ;
9815 \newline
9816 11.\SpecialChar ~
9817 \SpecialChar ~
9818 while (*x) *x++ = *p++;
9819 \newline
9820 12.\SpecialChar ~
9821 \SpecialChar ~
9822 \SpecialChar ~
9823 \SpecialChar ~
9824 sum = 0 ;
9825 \newline
9826 13.\SpecialChar ~
9827 \SpecialChar ~
9828 mul = 0;
9829 \newline
9830 14.\SpecialChar ~
9831 \SpecialChar ~
9832 /* compiler detects i,j to be induction variables */
9833 \newline
9834 15.\SpecialChar ~
9835 \SpecialChar ~
9836 for (i = 0, j = 10 ; i < 10 ; i++, j---) {
9837 \newline
9838 16.\SpecialChar ~
9839 \SpecialChar ~
9840 \SpecialChar ~
9841 \SpecialChar ~
9842 sum += i;
9843 \newline
9844 17.\SpecialChar ~
9845 \SpecialChar ~
9846 \SpecialChar ~
9847 \SpecialChar ~
9848 mul += i * 3; /* this multiplication remains */
9849 \newline
9850 18.\SpecialChar ~
9851 \SpecialChar ~
9852 \SpecialChar ~
9853 \SpecialChar ~
9854 gint += j * 3;/* this multiplication changed to addition */
9855 \newline
9856 19.\SpecialChar ~
9857 \SpecialChar ~
9858 }
9859 \newline
9860 20.\SpecialChar ~
9861 \SpecialChar ~
9862 return sum+mul;
9863 \newline
9864 21.\SpecialChar ~
9865 }
9866 \newline
9867
9868 \newline
9869
9870 \family default
9871 In addition to the operands each iCode contains information about the filename
9872  and line it corresponds to in the source file.
9873  The first field in the listing should be interpreted as follows:
9874 \newline
9875
9876 \shape italic
9877 \size footnotesize
9878 Filename(linenumber: iCode Execution sequence number : ICode hash table
9879  key : loop depth of the iCode).
9880 \shape default
9881 \size default
9882
9883 \newline
9884 Then follows the human readable form of the ICode operation.
9885  Each operand of this triplet form can be of three basic types a) compiler
9886  generated temporary b) user defined variable c) a constant value.
9887  Note that local variables and parameters are replaced by compiler generated
9888  temporaries.
9889  Live ranges are computed only for temporaries (i.e.
9890  live ranges are not computed for global variables).
9891  Registers are allocated for temporaries only.
9892  Operands are formatted in the following manner:
9893 \newline
9894
9895 \shape italic
9896 \size footnotesize
9897 Operand Name [lr live-from : live-to ] { type information } [ registers
9898  allocated ].
9899 \shape default
9900 \size default
9901
9902 \newline
9903 As mentioned earlier the live ranges are computed in terms of the execution
9904  sequence number of the iCodes, for example
9905 \newline
9906 the iTemp0 is live from (i.e.
9907  first defined in iCode with execution sequence number 3, and is last used
9908  in the iCode with sequence number 5).
9909  For induction variables such as iTemp21 the live range computation extends
9910  the lifetime from the start to the end of the loop.
9911 \newline
9912 The register allocator used the live range information to allocate registers,
9913  the same registers may be used for different temporaries if their live
9914  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
9915  iTemp17 since their live ranges do not overlap.
9916  In addition the allocator also takes into consideration the type and usage
9917  of a temporary, for example itemp6 is a pointer to near space and is used
9918  as to fetch data from (i.e.
9919  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
9920  Some short lived temporaries are allocated to special registers which have
9921  meaning to the code generator e.g.
9922  iTemp13 is allocated to a pseudo register CC which tells the back end that
9923  the temporary is used only for a conditional jump the code generation makes
9924  use of this information to optimize a compare and jump ICode.
9925 \newline
9926 There are several loop optimizations performed by the compiler.
9927  It can detect induction variables iTemp21(i) and iTemp23(j).
9928  Also note the compiler does selective strength reduction, i.e.
9929  the multiplication of an induction variable in line 18 (gint = j * 3) is
9930  changed to addition, a new temporary iTemp17 is allocated and assigned
9931  a initial value, a constant 3 is then added for each iteration of the loop.
9932  The compiler does not change the multiplication in line 17 however since
9933  the processor does support an 8 * 8 bit multiplication.
9934 \newline
9935 Note the dead code elimination optimization eliminated the dead assignments
9936  in line 7 & 8 to I and sum respectively.
9937 \newline
9938
9939 \layout Standard
9940
9941
9942 \size footnotesize
9943 Sample.c (5:1:0:0) _entry($9) :
9944 \layout Standard
9945
9946
9947 \size footnotesize
9948 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
9949 \layout Standard
9950
9951
9952 \size footnotesize
9953 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
9954 \layout Standard
9955
9956
9957 \size footnotesize
9958 Sample.c(11:4:53:0) preHeaderLbl0($11) :
9959 \layout Standard
9960
9961
9962 \size footnotesize
9963 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
9964  * int}[r2]
9965 \layout Standard
9966
9967
9968 \size footnotesize
9969 Sample.c(11:6:5:1) _whilecontinue_0($1) :
9970 \layout Standard
9971
9972
9973 \size footnotesize
9974 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
9975  int}[r0]]
9976 \layout Standard
9977
9978
9979 \size footnotesize
9980 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
9981 \layout Standard
9982
9983
9984 \size footnotesize
9985 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
9986  * int}
9987 \layout Standard
9988
9989
9990 \size footnotesize
9991 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
9992  {short}
9993 \layout Standard
9994
9995
9996 \size footnotesize
9997 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
9998  * int}[DPTR]]
9999 \layout Standard
10000
10001
10002 \size footnotesize
10003 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
10004 }[r2 r3]
10005 \layout Standard
10006
10007
10008 \size footnotesize
10009 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
10010  * int}[r0] + 0x2 {short}
10011 \layout Standard
10012
10013
10014 \size footnotesize
10015 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
10016 \layout Standard
10017
10018
10019 \size footnotesize
10020 Sample.c(11:17:21:0)_whilebreak_0($3) :
10021 \layout Standard
10022
10023
10024 \size footnotesize
10025 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
10026 \layout Standard
10027
10028
10029 \size footnotesize
10030 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
10031 \layout Standard
10032
10033
10034 \size footnotesize
10035 Sample.c(15:20:54:0)preHeaderLbl1($13) :
10036 \layout Standard
10037
10038
10039 \size footnotesize
10040 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
10041 \layout Standard
10042
10043
10044 \size footnotesize
10045 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
10046 \layout Standard
10047
10048
10049 \size footnotesize
10050 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
10051 \layout Standard
10052
10053
10054 \size footnotesize
10055 Sample.c(15:24:26:1)_forcond_0($4) :
10056 \layout Standard
10057
10058
10059 \size footnotesize
10060 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
10061  < 0xa {short}
10062 \layout Standard
10063
10064
10065 \size footnotesize
10066 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
10067 \layout Standard
10068
10069
10070 \size footnotesize
10071 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
10072  + ITemp21 [lr21:38]{short}[r4]
10073 \layout Standard
10074
10075
10076 \size footnotesize
10077 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
10078  * 0x3 {short}
10079 \layout Standard
10080
10081
10082 \size footnotesize
10083 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
10084  + iTemp15 [lr29:30]{short}[r1]
10085 \layout Standard
10086
10087
10088 \size footnotesize
10089 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
10090  r0]- 0x3 {short}
10091 \layout Standard
10092
10093
10094 \size footnotesize
10095 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
10096 int}[r7 r0]
10097 \layout Standard
10098
10099
10100 \size footnotesize
10101 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
10102  + 0x1 {short}
10103 \layout Standard
10104
10105
10106 \size footnotesize
10107 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
10108  r6]- 0x1 {short}
10109 \layout Standard
10110
10111
10112 \size footnotesize
10113 Sample.c(19:38:47:1) goto _forcond_0($4)
10114 \layout Standard
10115
10116
10117 \size footnotesize
10118 Sample.c(19:39:48:0)_forbreak_0($7) :
10119 \layout Standard
10120
10121
10122 \size footnotesize
10123 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
10124  + ITemp11 [lr19:40]{short}[r3]
10125 \layout Standard
10126
10127
10128 \size footnotesize
10129 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
10130 \layout Standard
10131
10132
10133 \size footnotesize
10134 Sample.c(20:42:51:0)_return($8) :
10135 \layout Standard
10136
10137
10138 \size footnotesize
10139 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
10140 \size default
10141
10142 \newline
10143
10144 \newline
10145 Finally the code generated for this function:
10146 \newline
10147
10148 \layout Standard
10149
10150
10151 \size footnotesize
10152 .area DSEG (DATA)
10153 \layout Standard
10154
10155
10156 \size footnotesize
10157 _p::
10158 \layout Standard
10159
10160
10161 \size footnotesize
10162 \SpecialChar ~
10163 \SpecialChar ~
10164 .ds 2
10165 \layout Standard
10166
10167
10168 \size footnotesize
10169 _gint::
10170 \layout Standard
10171
10172
10173 \size footnotesize
10174 \SpecialChar ~
10175 \SpecialChar ~
10176 .ds 2
10177 \layout Standard
10178
10179
10180 \size footnotesize
10181 ; sample.c 5
10182 \layout Standard
10183
10184
10185 \size footnotesize
10186 ; ----------------------------------------------
10187 \layout Standard
10188
10189
10190 \size footnotesize
10191 ; function function
10192 \layout Standard
10193
10194
10195 \size footnotesize
10196 ; ----------------------------------------------
10197 \layout Standard
10198
10199
10200 \size footnotesize
10201 _function:
10202 \layout Standard
10203
10204
10205 \size footnotesize
10206 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
10207 \layout Standard
10208
10209
10210 \size footnotesize
10211 \SpecialChar ~
10212 \SpecialChar ~
10213 mov r2,dpl
10214 \layout Standard
10215
10216
10217 \size footnotesize
10218 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
10219 \layout Standard
10220
10221
10222 \size footnotesize
10223 \SpecialChar ~
10224 \SpecialChar ~
10225 mov ar0,r2
10226 \layout Standard
10227
10228
10229 \size footnotesize
10230 ;_whilecontinue_0($1) :
10231 \layout Standard
10232
10233
10234 \size footnotesize
10235 00101$:
10236 \layout Standard
10237
10238
10239 \size footnotesize
10240 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
10241 \layout Standard
10242
10243
10244 \size footnotesize
10245 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
10246 \layout Standard
10247
10248
10249 \size footnotesize
10250 \SpecialChar ~
10251 \SpecialChar ~
10252 mov ar2,@r0
10253 \layout Standard
10254
10255
10256 \size footnotesize
10257 \SpecialChar ~
10258 \SpecialChar ~
10259 inc r0
10260 \layout Standard
10261
10262
10263 \size footnotesize
10264 \SpecialChar ~
10265 \SpecialChar ~
10266 mov ar3,@r0
10267 \layout Standard
10268
10269
10270 \size footnotesize
10271 \SpecialChar ~
10272 \SpecialChar ~
10273 dec r0
10274 \layout Standard
10275
10276
10277 \size footnotesize
10278 \SpecialChar ~
10279 \SpecialChar ~
10280 mov a,r2
10281 \layout Standard
10282
10283
10284 \size footnotesize
10285 \SpecialChar ~
10286 \SpecialChar ~
10287 orl a,r3
10288 \layout Standard
10289
10290
10291 \size footnotesize
10292 \SpecialChar ~
10293 \SpecialChar ~
10294 jz 00103$
10295 \layout Standard
10296
10297
10298 \size footnotesize
10299 00114$:
10300 \layout Standard
10301
10302
10303 \size footnotesize
10304 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
10305 \layout Standard
10306
10307
10308 \size footnotesize
10309 \SpecialChar ~
10310 \SpecialChar ~
10311 mov dpl,_p
10312 \layout Standard
10313
10314
10315 \size footnotesize
10316 \SpecialChar ~
10317 \SpecialChar ~
10318 mov dph,(_p + 1)
10319 \layout Standard
10320
10321
10322 \size footnotesize
10323 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
10324 \layout Standard
10325
10326
10327 \size footnotesize
10328 \SpecialChar ~
10329 \SpecialChar ~
10330 mov a,#0x02
10331 \layout Standard
10332
10333
10334 \size footnotesize
10335 \SpecialChar ~
10336 \SpecialChar ~
10337 add a,_p
10338 \layout Standard
10339
10340
10341 \size footnotesize
10342 \SpecialChar ~
10343 \SpecialChar ~
10344 mov _p,a
10345 \layout Standard
10346
10347
10348 \size footnotesize
10349 \SpecialChar ~
10350 \SpecialChar ~
10351 clr a
10352 \layout Standard
10353
10354
10355 \size footnotesize
10356 \SpecialChar ~
10357 \SpecialChar ~
10358 addc a,(_p + 1)
10359 \layout Standard
10360
10361
10362 \size footnotesize
10363 \SpecialChar ~
10364 \SpecialChar ~
10365 mov (_p + 1),a
10366 \layout Standard
10367
10368
10369 \size footnotesize
10370 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
10371 \layout Standard
10372
10373
10374 \size footnotesize
10375 \SpecialChar ~
10376 \SpecialChar ~
10377 movx a,@dptr
10378 \layout Standard
10379
10380
10381 \size footnotesize
10382 \SpecialChar ~
10383 \SpecialChar ~
10384 mov r2,a
10385 \layout Standard
10386
10387
10388 \size footnotesize
10389 \SpecialChar ~
10390 \SpecialChar ~
10391 inc dptr
10392 \layout Standard
10393
10394
10395 \size footnotesize
10396 \SpecialChar ~
10397 \SpecialChar ~
10398 movx a,@dptr
10399 \layout Standard
10400
10401
10402 \size footnotesize
10403 \SpecialChar ~
10404 \SpecialChar ~
10405 mov r3,a
10406 \layout Standard
10407
10408
10409 \size footnotesize
10410 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
10411 \layout Standard
10412
10413
10414 \size footnotesize
10415 \SpecialChar ~
10416 \SpecialChar ~
10417 mov @r0,ar2
10418 \layout Standard
10419
10420
10421 \size footnotesize
10422 \SpecialChar ~
10423 \SpecialChar ~
10424 inc r0
10425 \layout Standard
10426
10427
10428 \size footnotesize
10429 \SpecialChar ~
10430 \SpecialChar ~
10431 mov @r0,ar3
10432 \layout Standard
10433
10434
10435 \size footnotesize
10436 ; iTemp6 [lr5:16]{_near * int}[r0] =
10437 \layout Standard
10438
10439
10440 \size footnotesize
10441 ; iTemp6 [lr5:16]{_near * int}[r0] +
10442 \layout Standard
10443
10444
10445 \size footnotesize
10446 ; 0x2 {short}
10447 \layout Standard
10448
10449
10450 \size footnotesize
10451 \SpecialChar ~
10452 \SpecialChar ~
10453 inc r0
10454 \layout Standard
10455
10456
10457 \size footnotesize
10458 ; goto _whilecontinue_0($1)
10459 \layout Standard
10460
10461
10462 \size footnotesize
10463 \SpecialChar ~
10464 \SpecialChar ~
10465 sjmp 00101$
10466 \layout Standard
10467
10468
10469 \size footnotesize
10470 ; _whilebreak_0($3) :
10471 \layout Standard
10472
10473
10474 \size footnotesize
10475 00103$:
10476 \layout Standard
10477
10478
10479 \size footnotesize
10480 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
10481 \layout Standard
10482
10483
10484 \size footnotesize
10485 \SpecialChar ~
10486 \SpecialChar ~
10487 mov r2,#0x00
10488 \layout Standard
10489
10490
10491 \size footnotesize
10492 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
10493 \layout Standard
10494
10495
10496 \size footnotesize
10497 \SpecialChar ~
10498 \SpecialChar ~
10499 mov r3,#0x00
10500 \layout Standard
10501
10502
10503 \size footnotesize
10504 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
10505 \layout Standard
10506
10507
10508 \size footnotesize
10509 \SpecialChar ~
10510 \SpecialChar ~
10511 mov r4,#0x00
10512 \layout Standard
10513
10514
10515 \size footnotesize
10516 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
10517 \layout Standard
10518
10519
10520 \size footnotesize
10521 \SpecialChar ~
10522 \SpecialChar ~
10523 mov r5,#0x0A
10524 \layout Standard
10525
10526
10527 \size footnotesize
10528 \SpecialChar ~
10529 \SpecialChar ~
10530 mov r6,#0x00
10531 \layout Standard
10532
10533
10534 \size footnotesize
10535 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
10536 \layout Standard
10537
10538
10539 \size footnotesize
10540 \SpecialChar ~
10541 \SpecialChar ~
10542 mov r7,#0x1E
10543 \layout Standard
10544
10545
10546 \size footnotesize
10547 \SpecialChar ~
10548 \SpecialChar ~
10549 mov r0,#0x00
10550 \layout Standard
10551
10552
10553 \size footnotesize
10554 ; _forcond_0($4) :
10555 \layout Standard
10556
10557
10558 \size footnotesize
10559 00104$:
10560 \layout Standard
10561
10562
10563 \size footnotesize
10564 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
10565 \layout Standard
10566
10567
10568 \size footnotesize
10569 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
10570 \layout Standard
10571
10572
10573 \size footnotesize
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 clr c
10577 \layout Standard
10578
10579
10580 \size footnotesize
10581 \SpecialChar ~
10582 \SpecialChar ~
10583 mov a,r4
10584 \layout Standard
10585
10586
10587 \size footnotesize
10588 \SpecialChar ~
10589 \SpecialChar ~
10590 xrl a,#0x80
10591 \layout Standard
10592
10593
10594 \size footnotesize
10595 \SpecialChar ~
10596 \SpecialChar ~
10597 subb a,#0x8a
10598 \layout Standard
10599
10600
10601 \size footnotesize
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 jnc 00107$
10605 \layout Standard
10606
10607
10608 \size footnotesize
10609 00115$:
10610 \layout Standard
10611
10612
10613 \size footnotesize
10614 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
10615 \layout Standard
10616
10617
10618 \size footnotesize
10619 ; iTemp21 [lr21:38]{short}[r4]
10620 \layout Standard
10621
10622
10623 \size footnotesize
10624 \SpecialChar ~
10625 \SpecialChar ~
10626 mov a,r4
10627 \layout Standard
10628
10629
10630 \size footnotesize
10631 \SpecialChar ~
10632 \SpecialChar ~
10633 add a,r2
10634 \layout Standard
10635
10636
10637 \size footnotesize
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 mov r2,a
10641 \layout Standard
10642
10643
10644 \size footnotesize
10645 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
10646 \layout Standard
10647
10648
10649 \size footnotesize
10650 \SpecialChar ~
10651 \SpecialChar ~
10652 mov b,#0x03
10653 \layout Standard
10654
10655
10656 \size footnotesize
10657 \SpecialChar ~
10658 \SpecialChar ~
10659 mov a,r4
10660 \layout Standard
10661
10662
10663 \size footnotesize
10664 \SpecialChar ~
10665 \SpecialChar ~
10666 mul ab
10667 \layout Standard
10668
10669
10670 \size footnotesize
10671 \SpecialChar ~
10672 \SpecialChar ~
10673 mov r1,a
10674 \layout Standard
10675
10676
10677 \size footnotesize
10678 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
10679 \layout Standard
10680
10681
10682 \size footnotesize
10683 ; iTemp15 [lr29:30]{short}[r1]
10684 \layout Standard
10685
10686
10687 \size footnotesize
10688 \SpecialChar ~
10689 \SpecialChar ~
10690 add a,r3
10691 \layout Standard
10692
10693
10694 \size footnotesize
10695 \SpecialChar ~
10696 \SpecialChar ~
10697 mov r3,a
10698 \layout Standard
10699
10700
10701 \size footnotesize
10702 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
10703 \layout Standard
10704
10705
10706 \size footnotesize
10707 \SpecialChar ~
10708 \SpecialChar ~
10709 mov a,r7
10710 \layout Standard
10711
10712
10713 \size footnotesize
10714 \SpecialChar ~
10715 \SpecialChar ~
10716 add a,#0xfd
10717 \layout Standard
10718
10719
10720 \size footnotesize
10721 \SpecialChar ~
10722 \SpecialChar ~
10723 mov r7,a
10724 \layout Standard
10725
10726
10727 \size footnotesize
10728 \SpecialChar ~
10729 \SpecialChar ~
10730 mov a,r0
10731 \layout Standard
10732
10733
10734 \size footnotesize
10735 \SpecialChar ~
10736 \SpecialChar ~
10737 addc a,#0xff
10738 \layout Standard
10739
10740
10741 \size footnotesize
10742 \SpecialChar ~
10743 \SpecialChar ~
10744 mov r0,a
10745 \layout Standard
10746
10747
10748 \size footnotesize
10749 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
10750 \layout Standard
10751
10752
10753 \size footnotesize
10754 \SpecialChar ~
10755 \SpecialChar ~
10756 mov a,r7
10757 \layout Standard
10758
10759
10760 \size footnotesize
10761 \SpecialChar ~
10762 \SpecialChar ~
10763 add a,_gint
10764 \layout Standard
10765
10766
10767 \size footnotesize
10768 \SpecialChar ~
10769 \SpecialChar ~
10770 mov _gint,a
10771 \layout Standard
10772
10773
10774 \size footnotesize
10775 \SpecialChar ~
10776 \SpecialChar ~
10777 mov a,r0
10778 \layout Standard
10779
10780
10781 \size footnotesize
10782 \SpecialChar ~
10783 \SpecialChar ~
10784 addc a,(_gint + 1)
10785 \layout Standard
10786
10787
10788 \size footnotesize
10789 \SpecialChar ~
10790 \SpecialChar ~
10791 mov (_gint + 1),a
10792 \layout Standard
10793
10794
10795 \size footnotesize
10796 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
10797 \layout Standard
10798
10799
10800 \size footnotesize
10801 \SpecialChar ~
10802 \SpecialChar ~
10803 inc r4
10804 \layout Standard
10805
10806
10807 \size footnotesize
10808 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
10809 \layout Standard
10810
10811
10812 \size footnotesize
10813 \SpecialChar ~
10814 \SpecialChar ~
10815 dec r5
10816 \layout Standard
10817
10818
10819 \size footnotesize
10820 \SpecialChar ~
10821 \SpecialChar ~
10822 cjne r5,#0xff,00104$
10823 \layout Standard
10824
10825
10826 \size footnotesize
10827 \SpecialChar ~
10828 \SpecialChar ~
10829 dec r6
10830 \layout Standard
10831
10832
10833 \size footnotesize
10834 ; goto _forcond_0($4)
10835 \layout Standard
10836
10837
10838 \size footnotesize
10839 \SpecialChar ~
10840 \SpecialChar ~
10841 sjmp 00104$
10842 \layout Standard
10843
10844
10845 \size footnotesize
10846 ; _forbreak_0($7) :
10847 \layout Standard
10848
10849
10850 \size footnotesize
10851 00107$:
10852 \layout Standard
10853
10854
10855 \size footnotesize
10856 ; ret iTemp24 [lr40:41]{short}
10857 \layout Standard
10858
10859
10860 \size footnotesize
10861 \SpecialChar ~
10862 \SpecialChar ~
10863 mov a,r3
10864 \layout Standard
10865
10866
10867 \size footnotesize
10868 \SpecialChar ~
10869 \SpecialChar ~
10870 add a,r2
10871 \layout Standard
10872
10873
10874 \size footnotesize
10875 \SpecialChar ~
10876 \SpecialChar ~
10877 mov dpl,a
10878 \layout Standard
10879
10880
10881 \size footnotesize
10882 ; _return($8) :
10883 \layout Standard
10884
10885
10886 \size footnotesize
10887 00108$:
10888 \layout Standard
10889
10890
10891 \size footnotesize
10892 \SpecialChar ~
10893 \SpecialChar ~
10894 ret
10895 \newline
10896
10897 \layout Subsection
10898
10899 A few words about basic block successors, predecessors and dominators
10900 \layout Standard
10901
10902 Successors are basic blocks that might execute after this basic block.
10903 \newline
10904 Predecessors are basic blocks that might execute before reaching this basic
10905  block.
10906 \newline
10907 Dominators are basic blocks that WILL execute before reaching this basic
10908  block.
10909 \newline
10910
10911 \layout Standard
10912
10913 [basic block 1]
10914 \layout Standard
10915
10916 if (something)
10917 \layout Standard
10918
10919 [basic block 2]
10920 \layout Standard
10921
10922 else
10923 \layout Standard
10924
10925 [basic block 3]
10926 \layout Standard
10927
10928 [basic block 4]
10929 \newline
10930
10931 \layout Standard
10932
10933 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
10934 \layout Standard
10935
10936 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
10937 \layout Standard
10938
10939 c) domVect of [BB4] = BB1 ...
10940  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
10941  was executed.
10942 \layout Section
10943
10944 Acknowledgments
10945 \layout Standard
10946
10947
10948 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
10949
10950 \end_inset
10951
10952
10953 \newline
10954
10955 \newline
10956
10957 \emph on
10958 Thanks to all the other volunteer developers who have helped with coding,
10959  testing, web-page creation, distribution sets, etc.
10960  You know who you are :-)
10961 \emph default
10962
10963 \newline
10964
10965 \layout Standard
10966
10967 This document was initially written by Sandeep Dutta
10968 \layout Standard
10969
10970 All product names mentioned herein may be trademarks of their respective
10971  companies.
10972
10973 \layout Standard
10974
10975
10976 \begin_inset LatexCommand \printindex{}
10977
10978 \end_inset
10979
10980
10981 \the_end