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