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