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