git.gag.com Git - fw/sdcc/blob - doc/sdccman.lyx

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