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

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