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