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

   1 #LyX 1.3 created this file. For more info see http://www.lyx.org/
   2 \lyxformat 221
   3 \textclass article
   4 \begin_preamble
   5 \usepackage[
   6   pdftitle={SDCC Compiler User Guide},
   7   pdfauthor={SDCC development team},
   8   pdfsubject={installation, user manual},
   9   pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
  10                embedded, GPL, manual, mcs51, PIC, small, Z80},
  11   colorlinks=true,
  12   linkcolor=blue] {hyperref}
  13 \date{}
  14 \end_preamble
  15 \language english
  16 \inputencoding default
  17 \fontscheme pslatex
  18 \graphics default
  19 \paperfontsize default
  20 \spacing single
  21 \papersize Default
  22 \paperpackage a4
  23 \use_geometry 1
  24 \use_amsmath 0
  25 \use_natbib 0
  26 \use_numerical_citations 0
  27 \paperorientation portrait
  28 \leftmargin 30mm
  29 \topmargin 10mm
  30 \rightmargin 25mm
  31 \bottommargin 15mm
  32 \secnumdepth 3
  33 \tocdepth 3
  34 \paragraph_separation indent
  35 \defskip medskip
  36 \quotes_language swedish
  37 \quotes_times 2
  38 \papercolumns 1
  39 \papersides 1
  40 \paperpagestyle fancy
  41
  42 \layout Comment
  43
  44 Please note: double dashed longoptions (e.g.
  45  --version) are written this way: -
  46 \begin_inset ERT
  47 status Collapsed
  48
  49 \layout Standard
  50
  51 \backslash
  52 /
  53 \end_inset
  54
  55 -
  56 \layout Comment
  57
  58 Two resp.
  59  three consecutive dashes simply result in a long resp.
  60  extra long dash.
  61 \layout Title
  62
  63 SDCC Compiler User Guide
  64 \layout Standard
  65 \align center
  66 2003-06-02
  67 \layout Comment
  68
  69 The strings enclosed in $ are automatically updated by cvs:
  70 \layout Standard
  71 \align center
  72
  73 \size scriptsize
  74 cvs: $Revision$ $Date$
  75 \layout Standard
  76
  77
  78 \begin_inset LatexCommand \tableofcontents{}
  79
  80 \end_inset
  81
  82
  83 \layout Section
  84 \pagebreak_top
  85 Introduction
  86 \layout Subsection
  87
  88 About SDCC
  89 \layout Standard
  90
  91
  92 \series bold
  93 SDCC
  94 \series default
  95  is a Freeware, retargettable, optimizing ANSI-C compiler by
  96 \series bold
  97 Sandeep Dutta
  98 \series default
  99  designed for 8 bit Microprocessors.
 100  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 101  8051, 8052
 102 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052 CPU}
 103
 104 \end_inset
 105
 106 , etc), Zilog Z80 based MCUs, and the Dallas DS80C390 variant.
 107  It can be retargetted for other microprocessors, support for PIC, AVR and
 108  186 is under development.
 109  The entire source code for the compiler is distributed under GPL.
 110  SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
 111  SDCC has extensive language extensions suitable for utilizing various microcont
 112 rollers and underlying hardware effectively.
 113
 114 \newline
 115
 116 \newline
 117 In addition to the MCU specific optimizations SDCC also does a host of standard
 118  optimizations like:
 119 \layout Itemize
 120
 121 global sub expression elimination,
 122 \layout Itemize
 123
 124 loop optimizations (loop invariant, strength reduction of induction variables
 125  and loop reversing),
 126 \layout Itemize
 127
 128 constant folding & propagation,
 129 \layout Itemize
 130
 131 copy propagation,
 132 \layout Itemize
 133
 134 dead code elimination
 135 \layout Itemize
 136
 137 jump tables for
 138 \emph on
 139 switch
 140 \emph default
 141  statements.
 142 \layout Standard
 143
 144 For the back-end SDCC uses a global register allocation scheme which should
 145  be well suited for other 8 bit MCUs.
 146
 147 \newline
 148
 149 \newline
 150 The peep hole optimizer uses a rule based substitution mechanism which is
 151  MCU independent.
 152
 153 \newline
 154
 155 \newline
 156 Supported data-types are:
 157 \layout Itemize
 158
 159 char (8 bits, 1 byte),
 160 \layout Itemize
 161
 162 short and int (16 bits, 2 bytes),
 163 \layout Itemize
 164
 165 long (32 bit, 4 bytes)
 166 \layout Itemize
 167
 168 float (4 byte IEEE).
 169
 170 \layout Standard
 171
 172 The compiler also allows
 173 \emph on
 174 inline assembler code
 175 \emph default
 176  to be embedded anywhere in a function.
 177  In addition, routines developed in assembly can also be called.
 178 \newline
 179
 180 \newline
 181 SDCC also provides an option (-
 182 \begin_inset ERT
 183 status Collapsed
 184
 185 \layout Standard
 186
 187 \backslash
 188 /
 189 \end_inset
 190
 191 -cyclomatic) to report the relative complexity of a function.
 192  These functions can then be further optimized, or hand coded in assembly
 193  if needed.
 194
 195 \newline
 196
 197 \newline
 198 SDCC also comes with a companion source level debugger SDCDB, the debugger
 199  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 200
 201 \newline
 202
 203 \newline
 204 The latest version can be downloaded from
 205 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 206
 207 \end_inset
 208
 209 .
 210
 211 \series bold
 212
 213 \series default
 214 \emph on
 215 Please note: the compiler will probably always be some steps ahead of this
 216  documentation
 217 \series bold
 218 \emph default
 219
 220 \begin_inset LatexCommand \index{Status of documentation}
 221
 222 \end_inset
 223
 224
 225 \begin_inset Foot
 226 collapsed false
 227
 228 \layout Standard
 229
 230 Obviously this has pros and cons
 231 \end_inset
 232
 233 .
 234 \layout Subsection
 235
 236 Open Source
 237 \layout Standard
 238
 239 All packages used in this compiler system are
 240 \emph on
 241 opensource
 242 \emph default
 243  and
 244 \emph on
 245 freeware
 246 \emph default
 247 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 248  etc) is distributed with the package.
 249  This documentation is maintained using a freeware word processor (LyX).
 250 \newline
 251 This program is free software; you can redistribute it and/or modify it
 252  under the terms of the GNU General Public License
 253 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 254
 255 \end_inset
 256
 257  as published by the Free Software Foundation; either version 2, or (at
 258  your option) any later version.
 259  This program is distributed in the hope that it will be useful, but WITHOUT
 260  ANY WARRANTY; without even the implied warranty
 261 \begin_inset LatexCommand \index{warranty}
 262
 263 \end_inset
 264
 265  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 266  See the GNU General Public License for more details.
 267  You should have received a copy of the GNU General Public License along
 268  with this program; if not, write to the Free Software Foundation, 59 Temple
 269  Place - Suite 330, Boston, MA 02111-1307, USA.
 270  In other words, you are welcome to use, share and improve this program.
 271  You are forbidden to forbid anyone else to use, share and improve what
 272  you give them.
 273  Help stamp out software-hoarding!
 274 \layout Subsection
 275
 276 Typographic conventions
 277 \begin_inset LatexCommand \index{Typographic conventions}
 278
 279 \end_inset
 280
 281
 282 \layout Standard
 283
 284 Throughout this manual, we will use the following convention.
 285  Commands you have to type in are printed in
 286 \family sans
 287 \series bold
 288 "sans serif"
 289 \series default
 290 .
 291
 292 \family default
 293  Code samples are printed in
 294 \family typewriter
 295 typewriter font.
 296
 297 \family default
 298  Interesting items and new terms are printed in
 299 \emph on
 300 italic.
 301 \layout Subsection
 302
 303 Compatibility with previous versions
 304 \layout Standard
 305
 306 This version has numerous bug fixes compared with the previous version.
 307  But we also introduced some incompatibilities with older versions.
 308  Not just for the fun of it, but to make the compiler more stable, efficient
 309  and ANSI compliant
 310 \begin_inset LatexCommand \index{ANSI-compliance}
 311
 312 \end_inset
 313
 314 .
 315
 316 \newline
 317
 318 \layout Itemize
 319
 320 short is now equivalent to int (16 bits), it used to be equivalent to char
 321  (8 bits) which is not ANSI compliant
 322 \layout Itemize
 323
 324 the default directory for gcc-builds where include, library and documentation
 325  files are stored is now in /usr/local/share
 326 \layout Itemize
 327
 328 char type parameters to vararg functions are casted to int unless explicitly
 329  casted, e.g.:
 330 \newline
 331
 332 \family typewriter
 333 \SpecialChar ~
 334 \SpecialChar ~
 335 char a=3;
 336 \newline
 337 \SpecialChar ~
 338 \SpecialChar ~
 339 printf ("%d %c
 340 \backslash
 341 n", a, (char)a);
 342 \family default
 343
 344 \newline
 345  will push a as an int and as a char resp.
 346 \layout Itemize
 347
 348 option -
 349 \begin_inset ERT
 350 status Collapsed
 351
 352 \layout Standard
 353
 354 \backslash
 355 /
 356 \end_inset
 357
 358 -regextend has been removed
 359 \layout Itemize
 360
 361 option -
 362 \begin_inset ERT
 363 status Collapsed
 364
 365 \layout Standard
 366
 367 \backslash
 368 /
 369 \end_inset
 370
 371 -noregparms has been removed
 372 \layout Itemize
 373
 374 option -
 375 \begin_inset ERT
 376 status Collapsed
 377
 378 \layout Standard
 379
 380 \backslash
 381 /
 382 \end_inset
 383
 384 -stack-after-data has been removed
 385 \layout Standard
 386
 387
 388 \emph on
 389 <pending: more incompatibilities?>
 390 \layout Subsection
 391
 392 System Requirements
 393 \layout Standard
 394
 395 What do you need before you start installation of SDCC? A computer, and
 396  a desire to compute.
 397  The preferred method of installation is to compile SDCC from source using
 398  GNU gcc and make.
 399  For Windows some pre-compiled binary distributions are available for your
 400  convenience.
 401  You should have some experience with command line tools and compiler use.
 402 \layout Subsection
 403
 404 Other Resources
 405 \layout Standard
 406
 407 The SDCC home page at
 408 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 409
 410 \end_inset
 411
 412  is a great place to find distribution sets.
 413  You can also find links to the user mailing lists that offer help or discuss
 414  SDCC with other SDCC users.
 415  Web links to other SDCC related sites can also be found here.
 416  This document can be found in the DOC directory of the source package as
 417  a text or HTML file.
 418  Some of the other tools (simulator and assembler) included with SDCC contain
 419  their own documentation and can be found in the source distribution.
 420  If you want the latest unreleased software, the complete source package
 421  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 422 \layout Comment
 423
 424 ANSI C reference / related tools / recommended reading / compiler building:
 425  Muchnik?
 426 \layout Subsection
 427
 428 Wishes for the future
 429 \layout Standard
 430
 431 There are (and always will be) some things that could be done.
 432  Here are some I can think of:
 433 \newline
 434
 435 \layout Standard
 436
 437
 438 \family typewriter
 439 char KernelFunction3(char p) at 0x340;
 440 \newline
 441
 442 \layout Standard
 443
 444
 445 \family typewriter
 446 code banking
 447 \begin_inset LatexCommand \index{code banking (not supported)}
 448
 449 \end_inset
 450
 451  support for mcs51
 452 \newline
 453
 454 \family default
 455 If you can think of some more, please see the chapter 9 about filing feature
 456  requests
 457 \begin_inset LatexCommand \index{Requesting features}
 458
 459 \end_inset
 460
 461
 462 \begin_inset LatexCommand \index{Feature request}
 463
 464 \end_inset
 465
 466 .
 467 \newline
 468
 469 \layout Section
 470 \pagebreak_top
 471 Installation
 472 \begin_inset LatexCommand \index{Installation}
 473
 474 \end_inset
 475
 476
 477 \layout Subsection
 478
 479 Configure Options
 480 \begin_inset LatexCommand \index{Options SDCC configuration}
 481
 482 \end_inset
 483
 484
 485 \layout Standard
 486
 487 The install paths, search paths and other options are defined when running
 488  'configure'.
 489  The defaults can be overridden by:
 490 \layout List
 491 \labelwidthstring 00.00.0000
 492
 493 -
 494 \begin_inset ERT
 495 status Collapsed
 496
 497 \layout Standard
 498
 499 \backslash
 500 /
 501 \end_inset
 502
 503 -prefix see table below
 504 \layout List
 505 \labelwidthstring 00.00.0000
 506
 507 -
 508 \begin_inset ERT
 509 status Collapsed
 510
 511 \layout Standard
 512
 513 \backslash
 514 /
 515 \end_inset
 516
 517 -exec_prefix see table below
 518 \layout List
 519 \labelwidthstring 00.00.0000
 520
 521 -
 522 \begin_inset ERT
 523 status Collapsed
 524
 525 \layout Standard
 526
 527 \backslash
 528 /
 529 \end_inset
 530
 531 -bindir see table below
 532 \layout List
 533 \labelwidthstring 00.00.0000
 534
 535 -
 536 \begin_inset ERT
 537 status Collapsed
 538
 539 \layout Standard
 540
 541 \backslash
 542 /
 543 \end_inset
 544
 545 -datadir see table below
 546 \layout List
 547 \labelwidthstring 00.00.0000
 548
 549 docdir environment variable, see table below
 550 \layout List
 551 \labelwidthstring 00.00.0000
 552
 553 include_dir_suffix environment variable, see table below
 554 \layout List
 555 \labelwidthstring 00.00.0000
 556
 557 lib_dir_suffix environment variable, see table below
 558 \layout List
 559 \labelwidthstring 00.00.0000
 560
 561 sdccconf_h_dir_separator environment variable, either / or
 562 \backslash
 563
 564 \backslash
 565  makes sense here.
 566  This character will only be used in sdccconf.h; don't forget it's a C-header,
 567  therefore a double-backslash is needed there.
 568 \layout List
 569 \labelwidthstring 00.00.0000
 570
 571 -
 572 \begin_inset ERT
 573 status Collapsed
 574
 575 \layout Standard
 576
 577 \backslash
 578 /
 579 \end_inset
 580
 581 -disable-mcs51-port Excludes the Intel mcs51 port
 582 \layout List
 583 \labelwidthstring 00.00.0000
 584
 585 -
 586 \begin_inset ERT
 587 status Collapsed
 588
 589 \layout Standard
 590
 591 \backslash
 592 /
 593 \end_inset
 594
 595 -disable-gbz80-port Excludes the Gameboy gbz80 port
 596 \layout List
 597 \labelwidthstring 00.00.0000
 598
 599 -
 600 \begin_inset ERT
 601 status Collapsed
 602
 603 \layout Standard
 604
 605 \backslash
 606 /
 607 \end_inset
 608
 609 -z80-port Excludes the z80 port
 610 \layout List
 611 \labelwidthstring 00.00.0000
 612
 613 -
 614 \begin_inset ERT
 615 status Collapsed
 616
 617 \layout Standard
 618
 619 \backslash
 620 /
 621 \end_inset
 622
 623 -disable-avr-port Excludes the AVR port
 624 \layout List
 625 \labelwidthstring 00.00.0000
 626
 627 -
 628 \begin_inset ERT
 629 status Collapsed
 630
 631 \layout Standard
 632
 633 \backslash
 634 /
 635 \end_inset
 636
 637 -disable-ds390-port Excludes the DS390 port
 638 \layout List
 639 \labelwidthstring 00.00.0000
 640
 641 -
 642 \begin_inset ERT
 643 status Collapsed
 644
 645 \layout Standard
 646
 647 \backslash
 648 /
 649 \end_inset
 650
 651 -disable-pic-port Excludes the PIC port
 652 \layout List
 653 \labelwidthstring 00.00.0000
 654
 655 -
 656 \begin_inset ERT
 657 status Collapsed
 658
 659 \layout Standard
 660
 661 \backslash
 662 /
 663 \end_inset
 664
 665 -disable-xa51-port Excludes the XA51 port
 666 \layout List
 667 \labelwidthstring 00.00.0000
 668
 669 -
 670 \begin_inset ERT
 671 status Collapsed
 672
 673 \layout Standard
 674
 675 \backslash
 676 /
 677 \end_inset
 678
 679 -disable-ucsim Disables configuring and building of ucsim
 680 \layout List
 681 \labelwidthstring 00.00.0000
 682
 683 -
 684 \begin_inset ERT
 685 status Collapsed
 686
 687 \layout Standard
 688
 689 \backslash
 690 /
 691 \end_inset
 692
 693 -disable-device-lib-build Disables automatically building device libraries
 694 \layout List
 695 \labelwidthstring 00.00.0000
 696
 697 -
 698 \begin_inset ERT
 699 status Collapsed
 700
 701 \layout Standard
 702
 703 \backslash
 704 /
 705 \end_inset
 706
 707 -disable-packihx Disables building packihx
 708 \layout List
 709 \labelwidthstring 00.00.0000
 710
 711 -
 712 \begin_inset ERT
 713 status Collapsed
 714
 715 \layout Standard
 716
 717 \backslash
 718 /
 719 \end_inset
 720
 721 -enable-libgc Use the Bohem memory allocator.
 722  Lower runtime footprint.
 723 \layout Standard
 724
 725 Furthermore the environment variables CC, CFLAGS, ...
 726  the tools and their arguments can be influenced.
 727  Please see `configure -
 728 \begin_inset ERT
 729 status Collapsed
 730
 731 \layout Standard
 732
 733 \backslash
 734 /
 735 \end_inset
 736
 737 -help` and the man/info pages of `configure` for details.
 738 \newline
 739
 740 \newline
 741 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 742  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 743 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 744  At the moment it's not possible to change the default settings (it was
 745  simply never required.
 746 \newline
 747
 748 \newline
 749 These configure options are compiled into the binaries, and can only be
 750  changed by rerunning 'configure' and recompiling SDCC.
 751  The configure options are written in
 752 \emph on
 753 italics
 754 \emph default
 755  to distinguish them from run time environment variables (see section search
 756  paths).
 757 \newline
 758
 759 \newline
 760 The settings for
 761 \begin_inset Quotes sld
 762 \end_inset
 763
 764 Win32 builds
 765 \begin_inset Quotes srd
 766 \end_inset
 767
 768  are used by the SDCC team to build the official Win32 binaries.
 769  The SDCC team uses Mingw32 to build the official Windows binaries, because
 770  it's
 771 \layout Enumerate
 772
 773 open source,
 774 \layout Enumerate
 775
 776 a gcc compiler and last but not least
 777 \layout Enumerate
 778
 779 the binaries can be built by cross compiling on Sourceforge's compile farm.
 780 \layout Standard
 781
 782 See the examples, how to pass the Win32 settings to 'configure'.
 783  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 784  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 785  for Win32.
 786 \newline
 787
 788 \newline
 789 These defaults are:
 790 \newline
 791
 792 \newline
 793
 794 \begin_inset  Tabular
 795 <lyxtabular version="3" rows="8" columns="3">
 796 <features>
 797 <column alignment="block" valignment="top" leftline="true" width="0in">
 798 <column alignment="block" valignment="top" leftline="true" width="0in">
 799 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 800 <row topline="true" bottomline="true">
 801 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 802 \begin_inset Text
 803
 804 \layout Standard
 805
 806 Variable
 807 \end_inset
 808 </cell>
 809 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 810 \begin_inset Text
 811
 812 \layout Standard
 813
 814 default
 815 \end_inset
 816 </cell>
 817 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 818 \begin_inset Text
 819
 820 \layout Standard
 821
 822 Win32 builds
 823 \end_inset
 824 </cell>
 825 </row>
 826 <row topline="true">
 827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 828 \begin_inset Text
 829
 830 \layout Standard
 831
 832
 833 \emph on
 834 PREFIX
 835 \end_inset
 836 </cell>
 837 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 838 \begin_inset Text
 839
 840 \layout Standard
 841
 842 /usr/local
 843 \end_inset
 844 </cell>
 845 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 846 \begin_inset Text
 847
 848 \layout Standard
 849
 850
 851 \backslash
 852 sdcc
 853 \end_inset
 854 </cell>
 855 </row>
 856 <row topline="true">
 857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 858 \begin_inset Text
 859
 860 \layout Standard
 861
 862
 863 \emph on
 864 EXEC_PREFIX
 865 \end_inset
 866 </cell>
 867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 868 \begin_inset Text
 869
 870 \layout Standard
 871
 872
 873 \emph on
 874 $PREFIX
 875 \end_inset
 876 </cell>
 877 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 878 \begin_inset Text
 879
 880 \layout Standard
 881
 882
 883 \emph on
 884 $PREFIX
 885 \end_inset
 886 </cell>
 887 </row>
 888 <row topline="true">
 889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 890 \begin_inset Text
 891
 892 \layout Standard
 893
 894
 895 \emph on
 896 BINDIR
 897 \end_inset
 898 </cell>
 899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 900 \begin_inset Text
 901
 902 \layout Standard
 903
 904
 905 \emph on
 906 $EXECPREFIX
 907 \emph default
 908 /bin
 909 \end_inset
 910 </cell>
 911 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 912 \begin_inset Text
 913
 914 \layout Standard
 915
 916
 917 \emph on
 918 $EXECPREFIX
 919 \emph default
 920
 921 \backslash
 922 bin
 923 \end_inset
 924 </cell>
 925 </row>
 926 <row topline="true">
 927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 928 \begin_inset Text
 929
 930 \layout Standard
 931
 932
 933 \emph on
 934 DATADIR
 935 \end_inset
 936 </cell>
 937 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 938 \begin_inset Text
 939
 940 \layout Standard
 941
 942
 943 \emph on
 944 $PREFIX
 945 \emph default
 946 /share
 947 \end_inset
 948 </cell>
 949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 950 \begin_inset Text
 951
 952 \layout Standard
 953
 954
 955 \emph on
 956 $PREFIX
 957 \end_inset
 958 </cell>
 959 </row>
 960 <row topline="true">
 961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 962 \begin_inset Text
 963
 964 \layout Standard
 965
 966
 967 \emph on
 968 DOCDIR
 969 \end_inset
 970 </cell>
 971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 972 \begin_inset Text
 973
 974 \layout Standard
 975
 976
 977 \emph on
 978 $DATADIR
 979 \emph default
 980 /sdcc/doc
 981 \end_inset
 982 </cell>
 983 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 984 \begin_inset Text
 985
 986 \layout Standard
 987
 988
 989 \emph on
 990 $DATADIR
 991 \emph default
 992
 993 \backslash
 994 doc
 995 \end_inset
 996 </cell>
 997 </row>
 998 <row topline="true">
 999 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1000 \begin_inset Text
1001
1002 \layout Standard
1003
1004
1005 \emph on
1006 INCLUDE_DIR_SUFFIX
1007 \end_inset
1008 </cell>
1009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1010 \begin_inset Text
1011
1012 \layout Standard
1013
1014 sdcc/include
1015 \end_inset
1016 </cell>
1017 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1018 \begin_inset Text
1019
1020 \layout Standard
1021
1022 include
1023 \end_inset
1024 </cell>
1025 </row>
1026 <row topline="true" bottomline="true">
1027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1028 \begin_inset Text
1029
1030 \layout Standard
1031
1032
1033 \emph on
1034 LIB_DIR_SUFFIX
1035 \end_inset
1036 </cell>
1037 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1038 \begin_inset Text
1039
1040 \layout Standard
1041
1042 sdcc/lib
1043 \end_inset
1044 </cell>
1045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1046 \begin_inset Text
1047
1048 \layout Standard
1049
1050 lib
1051 \end_inset
1052 </cell>
1053 </row>
1054 </lyxtabular>
1055
1056 \end_inset
1057
1058
1059 \newline
1060
1061 \newline
1062
1063 \newline
1064 'configure' also computes relative paths.
1065  This is needed for full relocatability of a binary package and to complete
1066  search paths (see section search paths below):
1067 \newline
1068
1069 \newline
1070
1071 \begin_inset  Tabular
1072 <lyxtabular version="3" rows="4" columns="3">
1073 <features>
1074 <column alignment="block" valignment="top" leftline="true" width="0in">
1075 <column alignment="block" valignment="top" leftline="true" width="0in">
1076 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1077 <row topline="true" bottomline="true">
1078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1079 \begin_inset Text
1080
1081 \layout Standard
1082
1083 Variable (computed)
1084 \end_inset
1085 </cell>
1086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1087 \begin_inset Text
1088
1089 \layout Standard
1090
1091 default
1092 \end_inset
1093 </cell>
1094 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1095 \begin_inset Text
1096
1097 \layout Standard
1098
1099 Win32 builds
1100 \end_inset
1101 </cell>
1102 </row>
1103 <row topline="true" bottomline="true">
1104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1105 \begin_inset Text
1106
1107 \layout Standard
1108
1109
1110 \emph on
1111 BIN2DATA_DIR
1112 \end_inset
1113 </cell>
1114 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1115 \begin_inset Text
1116
1117 \layout Standard
1118
1119 ../share
1120 \end_inset
1121 </cell>
1122 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1123 \begin_inset Text
1124
1125 \layout Standard
1126
1127 ..
1128 \backslash
1129
1130 \end_inset
1131 </cell>
1132 </row>
1133 <row bottomline="true">
1134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1135 \begin_inset Text
1136
1137 \layout Standard
1138
1139
1140 \emph on
1141 PREFIX2BIN_DIR
1142 \end_inset
1143 </cell>
1144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1145 \begin_inset Text
1146
1147 \layout Standard
1148
1149 bin
1150 \end_inset
1151 </cell>
1152 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1153 \begin_inset Text
1154
1155 \layout Standard
1156
1157 bin
1158 \end_inset
1159 </cell>
1160 </row>
1161 <row bottomline="true">
1162 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1163 \begin_inset Text
1164
1165 \layout Standard
1166
1167
1168 \emph on
1169 PREFIX2DATA_DIR
1170 \end_inset
1171 </cell>
1172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1173 \begin_inset Text
1174
1175 \layout Standard
1176
1177 share/sdcc
1178 \end_inset
1179 </cell>
1180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1181 \begin_inset Text
1182
1183 \layout Standard
1184
1185 \end_inset
1186 </cell>
1187 </row>
1188 </lyxtabular>
1189
1190 \end_inset
1191
1192
1193 \newline
1194
1195 \newline
1196 Examples:
1197 \layout LyX-Code
1198
1199 ./configure
1200 \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 cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1225 32'):
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 Cross compiling SDCC on Linux for Windows
2817 \layout Standard
2818
2819 With the Mingw32 gcc cross compiler 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 running 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 dependenci
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 command:
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 command:
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 privileges 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 web site 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 Phillips
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 separate modules in separate
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 Phillips 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 unnecessary 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 inter procedural 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 helpful 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 documented.
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 following is a generic pointer physically located in xdata space
6740  */
6741 \newline
6742 char * xdata p;
6743 \layout Standard
6744
6745 Well you get the idea.
6746
6747 \newline
6748
6749 \newline
6750 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
6751 \emph on
6752 generic
6753 \emph default
6754  pointers.
6755
6756 \size small
6757
6758 \newline
6759
6760 \newline
6761
6762 \size default
6763 The highest order byte of the
6764 \emph on
6765 generic
6766 \emph default
6767  pointers contains the data space information.
6768  Assembler support routines are called whenever data is stored or retrieved
6769  using
6770 \emph on
6771 generic
6772 \emph default
6773  pointers.
6774  These are useful for developing reusable library
6775 \begin_inset LatexCommand \index{Libraries}
6776
6777 \end_inset
6778
6779  routines.
6780  Explicitly specifying the pointer type will generate the most efficient
6781  code.
6782 \layout Subsection
6783
6784 Parameters
6785 \begin_inset LatexCommand \index{Parameters}
6786
6787 \end_inset
6788
6789  & Local Variables
6790 \begin_inset LatexCommand \index{Local variable}
6791
6792 \end_inset
6793
6794
6795 \layout Standard
6796
6797 Automatic (local) variables and parameters to functions can either be placed
6798  on the stack or in data-space.
6799  The default action of the compiler is to place these variables in the internal
6800  RAM (for small model) or external RAM (for large model).
6801  This in fact makes them
6802 \emph on
6803 static
6804 \begin_inset LatexCommand \index{static}
6805
6806 \end_inset
6807
6808
6809 \emph default
6810  so by default functions are non-reentrant
6811 \begin_inset LatexCommand \index{reentrant}
6812
6813 \end_inset
6814
6815 .
6816 \newline
6817
6818 \newline
6819 They can be placed on the stack
6820 \begin_inset LatexCommand \index{stack}
6821
6822 \end_inset
6823
6824  either by using the
6825 \emph on
6826  -
6827 \begin_inset ERT
6828 status Collapsed
6829
6830 \layout Standard
6831
6832 \backslash
6833 /
6834 \end_inset
6835
6836 -stack-auto
6837 \begin_inset LatexCommand \index{-\/-stack-auto}
6838
6839 \end_inset
6840
6841
6842 \emph default
6843  option or by using the
6844 \emph on
6845 reentrant
6846 \begin_inset LatexCommand \index{reentrant}
6847
6848 \end_inset
6849
6850
6851 \emph default
6852  keyword in the function declaration, e.g.:
6853 \layout Verse
6854
6855
6856 \family typewriter
6857 unsigned char foo(char i) reentrant
6858 \newline
6859 {
6860 \newline
6861 ...
6862
6863 \newline
6864 }
6865 \layout Standard
6866
6867 Since stack space on 8051 is limited, the
6868 \emph on
6869 reentrant
6870 \emph default
6871 keyword or the
6872 \emph on
6873  -
6874 \begin_inset ERT
6875 status Collapsed
6876
6877 \layout Standard
6878
6879 \backslash
6880 /
6881 \end_inset
6882
6883 -stack-auto
6884 \emph default
6885  option should be used sparingly.
6886  Note that the reentrant keyword just means that the parameters & local
6887  variables will be allocated to the stack, it
6888 \emph on
6889 does not
6890 \emph default
6891  mean that the function is register bank independent.
6892 \newline
6893
6894 \newline
6895 Local variables can be assigned storage classes and absolute
6896 \begin_inset LatexCommand \index{Absolute addressing}
6897
6898 \end_inset
6899
6900  addresses, e.g.:
6901 \layout Verse
6902
6903
6904 \family typewriter
6905 unsigned char foo() {
6906 \newline
6907 \SpecialChar ~
6908 \SpecialChar ~
6909 \SpecialChar ~
6910 \SpecialChar ~
6911 xdata unsigned char i;
6912 \newline
6913 \SpecialChar ~
6914 \SpecialChar ~
6915 \SpecialChar ~
6916 \SpecialChar ~
6917 bit bvar;
6918 \newline
6919 \SpecialChar ~
6920 \SpecialChar ~
6921 \SpecialChar ~
6922 \SpecialChar ~
6923 data at 0x31 unsigned char j;
6924 \newline
6925 \SpecialChar ~
6926 \SpecialChar ~
6927 \SpecialChar ~
6928 \SpecialChar ~
6929 ...
6930
6931 \newline
6932 }
6933 \layout Standard
6934
6935 In the above example the variable
6936 \emph on
6937 i
6938 \emph default
6939  will be allocated in the external ram,
6940 \emph on
6941 bvar
6942 \emph default
6943  in bit addressable space and
6944 \emph on
6945  j
6946 \emph default
6947  in internal ram.
6948  When compiled with
6949 \emph on
6950 -
6951 \begin_inset ERT
6952 status Collapsed
6953
6954 \layout Standard
6955
6956 \backslash
6957 /
6958 \end_inset
6959
6960 -stack-auto
6961 \emph default
6962  or when a function is declared as
6963 \emph on
6964 reentrant
6965 \emph default
6966  this should only be done for static variables.
6967 \layout Standard
6968
6969 Parameters however are not allowed any storage class, (storage classes for
6970  parameters will be ignored), their allocation is governed by the memory
6971  model in use, and the reentrancy options.
6972 \layout Subsection
6973
6974 Overlaying
6975 \begin_inset LatexCommand \index{Overlaying}
6976
6977 \end_inset
6978
6979
6980 \layout Standard
6981
6982 For non-reentrant
6983 \begin_inset LatexCommand \index{reentrant}
6984
6985 \end_inset
6986
6987  functions SDCC will try to reduce internal ram space usage by overlaying
6988  parameters and local variables of a function (if possible).
6989  Parameters and local variables of a function will be allocated to an overlayabl
6990 e segment if the function has
6991 \emph on
6992 no other function calls and the function is non-reentrant and the memory
6993  model
6994 \begin_inset LatexCommand \index{Memory model}
6995
6996 \end_inset
6997
6998  is small.
6999
7000 \emph default
7001  If an explicit storage class
7002 \begin_inset LatexCommand \index{Storage class}
7003
7004 \end_inset
7005
7006  is specified for a local variable, it will NOT be overlayed.
7007 \layout Standard
7008
7009 Note that the compiler (not the linkage editor) makes the decision for overlayin
7010 g the data items.
7011  Functions that are called from an interrupt service routine should be preceded
7012  by a #pragma\SpecialChar ~
7013 NOOVERLAY
7014 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
7015
7016 \end_inset
7017
7018  if they are not reentrant.
7019 \layout Standard
7020
7021 Also note that the compiler does not do any processing of inline
7022 \begin_inset LatexCommand \index{inline}
7023
7024 \end_inset
7025
7026  assembler code, so the compiler might incorrectly assign local variables
7027  and parameters of a function into the overlay segment if the inline assembler
7028  code calls other c-functions that might use the overlay.
7029  In that case the #pragma\SpecialChar ~
7030 NOOVERLAY should be used.
7031 \layout Standard
7032
7033 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
7034 tion
7035 \begin_inset LatexCommand \index{Multiplication}
7036
7037 \end_inset
7038
7039  or division
7040 \begin_inset LatexCommand \index{Division}
7041
7042 \end_inset
7043
7044  will NOT be overlayed since these are implemented using external functions,
7045  e.g.:
7046 \layout Verse
7047
7048
7049 \family typewriter
7050 #pragma SAVE
7051 \newline
7052 #pragma NOOVERLAY
7053 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
7054
7055 \end_inset
7056
7057
7058 \newline
7059 void set_error(unsigned char errcd)
7060 \newline
7061 {
7062 \newline
7063 \SpecialChar ~
7064 \SpecialChar ~
7065 \SpecialChar ~
7066 \SpecialChar ~
7067 P3 = errcd;
7068 \newline
7069 }
7070 \newline
7071 #pragma RESTORE
7072 \newline
7073
7074 \newline
7075 void some_isr () interrupt
7076 \begin_inset LatexCommand \index{interrupt}
7077
7078 \end_inset
7079
7080  2 using
7081 \begin_inset LatexCommand \index{using}
7082
7083 \end_inset
7084
7085  1
7086 \newline
7087 {
7088 \newline
7089 \SpecialChar ~
7090 \SpecialChar ~
7091 \SpecialChar ~
7092 \SpecialChar ~
7093 ...
7094 \newline
7095 \SpecialChar ~
7096 \SpecialChar ~
7097 \SpecialChar ~
7098 \SpecialChar ~
7099 set_error(10);
7100 \newline
7101 \SpecialChar ~
7102 \SpecialChar ~
7103 \SpecialChar ~
7104 \SpecialChar ~
7105 ...
7106
7107 \newline
7108 }
7109 \layout Standard
7110
7111 In the above example the parameter
7112 \emph on
7113 errcd
7114 \emph default
7115  for the function
7116 \emph on
7117 set_error
7118 \emph default
7119  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
7120 NOOVERLAY was
7121  not present, this could cause unpredictable runtime behavior when called
7122  from an ISR.
7123  The #pragma\SpecialChar ~
7124 NOOVERLAY ensures that the parameters and local variables for
7125  the function are NOT overlayed.
7126 \layout Subsection
7127
7128 Interrupt Service Routines
7129 \layout Standard
7130
7131 SDCC allows interrupt service routines to be coded in C, with some extended
7132  keywords.
7133 \layout Verse
7134
7135
7136 \family typewriter
7137 void timer_isr (void) interrupt 2 using 1
7138 \newline
7139 {
7140 \newline
7141 ..
7142
7143 \newline
7144 }
7145 \layout Standard
7146
7147 The number following the
7148 \emph on
7149 interrupt
7150 \begin_inset LatexCommand \index{interrupt}
7151
7152 \end_inset
7153
7154
7155 \emph default
7156  keyword is the interrupt number this routine will service.
7157  The compiler will insert a call to this routine in the interrupt vector
7158  table for the interrupt number specified.
7159  The
7160 \emph on
7161 using
7162 \emph default
7163  keyword is used to tell the compiler to use the specified register bank
7164  (8051 specific) when generating code for this function.
7165  Note that when some function is called from an interrupt service routine
7166  it should be preceded by a #pragma\SpecialChar ~
7167 NOOVERLAY
7168 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
7169
7170 \end_inset
7171
7172  if it is not reentrant.
7173  A special note here, int (16 bit) and long (32 bit) integer division
7174 \begin_inset LatexCommand \index{Division}
7175
7176 \end_inset
7177
7178 , multiplication
7179 \begin_inset LatexCommand \index{Multiplication}
7180
7181 \end_inset
7182
7183  & modulus
7184 \begin_inset LatexCommand \index{Modulus}
7185
7186 \end_inset
7187
7188  operations are implemented using external support routines developed in
7189  ANSI-C, if an interrupt service routine needs to do any of these operations
7190  then the support routines (as mentioned in a following section) will have
7191  to be recompiled using the
7192 \emph on
7193  -
7194 \begin_inset ERT
7195 status Collapsed
7196
7197 \layout Standard
7198
7199 \backslash
7200 /
7201 \end_inset
7202
7203 -stack-auto
7204 \begin_inset LatexCommand \index{-\/-stack-auto}
7205
7206 \end_inset
7207
7208
7209 \emph default
7210  option and the source file will need to be compiled using the
7211 \emph on
7212 -
7213 \begin_inset ERT
7214 status Collapsed
7215
7216 \layout Standard
7217
7218 \backslash
7219 /
7220 \end_inset
7221
7222 -int-long-ren
7223 \emph default
7224 t
7225 \begin_inset LatexCommand \index{-\/-int-long-rent}
7226
7227 \end_inset
7228
7229  compiler option.
7230 \layout Standard
7231
7232 If you have multiple source files in your project, interrupt service routines
7233  can be present in any of them, but a prototype of the isr MUST be present
7234  or included in the file that contains the function
7235 \emph on
7236 main
7237 \emph default
7238 .
7239 \layout Standard
7240
7241 Interrupt Numbers and the corresponding address & descriptions for the Standard
7242  8051 are listed below.
7243  SDCC will automatically adjust the interrupt vector table to the maximum
7244  interrupt number specified.
7245 \newline
7246
7247 \layout Standard
7248
7249
7250 \begin_inset  Tabular
7251 <lyxtabular version="3" rows="6" columns="3">
7252 <features>
7253 <column alignment="block" valignment="top" leftline="true" width="0in">
7254 <column alignment="block" valignment="top" leftline="true" width="0in">
7255 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
7256 <row topline="true" bottomline="true">
7257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7258 \begin_inset Text
7259
7260 \layout Standard
7261
7262 Interrupt #
7263 \end_inset
7264 </cell>
7265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7266 \begin_inset Text
7267
7268 \layout Standard
7269
7270 Description
7271 \end_inset
7272 </cell>
7273 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7274 \begin_inset Text
7275
7276 \layout Standard
7277
7278 Vector Address
7279 \end_inset
7280 </cell>
7281 </row>
7282 <row topline="true">
7283 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7284 \begin_inset Text
7285
7286 \layout Standard
7287
7288 0
7289 \end_inset
7290 </cell>
7291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7292 \begin_inset Text
7293
7294 \layout Standard
7295
7296 External 0
7297 \end_inset
7298 </cell>
7299 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7300 \begin_inset Text
7301
7302 \layout Standard
7303
7304 0x0003
7305 \end_inset
7306 </cell>
7307 </row>
7308 <row topline="true">
7309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7310 \begin_inset Text
7311
7312 \layout Standard
7313
7314 1
7315 \end_inset
7316 </cell>
7317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7318 \begin_inset Text
7319
7320 \layout Standard
7321
7322 Timer 0
7323 \end_inset
7324 </cell>
7325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7326 \begin_inset Text
7327
7328 \layout Standard
7329
7330 0x000B
7331 \end_inset
7332 </cell>
7333 </row>
7334 <row topline="true">
7335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7336 \begin_inset Text
7337
7338 \layout Standard
7339
7340 2
7341 \end_inset
7342 </cell>
7343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7344 \begin_inset Text
7345
7346 \layout Standard
7347
7348 External 1
7349 \end_inset
7350 </cell>
7351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7352 \begin_inset Text
7353
7354 \layout Standard
7355
7356 0x0013
7357 \end_inset
7358 </cell>
7359 </row>
7360 <row topline="true">
7361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7362 \begin_inset Text
7363
7364 \layout Standard
7365
7366 3
7367 \end_inset
7368 </cell>
7369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7370 \begin_inset Text
7371
7372 \layout Standard
7373
7374 Timer 1
7375 \end_inset
7376 </cell>
7377 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7378 \begin_inset Text
7379
7380 \layout Standard
7381
7382 0x001B
7383 \end_inset
7384 </cell>
7385 </row>
7386 <row topline="true" bottomline="true">
7387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7388 \begin_inset Text
7389
7390 \layout Standard
7391
7392 4
7393 \end_inset
7394 </cell>
7395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7396 \begin_inset Text
7397
7398 \layout Standard
7399
7400 Serial
7401 \end_inset
7402 </cell>
7403 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7404 \begin_inset Text
7405
7406 \layout Standard
7407
7408 0x0023
7409 \end_inset
7410 </cell>
7411 </row>
7412 </lyxtabular>
7413
7414 \end_inset
7415
7416
7417 \newline
7418
7419 \newline
7420 If the interrupt service routine is defined without
7421 \emph on
7422 using
7423 \begin_inset LatexCommand \index{using}
7424
7425 \end_inset
7426
7427
7428 \emph default
7429  a register bank or with register bank 0 (using 0), the compiler will save
7430  the registers used by itself on the stack upon entry and restore them at
7431  exit, however if such an interrupt service routine calls another function
7432  then the entire register bank will be saved on the stack.
7433  This scheme may be advantageous for small interrupt service routines which
7434  have low register usage.
7435 \layout Standard
7436
7437 If the interrupt service routine is defined to be using a specific register
7438  bank then only
7439 \emph on
7440 a, b & dptr
7441 \emph default
7442  are save and restored, if such an interrupt service routine calls another
7443  function (using another register bank) then the entire register bank of
7444  the called function will be saved on the stack.
7445  This scheme is recommended for larger interrupt service routines.
7446 \layout Standard
7447
7448 Calling other functions from an interrupt service routine is not recommended,
7449  avoid it if possible.
7450 \newline
7451
7452 \newline
7453 Also see the _naked modifier.
7454 \layout Subsection
7455
7456 Critical Functions
7457 \layout Standard
7458
7459
7460 \shape italic
7461 <TODO: this isn't implemented at all!>
7462 \shape default
7463
7464 \newline
7465
7466 \newline
7467 A special keyword may be associated with a function declaring it as
7468 \emph on
7469 critical
7470 \emph default
7471 .
7472  SDCC will generate code to disable all interrupts upon entry to a critical
7473  function and enable them back before returning.
7474  Note that nesting critical functions may cause unpredictable results.
7475 \layout Verse
7476
7477
7478 \family typewriter
7479 int foo () critical
7480 \newline
7481 {
7482 \newline
7483 ...
7484
7485 \newline
7486 ...
7487
7488 \newline
7489 }
7490 \layout Standard
7491
7492 The critical attribute maybe used with other attributes like
7493 \emph on
7494 reentrant.
7495 \layout Subsection
7496
7497 Naked Functions
7498 \begin_inset LatexCommand \index{Naked functions}
7499
7500 \end_inset
7501
7502
7503 \layout Standard
7504
7505 A special keyword may be associated with a function declaring it as
7506 \emph on
7507 _naked
7508 \begin_inset LatexCommand \index{\_naked}
7509
7510 \end_inset
7511
7512 .
7513
7514 \emph default
7515 The
7516 \emph on
7517 _naked
7518 \emph default
7519  function modifier attribute prevents the compiler from generating prologue
7520 \begin_inset LatexCommand \index{function prologue}
7521
7522 \end_inset
7523
7524  and epilogue
7525 \begin_inset LatexCommand \index{function epilogue}
7526
7527 \end_inset
7528
7529  code for that function.
7530  This means that the user is entirely responsible for such things as saving
7531  any registers that may need to be preserved, selecting the proper register
7532  bank, generating the
7533 \emph on
7534 return
7535 \emph default
7536  instruction at the end, etc.
7537  Practically, this means that the contents of the function must be written
7538  in inline assembler.
7539  This is particularly useful for interrupt functions, which can have a large
7540  (and often unnecessary) prologue/epilogue.
7541  For example, compare the code generated by these two functions:
7542 \layout Verse
7543
7544
7545 \family typewriter
7546 data unsigned char counter;
7547 \newline
7548 void simpleInterrupt(void) interrupt
7549 \begin_inset LatexCommand \index{interrupt}
7550
7551 \end_inset
7552
7553  1
7554 \newline
7555 {
7556 \newline
7557 \SpecialChar ~
7558 \SpecialChar ~
7559 \SpecialChar ~
7560 \SpecialChar ~
7561 counter++;
7562 \newline
7563 }
7564 \newline
7565
7566 \newline
7567 void nakedInterrupt(void) interrupt 2 _naked
7568 \newline
7569 {
7570 \newline
7571 \SpecialChar ~
7572 \SpecialChar ~
7573 \SpecialChar ~
7574 \SpecialChar ~
7575 _asm
7576 \begin_inset LatexCommand \index{\_asm}
7577
7578 \end_inset
7579
7580
7581 \newline
7582 \SpecialChar ~
7583 \SpecialChar ~
7584 \SpecialChar ~
7585 \SpecialChar ~
7586 \SpecialChar ~
7587 \SpecialChar ~
7588 inc\SpecialChar ~
7589 \SpecialChar ~
7590 \SpecialChar ~
7591 \SpecialChar ~
7592 \SpecialChar ~
7593 _counter
7594 \newline
7595 \SpecialChar ~
7596 \SpecialChar ~
7597 \SpecialChar ~
7598 \SpecialChar ~
7599 \SpecialChar ~
7600 \SpecialChar ~
7601 reti\SpecialChar ~
7602 \SpecialChar ~
7603 \SpecialChar ~
7604 \SpecialChar ~
7605 ; MUST explicitly include ret in _naked function.
7606 \newline
7607 \SpecialChar ~
7608 \SpecialChar ~
7609 \SpecialChar ~
7610 \SpecialChar ~
7611 _endasm
7612 \begin_inset LatexCommand \index{\_endasm}
7613
7614 \end_inset
7615
7616 ;
7617 \newline
7618 }
7619 \layout Standard
7620
7621 For an 8051 target, the generated simpleInterrupt looks like:
7622 \layout Verse
7623
7624
7625 \family typewriter
7626 _simpleIterrupt:
7627 \newline
7628 \SpecialChar ~
7629 \SpecialChar ~
7630 \SpecialChar ~
7631 \SpecialChar ~
7632 push\SpecialChar ~
7633 \SpecialChar ~
7634 \SpecialChar ~
7635 \SpecialChar ~
7636 acc
7637 \newline
7638 \SpecialChar ~
7639 \SpecialChar ~
7640 \SpecialChar ~
7641 \SpecialChar ~
7642 push\SpecialChar ~
7643 \SpecialChar ~
7644 \SpecialChar ~
7645 \SpecialChar ~
7646 b
7647 \newline
7648 \SpecialChar ~
7649 \SpecialChar ~
7650 \SpecialChar ~
7651 \SpecialChar ~
7652 push\SpecialChar ~
7653 \SpecialChar ~
7654 \SpecialChar ~
7655 \SpecialChar ~
7656 dpl
7657 \newline
7658 \SpecialChar ~
7659 \SpecialChar ~
7660 \SpecialChar ~
7661 \SpecialChar ~
7662 push\SpecialChar ~
7663 \SpecialChar ~
7664 \SpecialChar ~
7665 \SpecialChar ~
7666 dph
7667 \newline
7668 \SpecialChar ~
7669 \SpecialChar ~
7670 \SpecialChar ~
7671 \SpecialChar ~
7672 push\SpecialChar ~
7673 \SpecialChar ~
7674 \SpecialChar ~
7675 \SpecialChar ~
7676 psw
7677 \newline
7678 \SpecialChar ~
7679 \SpecialChar ~
7680 \SpecialChar ~
7681 \SpecialChar ~
7682 mov\SpecialChar ~
7683 \SpecialChar ~
7684 \SpecialChar ~
7685 \SpecialChar ~
7686 \SpecialChar ~
7687 psw,#0x00
7688 \newline
7689 \SpecialChar ~
7690 \SpecialChar ~
7691 \SpecialChar ~
7692 \SpecialChar ~
7693 inc\SpecialChar ~
7694 \SpecialChar ~
7695 \SpecialChar ~
7696 \SpecialChar ~
7697 \SpecialChar ~
7698 _counter
7699 \newline
7700 \SpecialChar ~
7701 \SpecialChar ~
7702 \SpecialChar ~
7703 \SpecialChar ~
7704 pop\SpecialChar ~
7705 \SpecialChar ~
7706 \SpecialChar ~
7707 \SpecialChar ~
7708 \SpecialChar ~
7709 psw
7710 \newline
7711 \SpecialChar ~
7712 \SpecialChar ~
7713 \SpecialChar ~
7714 \SpecialChar ~
7715 pop\SpecialChar ~
7716 \SpecialChar ~
7717 \SpecialChar ~
7718 \SpecialChar ~
7719 \SpecialChar ~
7720 dph
7721 \newline
7722 \SpecialChar ~
7723 \SpecialChar ~
7724 \SpecialChar ~
7725 \SpecialChar ~
7726 pop\SpecialChar ~
7727 \SpecialChar ~
7728 \SpecialChar ~
7729 \SpecialChar ~
7730 \SpecialChar ~
7731 dpl
7732 \newline
7733 \SpecialChar ~
7734 \SpecialChar ~
7735 \SpecialChar ~
7736 \SpecialChar ~
7737 pop\SpecialChar ~
7738 \SpecialChar ~
7739 \SpecialChar ~
7740 \SpecialChar ~
7741 \SpecialChar ~
7742 b
7743 \newline
7744 \SpecialChar ~
7745 \SpecialChar ~
7746 \SpecialChar ~
7747 \SpecialChar ~
7748 pop\SpecialChar ~
7749 \SpecialChar ~
7750 \SpecialChar ~
7751 \SpecialChar ~
7752 \SpecialChar ~
7753 acc
7754 \newline
7755 \SpecialChar ~
7756 \SpecialChar ~
7757 \SpecialChar ~
7758 \SpecialChar ~
7759 reti
7760 \layout Standard
7761
7762 whereas nakedInterrupt looks like:
7763 \layout Verse
7764
7765
7766 \family typewriter
7767 _nakedInterrupt:
7768 \newline
7769 \SpecialChar ~
7770 \SpecialChar ~
7771 \SpecialChar ~
7772 \SpecialChar ~
7773 inc\SpecialChar ~
7774 \SpecialChar ~
7775 \SpecialChar ~
7776 \SpecialChar ~
7777 _counter
7778 \newline
7779 \SpecialChar ~
7780 \SpecialChar ~
7781 \SpecialChar ~
7782 \SpecialChar ~
7783 reti\SpecialChar ~
7784 \SpecialChar ~
7785 \SpecialChar ~
7786 ; MUST explicitly include ret(i) in _naked function.
7787 \layout Standard
7788
7789 While there is nothing preventing you from writing C code inside a _naked
7790  function, there are many ways to shoot yourself in the foot doing this,
7791  and it is recommended that you stick to inline assembler.
7792 \layout Subsection
7793
7794 Functions using private banks
7795 \begin_inset LatexCommand \index{bank}
7796
7797 \end_inset
7798
7799
7800 \layout Standard
7801
7802 The
7803 \emph on
7804 using
7805 \begin_inset LatexCommand \index{using}
7806
7807 \end_inset
7808
7809
7810 \emph default
7811  attribute (which tells the compiler to use a register bank other than the
7812  default bank zero) should only be applied to
7813 \emph on
7814 interrupt
7815 \begin_inset LatexCommand \index{interrupt}
7816
7817 \end_inset
7818
7819
7820 \emph default
7821  functions (see note 1 below).
7822  This will in most circumstances make the generated ISR code more efficient
7823  since it will not have to save registers on the stack.
7824 \layout Standard
7825
7826 The
7827 \emph on
7828 using
7829 \emph default
7830  attribute will have no effect on the generated code for a
7831 \emph on
7832 non-interrupt
7833 \emph default
7834  function (but may occasionally be useful anyway
7835 \begin_inset Foot
7836 collapsed false
7837
7838 \layout Standard
7839
7840 possible exception: if a function is called ONLY from 'interrupt' functions
7841  using a particular bank, it can be declared with the same 'using' attribute
7842  as the calling 'interrupt' functions.
7843  For instance, if you have several ISRs using bank one, and all of them
7844  call memcpy(), it might make sense to create a specialized version of memcpy()
7845  'using 1', since this would prevent the ISR from having to save bank zero
7846  to the stack on entry and switch to bank zero before calling the function
7847 \end_inset
7848
7849 ).
7850 \newline
7851
7852 \emph on
7853 (pending: I don't think this has been done yet)
7854 \layout Standard
7855
7856 An
7857 \emph on
7858 interrupt
7859 \emph default
7860  function using a non-zero bank will assume that it can trash that register
7861  bank, and will not save it.
7862  Since high-priority interrupts
7863 \begin_inset LatexCommand \index{interrupt priority}
7864
7865 \end_inset
7866
7867  can interrupt low-priority ones on the 8051 and friends, this means that
7868  if a high-priority ISR
7869 \emph on
7870 using
7871 \emph default
7872  a particular bank occurs while processing a low-priority ISR
7873 \emph on
7874 using
7875 \emph default
7876  the same bank, terrible and bad things can happen.
7877  To prevent this, no single register bank should be
7878 \emph on
7879 used
7880 \emph default
7881  by both a high priority and a low priority ISR.
7882  This is probably most easily done by having all high priority ISRs use
7883  one bank and all low priority ISRs use another.
7884  If you have an ISR which can change priority at runtime, you're on your
7885  own: I suggest using the default bank zero and taking the small performance
7886  hit.
7887 \layout Standard
7888
7889 It is most efficient if your ISR calls no other functions.
7890  If your ISR must call other functions, it is most efficient if those functions
7891  use the same bank as the ISR (see note 1 below); the next best is if the
7892  called functions use bank zero.
7893  It is very inefficient to call a function using a different, non-zero bank
7894  from an ISR.
7895
7896 \layout Subsection
7897
7898 Absolute Addressing
7899 \begin_inset LatexCommand \index{Absolute addressing}
7900
7901 \end_inset
7902
7903
7904 \layout Standard
7905
7906 Data items can be assigned an absolute address with the
7907 \emph on
7908 at
7909 \begin_inset LatexCommand \index{at}
7910
7911 \end_inset
7912
7913  <address>
7914 \emph default
7915  keyword, in addition to a storage class, e.g.:
7916 \layout Verse
7917
7918
7919 \family typewriter
7920 xdata
7921 \begin_inset LatexCommand \index{xdata}
7922
7923 \end_inset
7924
7925  at
7926 \begin_inset LatexCommand \index{at}
7927
7928 \end_inset
7929
7930  0x8000 unsigned char PORTA_8255 ;
7931 \layout Standard
7932
7933 In the above example the PORTA_8255 will be allocated to the location 0x8000
7934  of the external ram.
7935  Note that this feature is provided to give the programmer access to
7936 \emph on
7937 memory mapped
7938 \emph default
7939  devices attached to the controller.
7940  The compiler does not actually reserve any space for variables declared
7941  in this way (they are implemented with an equate in the assembler).
7942  Thus it is left to the programmer to make sure there are no overlaps with
7943  other variables that are declared without the absolute address.
7944  The assembler listing file (.lst
7945 \begin_inset LatexCommand \index{.lst}
7946
7947 \end_inset
7948
7949 ) and the linker output files (.rst
7950 \begin_inset LatexCommand \index{.rst}
7951
7952 \end_inset
7953
7954 ) and (.map
7955 \begin_inset LatexCommand \index{.map}
7956
7957 \end_inset
7958
7959 ) are a good places to look for such overlaps.
7960 \newline
7961
7962 \newline
7963 Absolute address can be specified for variables in all storage classes,
7964  e.g.:
7965 \layout Verse
7966
7967
7968 \family typewriter
7969 bit
7970 \begin_inset LatexCommand \index{bit}
7971
7972 \end_inset
7973
7974  at
7975 \begin_inset LatexCommand \index{at}
7976
7977 \end_inset
7978
7979  0x02 bvar;
7980 \layout Standard
7981
7982 The above example will allocate the variable at offset 0x02 in the bit-addressab
7983 le space.
7984  There is no real advantage to assigning absolute addresses to variables
7985  in this manner, unless you want strict control over all the variables allocated.
7986  One possible use would be to write hardware portable code.
7987  For example, if you have a routine that uses one or more of the microcontroller
7988  I/O pins, and such pins are different for two different hardwares, you
7989  can declare the I/O pins in you routine using
7990 \layout Verse
7991
7992
7993 \family typewriter
7994 extern bit SDI;
7995 \newline
7996 extern bit SCLK;
7997 \newline
7998 extern bit CPOL;
7999 \newline
8000
8001 \newline
8002 void DS1306_put(unsigned char value)
8003 \newline
8004 {
8005 \newline
8006 \SpecialChar ~
8007 \SpecialChar ~
8008 \SpecialChar ~
8009 \SpecialChar ~
8010 unsigned char mask=0x80;
8011 \newline
8012
8013 \newline
8014 \SpecialChar ~
8015 \SpecialChar ~
8016 \SpecialChar ~
8017 \SpecialChar ~
8018 while(mask)
8019 \newline
8020 \SpecialChar ~
8021 \SpecialChar ~
8022 \SpecialChar ~
8023 \SpecialChar ~
8024 {
8025 \newline
8026 \SpecialChar ~
8027 \SpecialChar ~
8028 \SpecialChar ~
8029 \SpecialChar ~
8030 \SpecialChar ~
8031 \SpecialChar ~
8032 \SpecialChar ~
8033 \SpecialChar ~
8034 SDI=(value & mask)?1:0;
8035 \newline
8036 \SpecialChar ~
8037 \SpecialChar ~
8038 \SpecialChar ~
8039 \SpecialChar ~
8040 \SpecialChar ~
8041 \SpecialChar ~
8042 \SpecialChar ~
8043 \SpecialChar ~
8044 SCLK=!CPOL;
8045 \newline
8046 \SpecialChar ~
8047 \SpecialChar ~
8048 \SpecialChar ~
8049 \SpecialChar ~
8050 \SpecialChar ~
8051 \SpecialChar ~
8052 \SpecialChar ~
8053 \SpecialChar ~
8054 SCLK=CPOL;
8055 \newline
8056 \SpecialChar ~
8057 \SpecialChar ~
8058 \SpecialChar ~
8059 \SpecialChar ~
8060 \SpecialChar ~
8061 \SpecialChar ~
8062 \SpecialChar ~
8063 \SpecialChar ~
8064 mask/=2;
8065 \newline
8066 \SpecialChar ~
8067 \SpecialChar ~
8068 \SpecialChar ~
8069 \SpecialChar ~
8070 }
8071 \newline
8072 }
8073 \layout Standard
8074
8075 Then, someplace in the code for the first hardware you would use
8076 \layout Verse
8077
8078
8079 \family typewriter
8080 bit at 0x80 SDI;\SpecialChar ~
8081 \SpecialChar ~
8082 \SpecialChar ~
8083 \SpecialChar ~
8084 /*I/O port 0, bit 0*/
8085 \newline
8086 bit at 0x81 SCLK;\SpecialChar ~
8087 \SpecialChar ~
8088 \SpecialChar ~
8089 /*I/O port 0, bit 1*/
8090 \newline
8091 bit CPOL;\SpecialChar ~
8092 \SpecialChar ~
8093 \SpecialChar ~
8094 \SpecialChar ~
8095 \SpecialChar ~
8096 \SpecialChar ~
8097 \SpecialChar ~
8098 \SpecialChar ~
8099 \SpecialChar ~
8100 \SpecialChar ~
8101 \SpecialChar ~
8102 /*This is a variable, let the linker allocate this one*/
8103 \layout Standard
8104
8105 Similarly, for the second hardware you would use
8106 \layout Verse
8107
8108
8109 \family typewriter
8110 bit at 0x83 SDI;\SpecialChar ~
8111 \SpecialChar ~
8112 \SpecialChar ~
8113 \SpecialChar ~
8114 /*I/O port 0, bit 3*/
8115 \newline
8116 bit at 0x91 SCLK;\SpecialChar ~
8117 \SpecialChar ~
8118 \SpecialChar ~
8119 /*I/O port 1, bit 1*/
8120 \newline
8121 bit CPOL;\SpecialChar ~
8122 \SpecialChar ~
8123 \SpecialChar ~
8124 \SpecialChar ~
8125 \SpecialChar ~
8126 \SpecialChar ~
8127 \SpecialChar ~
8128 \SpecialChar ~
8129 \SpecialChar ~
8130 \SpecialChar ~
8131 \SpecialChar ~
8132 /*This is a variable, let the linker allocate this one*/
8133 \layout Standard
8134
8135 and you can use the same hardware dependent routine without changes, as
8136  for example in a library.
8137  This is somehow similar to sbit, but only one absolute address has to be
8138  specified in the whole project.
8139 \layout Subsection
8140
8141 Startup Code
8142 \begin_inset LatexCommand \index{Startup code}
8143
8144 \end_inset
8145
8146
8147 \layout Standard
8148
8149 The compiler inserts a call to the C routine
8150 \emph on
8151 _sdcc_external_startup()
8152 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
8153
8154 \end_inset
8155
8156
8157 \series bold
8158 \emph default
8159
8160 \series default
8161 at the start of the CODE area.
8162  This routine is in the runtime library
8163 \begin_inset LatexCommand \index{Runtime library}
8164
8165 \end_inset
8166
8167 .
8168  By default this routine returns 0, if this routine returns a non-zero value,
8169  the static & global variable initialization will be skipped and the function
8170  main will be invoked Other wise static & global variables will be initialized
8171  before the function main is invoked.
8172  You could add a
8173 \emph on
8174 _sdcc_external_startup()
8175 \emph default
8176  routine to your program to override the default if you need to setup hardware
8177  or perform some other critical operation prior to static & global variable
8178  initialization.
8179 \layout Subsection
8180
8181 Inline Assembler Code
8182 \begin_inset LatexCommand \index{Assembler routines}
8183
8184 \end_inset
8185
8186
8187 \layout Standard
8188
8189 SDCC allows the use of in-line assembler with a few restriction as regards
8190  labels.
8191  All labels defined within inline assembler code
8192 \emph on
8193 has to be
8194 \emph default
8195  of the form
8196 \emph on
8197 nnnnn$
8198 \emph default
8199  where nnnn is a number less than 100 (which implies a limit of utmost 100
8200  inline assembler labels
8201 \emph on
8202 per function
8203 \emph default
8204 \noun on
8205 )
8206 \noun default
8207 .
8208  It is strongly recommended that each assembly instruction (including labels)
8209  be placed in a separate line (as the example shows).
8210  When the
8211 \emph on
8212 -
8213 \begin_inset ERT
8214 status Collapsed
8215
8216 \layout Standard
8217
8218 \backslash
8219 /
8220 \end_inset
8221
8222 -peep-asm
8223 \begin_inset LatexCommand \index{-\/-peep-asm}
8224
8225 \end_inset
8226
8227
8228 \emph default
8229  command line option is used, the inline assembler code will be passed through
8230  the peephole optimizer
8231 \begin_inset LatexCommand \index{Peephole optimizer}
8232
8233 \end_inset
8234
8235 .
8236  This might cause some unexpected changes in the inline assembler code.
8237  Please go through the peephole optimizer rules defined in file
8238 \emph on
8239 SDCCpeeph.def
8240 \emph default
8241  carefully before using this option.
8242 \layout Verse
8243
8244
8245 \family typewriter
8246 _asm
8247 \begin_inset LatexCommand \index{\_asm}
8248
8249 \end_inset
8250
8251
8252 \newline
8253 \SpecialChar ~
8254 \SpecialChar ~
8255 \SpecialChar ~
8256 \SpecialChar ~
8257 mov\SpecialChar ~
8258 \SpecialChar ~
8259 \SpecialChar ~
8260 \SpecialChar ~
8261 \SpecialChar ~
8262 b,#10
8263 \newline
8264 00001$:
8265 \newline
8266 \SpecialChar ~
8267 \SpecialChar ~
8268 \SpecialChar ~
8269 \SpecialChar ~
8270 djnz\SpecialChar ~
8271 \SpecialChar ~
8272 \SpecialChar ~
8273 \SpecialChar ~
8274 b,00001$
8275 \newline
8276 _endasm
8277 \begin_inset LatexCommand \index{\_endasm}
8278
8279 \end_inset
8280
8281  ;
8282 \layout Standard
8283
8284 The inline assembler code can contain any valid code understood by the assembler
8285 , this includes any assembler directives and comment lines.
8286  The compiler does not do any validation of the code within the
8287 \family typewriter
8288 _asm ...
8289  _endasm;
8290 \family default
8291  keyword pair.
8292
8293 \newline
8294
8295 \newline
8296 Inline assembler code cannot reference any C-Labels, however it can reference
8297  labels
8298 \begin_inset LatexCommand \index{Labels}
8299
8300 \end_inset
8301
8302  defined by the inline assembler, e.g.:
8303 \layout Verse
8304
8305
8306 \family typewriter
8307 foo() {
8308 \newline
8309 \SpecialChar ~
8310 \SpecialChar ~
8311 \SpecialChar ~
8312 \SpecialChar ~
8313 /* some c code */
8314 \newline
8315 \SpecialChar ~
8316 \SpecialChar ~
8317 \SpecialChar ~
8318 \SpecialChar ~
8319 _asm
8320 \newline
8321 \SpecialChar ~
8322 \SpecialChar ~
8323 \SpecialChar ~
8324 \SpecialChar ~
8325 \SpecialChar ~
8326 \SpecialChar ~
8327 ; some assembler code
8328 \newline
8329 \SpecialChar ~
8330 \SpecialChar ~
8331 \SpecialChar ~
8332 \SpecialChar ~
8333 \SpecialChar ~
8334 \SpecialChar ~
8335 ljmp $0003
8336 \newline
8337 \SpecialChar ~
8338 \SpecialChar ~
8339 \SpecialChar ~
8340 \SpecialChar ~
8341 _endasm;
8342 \newline
8343 \SpecialChar ~
8344 \SpecialChar ~
8345 \SpecialChar ~
8346 \SpecialChar ~
8347 /* some more c code */
8348 \newline
8349 clabel:\SpecialChar ~
8350 \SpecialChar ~
8351 /* inline assembler cannot reference this label */
8352 \newline
8353 \SpecialChar ~
8354 \SpecialChar ~
8355 \SpecialChar ~
8356 \SpecialChar ~
8357 _asm
8358 \newline
8359 \SpecialChar ~
8360 \SpecialChar ~
8361 \SpecialChar ~
8362 \SpecialChar ~
8363 $0003: ;label (can be reference by inline assembler only)
8364 \newline
8365 \SpecialChar ~
8366 \SpecialChar ~
8367 \SpecialChar ~
8368 \SpecialChar ~
8369 _endasm ;
8370 \newline
8371 \SpecialChar ~
8372 \SpecialChar ~
8373 \SpecialChar ~
8374 \SpecialChar ~
8375 /* some more c code */
8376 \newline
8377 }
8378 \layout Standard
8379
8380 In other words inline assembly code can access labels defined in inline
8381  assembly within the scope of the function.
8382  The same goes the other way, ie.
8383  labels defines in inline assembly CANNOT be accessed by C statements.
8384 \layout Subsection
8385
8386 int (16 bit)
8387 \begin_inset LatexCommand \index{int (16 bit)}
8388
8389 \end_inset
8390
8391  and long (32 bit)
8392 \begin_inset LatexCommand \index{long (32 bit)}
8393
8394 \end_inset
8395
8396  Support
8397 \layout Standard
8398
8399 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
8400  multiplication and modulus operations are implemented by support routines.
8401  These support routines are all developed in ANSI-C to facilitate porting
8402  to other MCUs, although some model specific assembler optimizations are
8403  used.
8404  The following files contain the described routine, all of them can be found
8405  in <installdir>/share/sdcc/lib.
8406 \newline
8407
8408 \newline
8409
8410 \begin_inset  Tabular
8411 <lyxtabular version="3" rows="11" columns="2">
8412 <features>
8413 <column alignment="center" valignment="top" leftline="true" width="0(null)">
8414 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
8415 <row topline="true" bottomline="true">
8416 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8417 \begin_inset Text
8418
8419 \layout Standard
8420
8421
8422 \series bold
8423 Function
8424 \end_inset
8425 </cell>
8426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8427 \begin_inset Text
8428
8429 \layout Standard
8430
8431
8432 \series bold
8433 Description
8434 \end_inset
8435 </cell>
8436 </row>
8437 <row topline="true">
8438 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8439 \begin_inset Text
8440
8441 \layout Standard
8442
8443 _mulint.c
8444 \end_inset
8445 </cell>
8446 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8447 \begin_inset Text
8448
8449 \layout Standard
8450
8451 16 bit multiplication
8452 \end_inset
8453 </cell>
8454 </row>
8455 <row topline="true">
8456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8457 \begin_inset Text
8458
8459 \layout Standard
8460
8461 _divsint.c
8462 \end_inset
8463 </cell>
8464 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8465 \begin_inset Text
8466
8467 \layout Standard
8468
8469  signed 16 bit division (calls _divuint)
8470 \end_inset
8471 </cell>
8472 </row>
8473 <row topline="true">
8474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8475 \begin_inset Text
8476
8477 \layout Standard
8478
8479 _divuint.c
8480 \end_inset
8481 </cell>
8482 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8483 \begin_inset Text
8484
8485 \layout Standard
8486
8487  unsigned 16 bit division
8488 \end_inset
8489 </cell>
8490 </row>
8491 <row topline="true">
8492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8493 \begin_inset Text
8494
8495 \layout Standard
8496
8497 _modsint.c
8498 \end_inset
8499 </cell>
8500 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8501 \begin_inset Text
8502
8503 \layout Standard
8504
8505 signed 16 bit modulus (calls _moduint)
8506 \end_inset
8507 </cell>
8508 </row>
8509 <row topline="true">
8510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8511 \begin_inset Text
8512
8513 \layout Standard
8514
8515 _moduint.c
8516 \end_inset
8517 </cell>
8518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8519 \begin_inset Text
8520
8521 \layout Standard
8522
8523 unsigned 16 bit modulus
8524 \end_inset
8525 </cell>
8526 </row>
8527 <row topline="true">
8528 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8529 \begin_inset Text
8530
8531 \layout Standard
8532
8533 _mullong.c
8534 \end_inset
8535 </cell>
8536 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8537 \begin_inset Text
8538
8539 \layout Standard
8540
8541 32 bit multiplication
8542 \end_inset
8543 </cell>
8544 </row>
8545 <row topline="true">
8546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8547 \begin_inset Text
8548
8549 \layout Standard
8550
8551 _divslong.c
8552 \end_inset
8553 </cell>
8554 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8555 \begin_inset Text
8556
8557 \layout Standard
8558
8559  signed 32 division (calls _divulong)
8560 \end_inset
8561 </cell>
8562 </row>
8563 <row topline="true">
8564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8565 \begin_inset Text
8566
8567 \layout Standard
8568
8569 _divulong.c
8570 \end_inset
8571 </cell>
8572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8573 \begin_inset Text
8574
8575 \layout Standard
8576
8577 unsigned 32 division
8578 \end_inset
8579 </cell>
8580 </row>
8581 <row topline="true">
8582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8583 \begin_inset Text
8584
8585 \layout Standard
8586
8587 _modslong.c
8588 \end_inset
8589 </cell>
8590 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8591 \begin_inset Text
8592
8593 \layout Standard
8594
8595  signed 32 bit modulus (calls _modulong)
8596 \end_inset
8597 </cell>
8598 </row>
8599 <row topline="true" bottomline="true">
8600 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8601 \begin_inset Text
8602
8603 \layout Standard
8604
8605 _modulong.c
8606 \end_inset
8607 </cell>
8608 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8609 \begin_inset Text
8610
8611 \layout Standard
8612
8613 unsigned 32 bit modulus
8614 \end_inset
8615 </cell>
8616 </row>
8617 </lyxtabular>
8618
8619 \end_inset
8620
8621
8622 \newline
8623
8624 \size footnotesize
8625
8626 \newline
8627
8628 \size default
8629 Since they are compiled as
8630 \emph on
8631 non-reentrant
8632 \emph default
8633
8634 \begin_inset LatexCommand \index{reentrant}
8635
8636 \end_inset
8637
8638 , interrupt
8639 \begin_inset LatexCommand \index{interrupt}
8640
8641 \end_inset
8642
8643  service routines should not do any of the above operations.
8644  If this is unavoidable then the above routines will need to be compiled
8645  with the
8646 \emph on
8647 -
8648 \begin_inset ERT
8649 status Collapsed
8650
8651 \layout Standard
8652
8653 \backslash
8654 /
8655 \end_inset
8656
8657 -stack-auto
8658 \begin_inset LatexCommand \index{-\/-stack-auto}
8659
8660 \end_inset
8661
8662
8663 \emph default
8664  option, after which the source program will have to be compiled with
8665 \emph on
8666 -
8667 \begin_inset ERT
8668 status Collapsed
8669
8670 \layout Standard
8671
8672 \backslash
8673 /
8674 \end_inset
8675
8676 -int-long-rent
8677 \begin_inset LatexCommand \index{-\/-int-long-rent}
8678
8679 \end_inset
8680
8681
8682 \emph default
8683  option.
8684  Notice that you don't have to call this routines directly.
8685  The compiler will use them automatically every time a integer operation
8686  is required.
8687 \layout Subsection
8688
8689 Floating Point Support
8690 \begin_inset LatexCommand \index{Floating point support}
8691
8692 \end_inset
8693
8694
8695 \layout Standard
8696
8697 SDCC supports IEEE (single precision 4bytes) floating point numbers.The floating
8698  point support routines are derived from gcc's floatlib.c and consists of
8699  the following routines:
8700 \newline
8701
8702 \newline
8703
8704 \size footnotesize
8705
8706 \begin_inset  Tabular
8707 <lyxtabular version="3" rows="17" columns="2">
8708 <features>
8709 <column alignment="center" valignment="top" leftline="true" width="0(null)">
8710 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
8711 <row topline="true" bottomline="true">
8712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8713 \begin_inset Text
8714
8715 \layout Standard
8716
8717
8718 \family roman
8719 \series medium
8720 \shape up
8721 \size normal
8722 \emph off
8723 \bar no
8724 \noun off
8725 \color none
8726 Function
8727 \end_inset
8728 </cell>
8729 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8730 \begin_inset Text
8731
8732 \layout Standard
8733
8734 Description
8735 \end_inset
8736 </cell>
8737 </row>
8738 <row topline="true">
8739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8740 \begin_inset Text
8741
8742 \layout Standard
8743
8744
8745 \family roman
8746 \series medium
8747 \shape up
8748 \size normal
8749 \emph off
8750 \bar no
8751 \noun off
8752 \color none
8753 _fsadd.c
8754 \end_inset
8755 </cell>
8756 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8757 \begin_inset Text
8758
8759 \layout Standard
8760
8761
8762 \family roman
8763 \series medium
8764 \shape up
8765 \size normal
8766 \emph off
8767 \bar no
8768 \noun off
8769 \color none
8770 add floating point numbers
8771 \end_inset
8772 </cell>
8773 </row>
8774 <row topline="true">
8775 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8776 \begin_inset Text
8777
8778 \layout Standard
8779
8780
8781 \family roman
8782 \series medium
8783 \shape up
8784 \size normal
8785 \emph off
8786 \bar no
8787 \noun off
8788 \color none
8789 _fssub.c
8790 \end_inset
8791 </cell>
8792 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8793 \begin_inset Text
8794
8795 \layout Standard
8796
8797
8798 \family roman
8799 \series medium
8800 \shape up
8801 \size normal
8802 \emph off
8803 \bar no
8804 \noun off
8805 \color none
8806 subtract floating point numbers
8807 \end_inset
8808 </cell>
8809 </row>
8810 <row topline="true">
8811 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8812 \begin_inset Text
8813
8814 \layout Standard
8815
8816
8817 \family roman
8818 \series medium
8819 \shape up
8820 \size normal
8821 \emph off
8822 \bar no
8823 \noun off
8824 \color none
8825 _fsdiv.c
8826 \end_inset
8827 </cell>
8828 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8829 \begin_inset Text
8830
8831 \layout Standard
8832
8833
8834 \family roman
8835 \series medium
8836 \shape up
8837 \size normal
8838 \emph off
8839 \bar no
8840 \noun off
8841 \color none
8842 divide floating point numbers
8843 \end_inset
8844 </cell>
8845 </row>
8846 <row topline="true">
8847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8848 \begin_inset Text
8849
8850 \layout Standard
8851
8852
8853 \family roman
8854 \series medium
8855 \shape up
8856 \size normal
8857 \emph off
8858 \bar no
8859 \noun off
8860 \color none
8861 _fsmul.c
8862 \end_inset
8863 </cell>
8864 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8865 \begin_inset Text
8866
8867 \layout Standard
8868
8869
8870 \family roman
8871 \series medium
8872 \shape up
8873 \size normal
8874 \emph off
8875 \bar no
8876 \noun off
8877 \color none
8878 multiply floating point numbers
8879 \end_inset
8880 </cell>
8881 </row>
8882 <row topline="true">
8883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8884 \begin_inset Text
8885
8886 \layout Standard
8887
8888
8889 \family roman
8890 \series medium
8891 \shape up
8892 \size normal
8893 \emph off
8894 \bar no
8895 \noun off
8896 \color none
8897 _fs2uchar.c
8898 \end_inset
8899 </cell>
8900 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8901 \begin_inset Text
8902
8903 \layout Standard
8904
8905
8906 \family roman
8907 \series medium
8908 \shape up
8909 \size normal
8910 \emph off
8911 \bar no
8912 \noun off
8913 \color none
8914 convert floating point to unsigned char
8915 \end_inset
8916 </cell>
8917 </row>
8918 <row topline="true">
8919 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8920 \begin_inset Text
8921
8922 \layout Standard
8923
8924
8925 \family roman
8926 \series medium
8927 \shape up
8928 \size normal
8929 \emph off
8930 \bar no
8931 \noun off
8932 \color none
8933 _fs2char.c
8934 \end_inset
8935 </cell>
8936 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8937 \begin_inset Text
8938
8939 \layout Standard
8940
8941
8942 \family roman
8943 \series medium
8944 \shape up
8945 \size normal
8946 \emph off
8947 \bar no
8948 \noun off
8949 \color none
8950 convert floating point to signed char
8951 \end_inset
8952 </cell>
8953 </row>
8954 <row topline="true">
8955 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8956 \begin_inset Text
8957
8958 \layout Standard
8959
8960
8961 \family roman
8962 \series medium
8963 \shape up
8964 \size normal
8965 \emph off
8966 \bar no
8967 \noun off
8968 \color none
8969 _fs2uint.c
8970 \end_inset
8971 </cell>
8972 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8973 \begin_inset Text
8974
8975 \layout Standard
8976
8977
8978 \family roman
8979 \series medium
8980 \shape up
8981 \size normal
8982 \emph off
8983 \bar no
8984 \noun off
8985 \color none
8986 convert floating point to unsigned int
8987 \end_inset
8988 </cell>
8989 </row>
8990 <row topline="true">
8991 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8992 \begin_inset Text
8993
8994 \layout Standard
8995
8996
8997 \family roman
8998 \series medium
8999 \shape up
9000 \size normal
9001 \emph off
9002 \bar no
9003 \noun off
9004 \color none
9005 _fs2int.c
9006 \end_inset
9007 </cell>
9008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9009 \begin_inset Text
9010
9011 \layout Standard
9012
9013
9014 \family roman
9015 \series medium
9016 \shape up
9017 \size normal
9018 \emph off
9019 \bar no
9020 \noun off
9021 \color none
9022 convert floating point to signed int
9023 \end_inset
9024 </cell>
9025 </row>
9026 <row topline="true">
9027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9028 \begin_inset Text
9029
9030 \layout Standard
9031
9032
9033 \family roman
9034 \series medium
9035 \shape up
9036 \size normal
9037 \emph off
9038 \bar no
9039 \noun off
9040 \color none
9041 _fs2ulong.
9042 \family default
9043 \series default
9044 \shape default
9045 \size default
9046 \emph default
9047 \bar default
9048 \noun default
9049 \color default
9050 c
9051 \end_inset
9052 </cell>
9053 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9054 \begin_inset Text
9055
9056 \layout Standard
9057
9058
9059 \family roman
9060 \series medium
9061 \shape up
9062 \size normal
9063 \emph off
9064 \bar no
9065 \noun off
9066 \color none
9067 convert floating point to unsigned long
9068 \end_inset
9069 </cell>
9070 </row>
9071 <row topline="true">
9072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9073 \begin_inset Text
9074
9075 \layout Standard
9076
9077
9078 \family roman
9079 \series medium
9080 \shape up
9081 \size normal
9082 \emph off
9083 \bar no
9084 \noun off
9085 \color none
9086 _fs2long.c
9087 \end_inset
9088 </cell>
9089 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9090 \begin_inset Text
9091
9092 \layout Standard
9093
9094
9095 \family roman
9096 \series medium
9097 \shape up
9098 \size normal
9099 \emph off
9100 \bar no
9101 \noun off
9102 \color none
9103 convert floating point to signed long
9104 \end_inset
9105 </cell>
9106 </row>
9107 <row topline="true">
9108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9109 \begin_inset Text
9110
9111 \layout Standard
9112
9113
9114 \family roman
9115 \series medium
9116 \shape up
9117 \size normal
9118 \emph off
9119 \bar no
9120 \noun off
9121 \color none
9122 _uchar2fs.c
9123 \end_inset
9124 </cell>
9125 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9126 \begin_inset Text
9127
9128 \layout Standard
9129
9130
9131 \family roman
9132 \series medium
9133 \shape up
9134 \size normal
9135 \emph off
9136 \bar no
9137 \noun off
9138 \color none
9139 convert unsigned char to floating point
9140 \end_inset
9141 </cell>
9142 </row>
9143 <row topline="true">
9144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9145 \begin_inset Text
9146
9147 \layout Standard
9148
9149
9150 \family roman
9151 \series medium
9152 \shape up
9153 \size normal
9154 \emph off
9155 \bar no
9156 \noun off
9157 \color none
9158 _char2fs.c
9159 \end_inset
9160 </cell>
9161 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9162 \begin_inset Text
9163
9164 \layout Standard
9165
9166
9167 \family roman
9168 \series medium
9169 \shape up
9170 \size normal
9171 \emph off
9172 \bar no
9173 \noun off
9174 \color none
9175 convert char to floating point number
9176 \end_inset
9177 </cell>
9178 </row>
9179 <row topline="true">
9180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9181 \begin_inset Text
9182
9183 \layout Standard
9184
9185
9186 \family roman
9187 \series medium
9188 \shape up
9189 \size normal
9190 \emph off
9191 \bar no
9192 \noun off
9193 \color none
9194 _uint2fs.c
9195 \end_inset
9196 </cell>
9197 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9198 \begin_inset Text
9199
9200 \layout Standard
9201
9202
9203 \family roman
9204 \series medium
9205 \shape up
9206 \size normal
9207 \emph off
9208 \bar no
9209 \noun off
9210 \color none
9211 convert unsigned int to floating point
9212 \end_inset
9213 </cell>
9214 </row>
9215 <row topline="true">
9216 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9217 \begin_inset Text
9218
9219 \layout Standard
9220
9221
9222 \family roman
9223 \series medium
9224 \shape up
9225 \size normal
9226 \emph off
9227 \bar no
9228 \noun off
9229 \color none
9230 _int2fs.c
9231 \end_inset
9232 </cell>
9233 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9234 \begin_inset Text
9235
9236 \layout Standard
9237
9238
9239 \family roman
9240 \series medium
9241 \shape up
9242 \size normal
9243 \emph off
9244 \bar no
9245 \noun off
9246 \color none
9247 convert int to floating point numbers
9248 \end_inset
9249 </cell>
9250 </row>
9251 <row topline="true">
9252 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9253 \begin_inset Text
9254
9255 \layout Standard
9256
9257
9258 \family roman
9259 \series medium
9260 \shape up
9261 \size normal
9262 \emph off
9263 \bar no
9264 \noun off
9265 \color none
9266 _ulong2fs.c
9267 \end_inset
9268 </cell>
9269 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9270 \begin_inset Text
9271
9272 \layout Standard
9273
9274
9275 \family roman
9276 \series medium
9277 \shape up
9278 \size normal
9279 \emph off
9280 \bar no
9281 \noun off
9282 \color none
9283 convert unsigned long to floating point number
9284 \end_inset
9285 </cell>
9286 </row>
9287 <row topline="true" bottomline="true">
9288 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9289 \begin_inset Text
9290
9291 \layout Standard
9292
9293
9294 \family roman
9295 \series medium
9296 \shape up
9297 \size normal
9298 \emph off
9299 \bar no
9300 \noun off
9301 \color none
9302 _long2fs.c
9303 \end_inset
9304 </cell>
9305 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9306 \begin_inset Text
9307
9308 \layout Standard
9309
9310
9311 \family roman
9312 \series medium
9313 \shape up
9314 \size normal
9315 \emph off
9316 \bar no
9317 \noun off
9318 \color none
9319 convert long to floating point number
9320 \end_inset
9321 </cell>
9322 </row>
9323 </lyxtabular>
9324
9325 \end_inset
9326
9327
9328 \newline
9329
9330 \size default
9331
9332 \newline
9333 Note if all these routines are used simultaneously the data space might
9334  overflow.
9335  For serious floating point usage it is strongly recommended that the large
9336  model be used.
9337  Also notice that you don't have to call this routines directly.
9338  The compiler will use them automatically every time a floating point operation
9339  is required.
9340 \layout Subsection
9341
9342 MCS51 Memory Models
9343 \begin_inset LatexCommand \index{Memory model}
9344
9345 \end_inset
9346
9347
9348 \begin_inset LatexCommand \index{MCS51 memory}
9349
9350 \end_inset
9351
9352
9353 \layout Standard
9354
9355 SDCC allows two memory models for MCS51 code, small and large.
9356  Modules compiled with different memory models should
9357 \emph on
9358 never
9359 \emph default
9360  be combined together or the results would be unpredictable.
9361  The library routines supplied with the compiler are compiled as both small
9362  and large.
9363  The compiled library modules are contained in separate directories as small
9364  and large so that you can link to either set.
9365
9366 \layout Standard
9367
9368 When the large model is used all variables declared without a storage class
9369  will be allocated into the external ram, this includes all parameters and
9370  local variables (for non-reentrant
9371 \begin_inset LatexCommand \index{reentrant}
9372
9373 \end_inset
9374
9375  functions).
9376  When the small model is used variables without storage class are allocated
9377  in the internal ram.
9378 \layout Standard
9379
9380 Judicious usage of the processor specific storage classes
9381 \begin_inset LatexCommand \index{Storage class}
9382
9383 \end_inset
9384
9385  and the 'reentrant' function type will yield much more efficient code,
9386  than using the large model.
9387  Several optimizations are disabled when the program is compiled using the
9388  large model, it is therefore strongly recommended that the small model
9389  be used unless absolutely required.
9390 \layout Subsection
9391
9392 DS390 Memory Models
9393 \begin_inset LatexCommand \index{Memory model}
9394
9395 \end_inset
9396
9397
9398 \begin_inset LatexCommand \index{DS390 memory model}
9399
9400 \end_inset
9401
9402
9403 \layout Standard
9404
9405 The only model supported is Flat 24
9406 \begin_inset LatexCommand \index{Flat 24 (memory model)}
9407
9408 \end_inset
9409
9410 .
9411  This generates code for the 24 bit contiguous addressing mode of the Dallas
9412  DS80C390 part.
9413  In this mode, up to four meg of external RAM or code space can be directly
9414  addressed.
9415  See the data sheets at www.dalsemi.com for further information on this part.
9416 \newline
9417
9418 \newline
9419 In older versions of the compiler, this option was used with the MCS51 code
9420  generator (
9421 \emph on
9422 -mmcs51
9423 \emph default
9424 ).
9425  Now, however, the '390 has it's own code generator, selected by the
9426 \emph on
9427 -mds390
9428 \emph default
9429  switch.
9430
9431 \newline
9432
9433 \newline
9434 Note that the compiler does not generate any code to place the processor
9435  into 24 bitmode (although
9436 \emph on
9437 tinibios
9438 \emph default
9439  in the ds390 libraries will do that for you).
9440  If you don't use
9441 \emph on
9442 tinibios
9443 \emph default
9444
9445 \begin_inset LatexCommand \index{Tinibios (DS390)}
9446
9447 \end_inset
9448
9449 , the boot loader or similar code must ensure that the processor is in 24
9450  bit contiguous addressing mode before calling the SDCC startup code.
9451 \newline
9452
9453 \newline
9454 Like the
9455 \emph on
9456 -
9457 \begin_inset ERT
9458 status Collapsed
9459
9460 \layout Standard
9461
9462 \backslash
9463 /
9464 \end_inset
9465
9466 -model-large
9467 \emph default
9468  option, variables will by default be placed into the XDATA segment.
9469
9470 \newline
9471
9472 \newline
9473 Segments may be placed anywhere in the 4 meg address space using the usual
9474  -
9475 \begin_inset ERT
9476 status Collapsed
9477
9478 \layout Standard
9479
9480 \backslash
9481 /
9482 \end_inset
9483
9484 -*-loc options.
9485  Note that if any segments are located above 64K, the -r flag must be passed
9486  to the linker to generate the proper segment relocations, and the Intel
9487  HEX output format must be used.
9488  The -r flag can be passed to the linker by using the option
9489 \emph on
9490 -Wl-r
9491 \emph default
9492  on the sdcc command line.
9493  However, currently the linker can not handle code segments > 64k.
9494 \layout Subsection
9495
9496 Defines Created by the Compiler
9497 \begin_inset LatexCommand \index{Defines created by the compiler}
9498
9499 \end_inset
9500
9501
9502 \layout Standard
9503
9504 The compiler creates the following #defines
9505 \begin_inset LatexCommand \index{\#defines}
9506
9507 \end_inset
9508
9509 .
9510 \layout Itemize
9511
9512 SDCC
9513 \begin_inset LatexCommand \index{SDCC}
9514
9515 \end_inset
9516
9517  - this Symbol is always defined.
9518 \layout Itemize
9519
9520 SDCC_mcs51
9521 \begin_inset LatexCommand \index{SDCC\_mcs51}
9522
9523 \end_inset
9524
9525  or SDCC_ds390
9526 \begin_inset LatexCommand \index{SDCC\_ds390}
9527
9528 \end_inset
9529
9530  or SDCC_z80
9531 \begin_inset LatexCommand \index{SDCC\_z80}
9532
9533 \end_inset
9534
9535 , etc - depending on the model used (e.g.: -mds390)
9536 \layout Itemize
9537
9538 __mcs51
9539 \begin_inset LatexCommand \index{\_\_mcs51}
9540
9541 \end_inset
9542
9543  or __ds390
9544 \begin_inset LatexCommand \index{\_\_ds390}
9545
9546 \end_inset
9547
9548  or __z80
9549 \begin_inset LatexCommand \index{\_\_z80}
9550
9551 \end_inset
9552
9553 , etc - depending on the model used (e.g.
9554  -mz80)
9555 \layout Itemize
9556
9557 SDCC_STACK_AUTO
9558 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
9559
9560 \end_inset
9561
9562  - this symbol is defined when
9563 \emph on
9564 -
9565 \begin_inset ERT
9566 status Collapsed
9567
9568 \layout Standard
9569
9570 \backslash
9571 /
9572 \end_inset
9573
9574 -stack-auto
9575 \emph default
9576  option is used.
9577 \layout Itemize
9578
9579 SDCC_MODEL_SMALL
9580 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
9581
9582 \end_inset
9583
9584  - when
9585 \emph on
9586 -
9587 \begin_inset ERT
9588 status Collapsed
9589
9590 \layout Standard
9591
9592 \backslash
9593 /
9594 \end_inset
9595
9596 -model-small
9597 \emph default
9598  is used.
9599 \layout Itemize
9600
9601 SDCC_MODEL_LARGE
9602 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
9603
9604 \end_inset
9605
9606  - when
9607 \emph on
9608 -
9609 \begin_inset ERT
9610 status Collapsed
9611
9612 \layout Standard
9613
9614 \backslash
9615 /
9616 \end_inset
9617
9618 -model-large
9619 \emph default
9620  is used.
9621 \layout Itemize
9622
9623 SDCC_USE_XSTACK
9624 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
9625
9626 \end_inset
9627
9628  - when
9629 \emph on
9630 -
9631 \begin_inset ERT
9632 status Collapsed
9633
9634 \layout Standard
9635
9636 \backslash
9637 /
9638 \end_inset
9639
9640 -xstack
9641 \emph default
9642  option is used.
9643 \layout Itemize
9644
9645 SDCC_STACK_TENBIT
9646 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
9647
9648 \end_inset
9649
9650  - when
9651 \emph on
9652 -mds390
9653 \emph default
9654  is used
9655 \layout Itemize
9656
9657 SDCC_MODEL_FLAT24
9658 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
9659
9660 \end_inset
9661
9662  - when
9663 \emph on
9664 -mds390
9665 \emph default
9666  is used
9667 \layout Section
9668 \pagebreak_top
9669 SDCC Technical Data
9670 \layout Subsection
9671
9672 Optimizations
9673 \begin_inset LatexCommand \index{Optimizations}
9674
9675 \end_inset
9676
9677
9678 \layout Standard
9679
9680 SDCC performs a host of standard optimizations in addition to some MCU specific
9681  optimizations.
9682
9683 \layout Subsubsection
9684
9685 Sub-expression Elimination
9686 \begin_inset LatexCommand \index{Subexpression elimination}
9687
9688 \end_inset
9689
9690
9691 \layout Standard
9692
9693 The compiler does local and global common subexpression elimination, e.g.:
9694
9695 \layout Verse
9696
9697
9698 \family typewriter
9699 i = x + y + 1;
9700 \newline
9701 j = x + y;
9702 \layout Standard
9703
9704 will be translated to
9705 \layout Verse
9706
9707
9708 \family typewriter
9709 iTemp = x + y
9710 \newline
9711 i = iTemp + 1
9712 \newline
9713 j = iTemp
9714 \layout Standard
9715
9716 Some subexpressions are not as obvious as the above example, e.g.:
9717 \layout Verse
9718
9719
9720 \family typewriter
9721 a->b[i].c = 10;
9722 \newline
9723 a->b[i].d = 11;
9724 \layout Standard
9725
9726 In this case the address arithmetic a->b[i] will be computed only once;
9727  the equivalent code in C would be.
9728 \layout Verse
9729
9730
9731 \family typewriter
9732 iTemp = a->b[i];
9733 \newline
9734 iTemp.c = 10;
9735 \newline
9736 iTemp.d = 11;
9737 \layout Standard
9738
9739 The compiler will try to keep these temporary variables in registers.
9740 \layout Subsubsection
9741
9742 Dead-Code Elimination
9743 \begin_inset LatexCommand \index{Dead-code elimination}
9744
9745 \end_inset
9746
9747
9748 \layout Verse
9749
9750
9751 \family typewriter
9752 int global;
9753 \newline
9754 void f () {
9755 \newline
9756 \SpecialChar ~
9757 \SpecialChar ~
9758 int i;
9759 \newline
9760 \SpecialChar ~
9761 \SpecialChar ~
9762 i = 1; \SpecialChar ~
9763 /* dead store */
9764 \newline
9765 \SpecialChar ~
9766 \SpecialChar ~
9767 global = 1;\SpecialChar ~
9768 /* dead store */
9769 \newline
9770 \SpecialChar ~
9771 \SpecialChar ~
9772 global = 2;
9773 \newline
9774 \SpecialChar ~
9775 \SpecialChar ~
9776 return;
9777 \newline
9778 \SpecialChar ~
9779 \SpecialChar ~
9780 global = 3;\SpecialChar ~
9781 /* unreachable */
9782 \newline
9783 }
9784 \layout Standard
9785
9786 will be changed to
9787 \layout Verse
9788
9789
9790 \family typewriter
9791 int global; void f ()
9792 \newline
9793 {
9794 \newline
9795 \SpecialChar ~
9796 \SpecialChar ~
9797 global = 2;
9798 \newline
9799 \SpecialChar ~
9800 \SpecialChar ~
9801 return;
9802 \newline
9803 }
9804 \layout Subsubsection
9805
9806 Copy-Propagation
9807 \begin_inset LatexCommand \index{Copy propagation}
9808
9809 \end_inset
9810
9811
9812 \layout Verse
9813
9814
9815 \family typewriter
9816 int f() {
9817 \newline
9818 \SpecialChar ~
9819 \SpecialChar ~
9820 int i, j;
9821 \newline
9822 \SpecialChar ~
9823 \SpecialChar ~
9824 i = 10;
9825 \newline
9826 \SpecialChar ~
9827 \SpecialChar ~
9828 j = i;
9829 \newline
9830 \SpecialChar ~
9831 \SpecialChar ~
9832 return j;
9833 \newline
9834 }
9835 \layout Standard
9836
9837 will be changed to
9838 \layout Verse
9839
9840
9841 \family typewriter
9842 int f() {
9843 \newline
9844 \SpecialChar ~
9845  \SpecialChar ~
9846  int i,j;
9847 \newline
9848 \SpecialChar ~
9849  \SpecialChar ~
9850  i = 10;
9851 \newline
9852 \SpecialChar ~
9853  \SpecialChar ~
9854  j = 10;
9855 \newline
9856 \SpecialChar ~
9857  \SpecialChar ~
9858  return 10;
9859 \newline
9860 }
9861 \layout Standard
9862
9863 Note: the dead stores created by this copy propagation will be eliminated
9864  by dead-code elimination.
9865 \layout Subsubsection
9866
9867 Loop Optimizations
9868 \begin_inset LatexCommand \index{Loop optimization}
9869
9870 \end_inset
9871
9872
9873 \layout Standard
9874
9875 Two types of loop optimizations are done by SDCC loop invariant lifting
9876  and strength reduction of loop induction variables.
9877  In addition to the strength reduction the optimizer marks the induction
9878  variables and the register allocator tries to keep the induction variables
9879  in registers for the duration of the loop.
9880  Because of this preference of the register allocator
9881 \begin_inset LatexCommand \index{Register allocation}
9882
9883 \end_inset
9884
9885 , loop induction optimization causes an increase in register pressure, which
9886  may cause unwanted spilling of other temporary variables into the stack
9887 \begin_inset LatexCommand \index{stack}
9888
9889 \end_inset
9890
9891  / data space.
9892  The compiler will generate a warning message when it is forced to allocate
9893  extra space either on the stack or data space.
9894  If this extra space allocation is undesirable then induction optimization
9895  can be eliminated either for the entire source file (with -
9896 \begin_inset ERT
9897 status Collapsed
9898
9899 \layout Standard
9900
9901 \backslash
9902 /
9903 \end_inset
9904
9905 -noinduction option) or for a given function only using #pragma\SpecialChar ~
9906 NOINDUCTION
9907 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
9908
9909 \end_inset
9910
9911 .
9912 \newline
9913
9914 \newline
9915 Loop Invariant:
9916 \layout Verse
9917
9918
9919 \family typewriter
9920 for (i = 0 ; i < 100 ; i ++)
9921 \newline
9922  \SpecialChar ~
9923  \SpecialChar ~
9924 f += k + l;
9925 \layout Standard
9926
9927 changed to
9928 \layout Verse
9929
9930
9931 \family typewriter
9932 itemp = k + l;
9933 \newline
9934 for (i = 0; i < 100; i++)
9935 \newline
9936 \SpecialChar ~
9937 \SpecialChar ~
9938 f += itemp;
9939 \layout Standard
9940
9941 As mentioned previously some loop invariants are not as apparent, all static
9942  address computations are also moved out of the loop.
9943 \newline
9944
9945 \newline
9946 Strength Reduction
9947 \begin_inset LatexCommand \index{Strength reduction}
9948
9949 \end_inset
9950
9951 , this optimization substitutes an expression by a cheaper expression:
9952 \layout Verse
9953
9954
9955 \family typewriter
9956 for (i=0;i < 100; i++)
9957 \newline
9958 \SpecialChar ~
9959 \SpecialChar ~
9960 ar[i*5] = i*3;
9961 \layout Standard
9962
9963 changed to
9964 \layout Verse
9965
9966
9967 \family typewriter
9968 itemp1 = 0;
9969 \newline
9970 itemp2 = 0;
9971 \newline
9972 for (i=0;i< 100;i++) {
9973 \newline
9974  \SpecialChar ~
9975  \SpecialChar ~
9976 ar[itemp1] = itemp2;
9977 \newline
9978  \SpecialChar ~
9979  \SpecialChar ~
9980 itemp1 += 5;
9981 \newline
9982  \SpecialChar ~
9983  \SpecialChar ~
9984 itemp2 += 3;
9985 \newline
9986 }
9987 \layout Standard
9988
9989 The more expensive multiplication
9990 \begin_inset LatexCommand \index{Multiplication}
9991
9992 \end_inset
9993
9994  is changed to a less expensive addition.
9995 \layout Subsubsection
9996
9997 Loop Reversing
9998 \begin_inset LatexCommand \index{Loop reversing}
9999
10000 \end_inset
10001
10002
10003 \layout Standard
10004
10005 This optimization is done to reduce the overhead of checking loop boundaries
10006  for every iteration.
10007  Some simple loops can be reversed and implemented using a
10008 \begin_inset Quotes eld
10009 \end_inset
10010
10011 decrement and jump if not zero
10012 \begin_inset Quotes erd
10013 \end_inset
10014
10015  instruction.
10016  SDCC checks for the following criterion to determine if a loop is reversible
10017  (note: more sophisticated compilers use data-dependency analysis to make
10018  this determination, SDCC uses a more simple minded analysis).
10019 \layout Itemize
10020
10021 The 'for' loop is of the form
10022 \newline
10023
10024 \newline
10025
10026 \family typewriter
10027 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
10028  += 1])
10029 \newline
10030 \SpecialChar ~
10031 \SpecialChar ~
10032 \SpecialChar ~
10033 \SpecialChar ~
10034 <for body>
10035 \layout Itemize
10036
10037 The <for body> does not contain
10038 \begin_inset Quotes eld
10039 \end_inset
10040
10041 continue
10042 \begin_inset Quotes erd
10043 \end_inset
10044
10045  or 'break
10046 \begin_inset Quotes erd
10047 \end_inset
10048
10049 .
10050 \layout Itemize
10051
10052 All goto's are contained within the loop.
10053 \layout Itemize
10054
10055 No function calls within the loop.
10056 \layout Itemize
10057
10058 The loop control variable <sym> is not assigned any value within the loop
10059 \layout Itemize
10060
10061 The loop control variable does NOT participate in any arithmetic operation
10062  within the loop.
10063 \layout Itemize
10064
10065 There are NO switch statements in the loop.
10066 \layout Subsubsection
10067
10068 Algebraic Simplifications
10069 \layout Standard
10070
10071 SDCC does numerous algebraic simplifications, the following is a small sub-set
10072  of these optimizations.
10073 \layout Verse
10074
10075
10076 \family typewriter
10077 i = j + 0 ; /* changed to */ i = j;
10078 \newline
10079 i /= 2; /* changed to */ i >>= 1;
10080 \newline
10081 i = j - j ; /* changed to */ i = 0;
10082 \newline
10083 i = j / 1 ; /* changed to */ i = j;
10084 \layout Standard
10085
10086 Note the subexpressions
10087 \begin_inset LatexCommand \index{Subexpression}
10088
10089 \end_inset
10090
10091  given above are generally introduced by macro expansions or as a result
10092  of copy/constant propagation.
10093 \layout Subsubsection
10094
10095 'switch' Statements
10096 \begin_inset LatexCommand \index{switch statement}
10097
10098 \end_inset
10099
10100
10101 \layout Standard
10102
10103 SDCC changes switch statements to jump tables
10104 \begin_inset LatexCommand \index{jump tables}
10105
10106 \end_inset
10107
10108  when the following conditions are true.
10109
10110 \layout Itemize
10111
10112 The case labels are in numerical sequence, the labels need not be in order,
10113  and the starting number need not be one or zero.
10114 \begin_deeper
10115 \layout Verse
10116
10117
10118 \family typewriter
10119 switch(i) {\SpecialChar ~
10120  \SpecialChar ~
10121  \SpecialChar ~
10122  \SpecialChar ~
10123  \SpecialChar ~
10124  \SpecialChar ~
10125  \SpecialChar ~
10126  \SpecialChar ~
10127  \SpecialChar ~
10128  \SpecialChar ~
10129  \SpecialChar ~
10130  \SpecialChar ~
10131  \SpecialChar ~
10132 switch (i) {
10133 \newline
10134 case 4:...
10135  \SpecialChar ~
10136  \SpecialChar ~
10137  \SpecialChar ~
10138  \SpecialChar ~
10139  \SpecialChar ~
10140  \SpecialChar ~
10141  \SpecialChar ~
10142  \SpecialChar ~
10143  \SpecialChar ~
10144  \SpecialChar ~
10145  \SpecialChar ~
10146  \SpecialChar ~
10147  \SpecialChar ~
10148 case 1: ...
10149
10150 \newline
10151 case 5:...
10152  \SpecialChar ~
10153  \SpecialChar ~
10154  \SpecialChar ~
10155  \SpecialChar ~
10156  \SpecialChar ~
10157  \SpecialChar ~
10158  \SpecialChar ~
10159  \SpecialChar ~
10160  \SpecialChar ~
10161  \SpecialChar ~
10162  \SpecialChar ~
10163  \SpecialChar ~
10164  \SpecialChar ~
10165 case 2: ...
10166
10167 \newline
10168 case 3:...
10169  \SpecialChar ~
10170  \SpecialChar ~
10171  \SpecialChar ~
10172  \SpecialChar ~
10173  \SpecialChar ~
10174  \SpecialChar ~
10175  \SpecialChar ~
10176  \SpecialChar ~
10177  \SpecialChar ~
10178  \SpecialChar ~
10179  \SpecialChar ~
10180  \SpecialChar ~
10181  \SpecialChar ~
10182 case 3: ...
10183
10184 \newline
10185 case 6:...
10186  \SpecialChar ~
10187  \SpecialChar ~
10188  \SpecialChar ~
10189  \SpecialChar ~
10190  \SpecialChar ~
10191  \SpecialChar ~
10192  \SpecialChar ~
10193  \SpecialChar ~
10194  \SpecialChar ~
10195  \SpecialChar ~
10196  \SpecialChar ~
10197  \SpecialChar ~
10198  \SpecialChar ~
10199 case 4: ...
10200
10201 \newline
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  \SpecialChar ~
10219  \SpecialChar ~
10220 }
10221 \layout Standard
10222
10223 Both the above switch statements will be implemented using a jump-table.
10224 \end_deeper
10225 \layout Itemize
10226
10227 The number of case labels is at least three, since it takes two conditional
10228  statements to handle the boundary conditions.
10229 \layout Itemize
10230
10231 The number of case labels is less than 84, since each label takes 3 bytes
10232  and a jump-table can be utmost 256 bytes long.
10233
10234 \layout Standard
10235
10236 Switch statements which have gaps in the numeric sequence or those that
10237  have more that 84 case labels can be split into more than one switch statement
10238  for efficient code generation, e.g.:
10239 \layout Verse
10240
10241
10242 \family typewriter
10243 switch (i) {
10244 \newline
10245 \SpecialChar ~
10246 \SpecialChar ~
10247 case 1: ...
10248
10249 \newline
10250 \SpecialChar ~
10251 \SpecialChar ~
10252 case 2: ...
10253
10254 \newline
10255 \SpecialChar ~
10256 \SpecialChar ~
10257 case 3: ...
10258
10259 \newline
10260 \SpecialChar ~
10261 \SpecialChar ~
10262 case 4: ...
10263
10264 \newline
10265 \SpecialChar ~
10266 \SpecialChar ~
10267 case 9: ...
10268
10269 \newline
10270 \SpecialChar ~
10271 \SpecialChar ~
10272 case 10: ...
10273
10274 \newline
10275 \SpecialChar ~
10276 \SpecialChar ~
10277 case 11: ...
10278
10279 \newline
10280 \SpecialChar ~
10281 \SpecialChar ~
10282 case 12: ...
10283
10284 \newline
10285 }
10286 \layout Standard
10287
10288 If the above switch statement is broken down into two switch statements
10289 \layout Verse
10290
10291
10292 \family typewriter
10293 switch (i) {
10294 \newline
10295 \SpecialChar ~
10296 \SpecialChar ~
10297 case 1: ...
10298
10299 \newline
10300 \SpecialChar ~
10301 \SpecialChar ~
10302 case 2: ...
10303
10304 \newline
10305 \SpecialChar ~
10306 \SpecialChar ~
10307 case 3: ...
10308
10309 \newline
10310 \SpecialChar ~
10311 \SpecialChar ~
10312 case 4: ...
10313
10314 \newline
10315 }
10316 \layout Standard
10317
10318 and
10319 \layout Verse
10320
10321
10322 \family typewriter
10323 switch (i) {
10324 \newline
10325 \SpecialChar ~
10326 \SpecialChar ~
10327 case 9: \SpecialChar ~
10328 ...
10329
10330 \newline
10331 \SpecialChar ~
10332 \SpecialChar ~
10333 case 10: ...
10334
10335 \newline
10336 \SpecialChar ~
10337 \SpecialChar ~
10338 case 11: ...
10339
10340 \newline
10341 \SpecialChar ~
10342 \SpecialChar ~
10343 case 12:\SpecialChar ~
10344 ...
10345
10346 \newline
10347 }
10348 \layout Standard
10349
10350 then both the switch statements will be implemented using jump-tables whereas
10351  the unmodified switch statement will not be.
10352 \layout Subsubsection
10353
10354 Bit-shifting Operations
10355 \begin_inset LatexCommand \index{Bit shifting}
10356
10357 \end_inset
10358
10359 .
10360 \layout Standard
10361
10362 Bit shifting is one of the most frequently used operation in embedded programmin
10363 g.
10364  SDCC tries to implement bit-shift operations in the most efficient way
10365  possible, e.g.:
10366 \layout Verse
10367
10368
10369 \family typewriter
10370 unsigned char i;
10371 \newline
10372 ...
10373
10374 \newline
10375 i>>= 4;
10376 \newline
10377 ...
10378 \layout Standard
10379
10380 generates the following code:
10381 \layout Verse
10382
10383
10384 \family typewriter
10385 mov a,_i
10386 \newline
10387 swap a
10388 \newline
10389 anl a,#0x0f
10390 \newline
10391 mov _i,a
10392 \layout Standard
10393
10394 In general SDCC will never setup a loop if the shift count is known.
10395  Another example:
10396 \layout Verse
10397
10398
10399 \family typewriter
10400 unsigned int i;
10401 \newline
10402 ...
10403
10404 \newline
10405 i >>= 9;
10406 \newline
10407 ...
10408 \layout Standard
10409
10410 will generate:
10411 \layout Verse
10412
10413
10414 \family typewriter
10415 mov a,(_i + 1)
10416 \newline
10417 mov (_i + 1),#0x00
10418 \newline
10419 clr c
10420 \newline
10421 rrc a
10422 \newline
10423 mov _i,a
10424 \layout Standard
10425
10426 Note that SDCC stores numbers in little-endian format (i.e.
10427  lowest order first).
10428 \layout Subsubsection
10429
10430 Bit-rotation
10431 \begin_inset LatexCommand \index{Bit rotation}
10432
10433 \end_inset
10434
10435
10436 \layout Standard
10437
10438 A special case of the bit-shift operation is bit rotation, SDCC recognizes
10439  the following expression to be a left bit-rotation:
10440 \layout Verse
10441
10442
10443 \family typewriter
10444 unsigned char i;
10445 \newline
10446 ...
10447
10448 \newline
10449 i = ((i << 1) | (i >> 7));
10450 \family default
10451
10452 \newline
10453
10454 \family typewriter
10455 ...
10456 \layout Standard
10457
10458 will generate the following code:
10459 \layout Verse
10460
10461
10462 \family typewriter
10463 mov a,_i
10464 \newline
10465 rl a
10466 \newline
10467 mov _i,a
10468 \layout Standard
10469
10470 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
10471 ns of this case will also be recognized as bit-rotation, i.e.:
10472 \layout Verse
10473
10474
10475 \family typewriter
10476 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
10477 \layout Subsubsection
10478
10479 Highest Order Bit
10480 \begin_inset LatexCommand \index{Highest Order Bit}
10481
10482 \end_inset
10483
10484
10485 \layout Standard
10486
10487 It is frequently required to obtain the highest order bit of an integral
10488  type (long, int, short or char types).
10489  SDCC recognizes the following expression to yield the highest order bit
10490  and generates optimized code for it, e.g.:
10491 \layout Verse
10492
10493
10494 \family typewriter
10495 unsigned int gint;
10496 \newline
10497
10498 \newline
10499 foo () {
10500 \newline
10501 unsigned char hob;
10502 \newline
10503 \SpecialChar ~
10504 \SpecialChar ~
10505 ...
10506
10507 \newline
10508 \SpecialChar ~
10509 \SpecialChar ~
10510 hob = (gint >> 15) & 1;
10511 \newline
10512 \SpecialChar ~
10513 \SpecialChar ~
10514 ..
10515
10516 \newline
10517 }
10518 \layout Standard
10519
10520 will generate the following code:
10521 \layout Verse
10522
10523
10524 \family typewriter
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 \SpecialChar ~
10549 \SpecialChar ~
10550  61 ;\SpecialChar ~
10551  hob.c 7
10552 \newline
10553 000A E5*01\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 \SpecialChar ~
10567 \SpecialChar ~
10568  62\SpecialChar ~
10569 \SpecialChar ~
10570 \SpecialChar ~
10571 \SpecialChar ~
10572 \SpecialChar ~
10573 \SpecialChar ~
10574 \SpecialChar ~
10575 \SpecialChar ~
10576  mov\SpecialChar ~
10577  a,(_gint + 1)
10578 \newline
10579 000C 33\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 \SpecialChar ~
10596 \SpecialChar ~
10597  63\SpecialChar ~
10598 \SpecialChar ~
10599 \SpecialChar ~
10600 \SpecialChar ~
10601 \SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 \SpecialChar ~
10605  rlc\SpecialChar ~
10606  a
10607 \newline
10608 000D E4\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 \SpecialChar ~
10625 \SpecialChar ~
10626  64\SpecialChar ~
10627 \SpecialChar ~
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 \SpecialChar ~
10633 \SpecialChar ~
10634  clr\SpecialChar ~
10635  a
10636 \newline
10637 000E 13\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 \SpecialChar ~
10654 \SpecialChar ~
10655  65\SpecialChar ~
10656 \SpecialChar ~
10657 \SpecialChar ~
10658 \SpecialChar ~
10659 \SpecialChar ~
10660 \SpecialChar ~
10661 \SpecialChar ~
10662 \SpecialChar ~
10663  rrc\SpecialChar ~
10664  a
10665 \newline
10666 000F F5*02\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 \SpecialChar ~
10680 \SpecialChar ~
10681  66\SpecialChar ~
10682 \SpecialChar ~
10683 \SpecialChar ~
10684 \SpecialChar ~
10685 \SpecialChar ~
10686 \SpecialChar ~
10687 \SpecialChar ~
10688 \SpecialChar ~
10689  mov\SpecialChar ~
10690  _foo_hob_1_1,a
10691 \layout Standard
10692
10693 Variations of this case however will
10694 \emph on
10695 not
10696 \emph default
10697  be recognized.
10698  It is a standard C expression, so I heartily recommend this be the only
10699  way to get the highest order bit, (it is portable).
10700  Of course it will be recognized even if it is embedded in other expressions,
10701  e.g.:
10702 \layout Verse
10703
10704
10705 \family typewriter
10706 xyz = gint + ((gint >> 15) & 1);
10707 \layout Standard
10708
10709 will still be recognized.
10710 \layout Subsubsection
10711
10712 Peephole Optimizer
10713 \begin_inset LatexCommand \index{Peephole optimizer}
10714
10715 \end_inset
10716
10717
10718 \layout Standard
10719
10720 The compiler uses a rule based, pattern matching and re-writing mechanism
10721  for peep-hole optimization.
10722  It is inspired by
10723 \emph on
10724 copt
10725 \emph default
10726  a peep-hole optimizer by Christopher W.
10727  Fraser (cwfraser@microsoft.com).
10728  A default set of rules are compiled into the compiler, additional rules
10729  may be added with the
10730 \emph on
10731 -
10732 \begin_inset ERT
10733 status Collapsed
10734
10735 \layout Standard
10736
10737 \backslash
10738 /
10739 \end_inset
10740
10741 -peep-file
10742 \begin_inset LatexCommand \index{-\/-peep-file}
10743
10744 \end_inset
10745
10746  <filename>
10747 \emph default
10748  option.
10749  The rule language is best illustrated with examples.
10750 \layout Verse
10751
10752
10753 \family typewriter
10754 replace {
10755 \newline
10756 \SpecialChar ~
10757 \SpecialChar ~
10758 mov %1,a
10759 \newline
10760 \SpecialChar ~
10761 \SpecialChar ~
10762 mov a,%1
10763 \newline
10764 } by {
10765 \newline
10766 \SpecialChar ~
10767 \SpecialChar ~
10768 mov %1,a
10769 \newline
10770 }
10771 \layout Standard
10772
10773 The above rule will change the following assembly
10774 \begin_inset LatexCommand \index{Assembler routines}
10775
10776 \end_inset
10777
10778  sequence:
10779 \layout Verse
10780
10781
10782 \family typewriter
10783 mov r1,a
10784 \newline
10785 mov a,r1
10786 \layout Standard
10787
10788 to
10789 \layout Verse
10790
10791
10792 \family typewriter
10793 mov r1,a
10794 \layout Standard
10795
10796 Note: All occurrences of a
10797 \emph on
10798 %n
10799 \emph default
10800  (pattern variable) must denote the same string.
10801  With the above rule, the assembly sequence:
10802 \layout Verse
10803
10804
10805 \family typewriter
10806 mov r1,a
10807 \newline
10808 mov a,r2
10809 \layout Standard
10810
10811 will remain unmodified.
10812 \newline
10813
10814 \newline
10815 Other special case optimizations may be added by the user (via
10816 \emph on
10817 -
10818 \begin_inset ERT
10819 status Collapsed
10820
10821 \layout Standard
10822
10823 \backslash
10824 /
10825 \end_inset
10826
10827 -peep-file option
10828 \emph default
10829 ).
10830  E.g.
10831  some variants of the 8051 MCU allow only
10832 \family typewriter
10833 ajmp
10834 \family default
10835  and
10836 \family typewriter
10837 acall
10838 \family default
10839 .
10840  The following two rules will change all
10841 \family typewriter
10842 ljmp
10843 \family default
10844  and
10845 \family typewriter
10846 lcall
10847 \family default
10848  to
10849 \family typewriter
10850 ajmp
10851 \family default
10852  and
10853 \family typewriter
10854 acall
10855 \layout Verse
10856
10857
10858 \family typewriter
10859 replace { lcall %1 } by { acall %1 }
10860 \newline
10861 replace { ljmp %1 } by { ajmp %1 }
10862 \layout Standard
10863
10864 The
10865 \emph on
10866 inline-assembler code
10867 \emph default
10868  is also passed through the peep hole optimizer, thus the peephole optimizer
10869  can also be used as an assembly level macro expander.
10870  The rules themselves are MCU dependent whereas the rule language infra-structur
10871 e is MCU independent.
10872  Peephole optimization rules for other MCU can be easily programmed using
10873  the rule language.
10874 \newline
10875
10876 \newline
10877 The syntax for a rule is as follows:
10878 \layout Verse
10879
10880
10881 \family typewriter
10882 rule := replace [ restart ] '{' <assembly sequence> '
10883 \backslash
10884 n'
10885 \newline
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  \SpecialChar ~
10899  \SpecialChar ~
10900  '}' by '{' '
10901 \backslash
10902 n'
10903 \newline
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  \SpecialChar ~
10919  \SpecialChar ~
10920  <assembly sequence> '
10921 \backslash
10922 n'
10923 \newline
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  \SpecialChar ~
10937  \SpecialChar ~
10938  '}' [if <functionName> ] '
10939 \backslash
10940 n'
10941 \layout Standard
10942
10943 <assembly sequence> := assembly instruction (each instruction including
10944  labels must be on a separate line).
10945 \newline
10946
10947 \newline
10948 The optimizer will apply to the rules one by one from the top in the sequence
10949  of their appearance, it will terminate when all rules are exhausted.
10950  If the 'restart' option is specified, then the optimizer will start matching
10951  the rules again from the top, this option for a rule is expensive (performance)
10952 , it is intended to be used in situations where a transformation will trigger
10953  the same rule again.
10954  An example of this (not a good one, it has side effects) is the following
10955  rule:
10956 \layout Verse
10957
10958
10959 \family typewriter
10960 replace restart {
10961 \newline
10962 \SpecialChar ~
10963 \SpecialChar ~
10964 pop %1
10965 \newline
10966 \SpecialChar ~
10967 \SpecialChar ~
10968 push %1 } by {
10969 \newline
10970 \SpecialChar ~
10971 \SpecialChar ~
10972 ; nop
10973 \newline
10974 }
10975 \layout Standard
10976
10977 Note that the replace pattern cannot be a blank, but can be a comment line.
10978  Without the 'restart' option only the inner most 'pop' 'push' pair would
10979  be eliminated, i.e.:
10980 \layout Verse
10981
10982
10983 \family typewriter
10984 pop ar1
10985 \newline
10986 pop ar2
10987 \newline
10988 push ar2
10989 \newline
10990 push ar1
10991 \layout Standard
10992
10993 would result in:
10994 \layout Verse
10995
10996
10997 \family typewriter
10998 pop ar1
10999 \newline
11000 ; nop
11001 \newline
11002 push ar1
11003 \layout Standard
11004
11005
11006 \emph on
11007 with
11008 \emph default
11009  the restart option the rule will be applied again to the resulting code
11010  and then all the pop-push pairs will be eliminated to yield:
11011 \layout Verse
11012
11013
11014 \family typewriter
11015 ; nop
11016 \newline
11017 ; nop
11018 \layout Standard
11019
11020 A conditional function can be attached to a rule.
11021  Attaching rules are somewhat more involved, let me illustrate this with
11022  an example.
11023 \layout Verse
11024
11025
11026 \family typewriter
11027 replace {
11028 \newline
11029 \SpecialChar ~
11030  \SpecialChar ~
11031  \SpecialChar ~
11032 ljmp %5
11033 \newline
11034 %2:
11035 \newline
11036 } by {
11037 \newline
11038 \SpecialChar ~
11039  \SpecialChar ~
11040  \SpecialChar ~
11041 sjmp %5
11042 \newline
11043 %2:
11044 \newline
11045 } if labelInRange
11046 \layout Standard
11047
11048 The optimizer does a look-up of a function name table defined in function
11049
11050 \emph on
11051 callFuncByName
11052 \emph default
11053  in the source file SDCCpeeph.c, with the name
11054 \emph on
11055 labelInRange
11056 \emph default
11057 .
11058  If it finds a corresponding entry the function is called.
11059  Note there can be no parameters specified for these functions, in this
11060  case the use of
11061 \emph on
11062 %5
11063 \emph default
11064  is crucial, since the function
11065 \emph on
11066 labelInRange
11067 \emph default
11068  expects to find the label in that particular variable (the hash table containin
11069 g the variable bindings is passed as a parameter).
11070  If you want to code more such functions, take a close look at the function
11071  labelInRange and the calling mechanism in source file SDCCpeeph.c.
11072  I know this whole thing is a little kludgey, but maybe some day we will
11073  have some better means.
11074  If you are looking at this file, you will also see the default rules that
11075  are compiled into the compiler, you can add your own rules in the default
11076  set there if you get tired of specifying the -
11077 \begin_inset ERT
11078 status Collapsed
11079
11080 \layout Standard
11081
11082 \backslash
11083 /
11084 \end_inset
11085
11086 -peep-file option.
11087 \layout Subsection
11088
11089 Pragmas
11090 \begin_inset LatexCommand \index{Pragmas}
11091
11092 \end_inset
11093
11094
11095 \layout Standard
11096
11097 SDCC supports the following #pragma directives.
11098 \layout Itemize
11099
11100 SAVE
11101 \begin_inset LatexCommand \index{\#pragma SAVE}
11102
11103 \end_inset
11104
11105  - this will save all current options to the SAVE/RESTORE stack.
11106  See RESTORE.
11107 \layout Itemize
11108
11109 RESTORE
11110 \begin_inset LatexCommand \index{\#pragma RESTORE}
11111
11112 \end_inset
11113
11114  - will restore saved options from the last save.
11115  SAVEs & RESTOREs can be nested.
11116  SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
11117  RESTORE pulls current options from the stack.
11118  See SAVE.
11119 \layout Itemize
11120
11121 NOGCSE
11122 \begin_inset LatexCommand \index{\#pragma NOGCSE}
11123
11124 \end_inset
11125
11126  - will stop global subexpression elimination.
11127 \layout Itemize
11128
11129 NOINDUCTION
11130 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
11131
11132 \end_inset
11133
11134  - will stop loop induction optimizations.
11135 \layout Itemize
11136
11137 NOJTBOUND
11138 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
11139
11140 \end_inset
11141
11142  - will not generate code for boundary value checking, when switch statements
11143  are turned into jump-tables.
11144 \layout Itemize
11145
11146 NOOVERLAY
11147 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
11148
11149 \end_inset
11150
11151  - the compiler will not overlay the parameters and local variables of a
11152  function.
11153 \layout Itemize
11154
11155 LESS_PEDANTIC
11156 \begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
11157
11158 \end_inset
11159
11160  - the compiler will not warn you anymore for obvious mistakes, you'r on
11161  your own now ;-(
11162 \layout Itemize
11163
11164 NOLOOPREVERSE
11165 \begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
11166
11167 \end_inset
11168
11169  - Will not do loop reversal optimization
11170 \layout Itemize
11171
11172 EXCLUDE
11173 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
11174
11175 \end_inset
11176
11177  NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
11178  pair of push/pop
11179 \begin_inset LatexCommand \index{push/pop}
11180
11181 \end_inset
11182
11183  instruction in ISR function (using interrupt
11184 \begin_inset LatexCommand \index{interrupt}
11185
11186 \end_inset
11187
11188  keyword).
11189  The directive should be placed immediately before the ISR function definition
11190  and it affects ALL ISR functions following it.
11191  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
11192 EXCLUDE\SpecialChar ~
11193 none
11194 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
11195
11196 \end_inset
11197
11198 .
11199 \layout Itemize
11200
11201 NOIV
11202 \begin_inset LatexCommand \index{\#pragma NOIV}
11203
11204 \end_inset
11205
11206  - Do not generate interrupt vector table entries for all ISR functions
11207  defined after the pragma.
11208  This is useful in cases where the interrupt vector table must be defined
11209  manually, or when there is a secondary, manually defined interrupt vector
11210  table (e.g.
11211  for the autovector feature of the Cypress EZ-USB FX2).
11212 \layout Itemize
11213
11214 CALLEE-SAVES
11215 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
11216
11217 \end_inset
11218
11219
11220 \begin_inset LatexCommand \index{function prologue}
11221
11222 \end_inset
11223
11224  function1[,function2[,function3...]] - The compiler by default uses a caller
11225  saves convention for register saving across function calls, however this
11226  can cause unnecessary register pushing & popping when calling small functions
11227  from larger functions.
11228  This option can be used to switch off the register saving convention for
11229  the function names specified.
11230  The compiler will not save registers when calling these functions, extra
11231  code need to be manually inserted at the entry & exit for these functions
11232  to save & restore the registers used by these functions, this can SUBSTANTIALLY
11233  reduce code & improve run time performance of the generated code.
11234  In the future the compiler (with inter procedural analysis) may be able
11235  to determine the appropriate scheme to use for each function call.
11236  If -
11237 \begin_inset ERT
11238 status Collapsed
11239
11240 \layout Standard
11241
11242 \backslash
11243 /
11244 \end_inset
11245
11246 -callee-saves command line option is used, the function names specified
11247  in #pragma\SpecialChar ~
11248 CALLEE-SAVES
11249 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
11250
11251 \end_inset
11252
11253  is appended to the list of functions specified in the command line.
11254 \layout Standard
11255
11256 The pragma's are intended to be used to turn-off certain optimizations which
11257  might cause the compiler to generate extra stack / data space to store
11258  compiler generated temporary variables.
11259  This usually happens in large functions.
11260  Pragma directives should be used as shown in the following example, they
11261  are used to control options & optimizations for a given function; pragmas
11262  should be placed before and/or after a function, placing pragma's inside
11263  a function body could have unpredictable results.
11264 \layout Verse
11265
11266
11267 \family typewriter
11268 #pragma SAVE
11269 \begin_inset LatexCommand \index{\#pragma SAVE}
11270
11271 \end_inset
11272
11273  /* save the current settings */
11274 \newline
11275 #pragma NOGCSE
11276 \begin_inset LatexCommand \index{\#pragma NOGCSE}
11277
11278 \end_inset
11279
11280  /* turnoff global subexpression elimination */
11281 \newline
11282 #pragma NOINDUCTION
11283 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
11284
11285 \end_inset
11286
11287  /* turn off induction optimizations */
11288 \newline
11289 int foo ()
11290 \newline
11291 {
11292 \newline
11293 \SpecialChar ~
11294  \SpecialChar ~
11295  ...
11296
11297 \newline
11298 \SpecialChar ~
11299  \SpecialChar ~
11300  /* large code */
11301 \newline
11302 \SpecialChar ~
11303  \SpecialChar ~
11304  ...
11305
11306 \newline
11307 }
11308 \newline
11309 #pragma RESTORE
11310 \begin_inset LatexCommand \index{\#pragma RESTORE}
11311
11312 \end_inset
11313
11314  /* turn the optimizations back on */
11315 \layout Standard
11316
11317 The compiler will generate a warning message when extra space is allocated.
11318  It is strongly recommended that the SAVE and RESTORE pragma's be used when
11319  changing options for a function.
11320 \layout Subsection
11321
11322 Library Routines
11323 \emph on
11324  <pending: this is messy and incomplete>
11325 \emph default
11326
11327 \layout Enumerate
11328
11329 Compiler support routines (_gptrget, _mulint etc)
11330 \layout Enumerate
11331
11332 Stdclib functions (puts, printf, strcat etc)
11333 \layout Enumerate
11334
11335 Math functions (sin, pow, sqrt etc)
11336 \layout Comment
11337
11338 license statements for the libraries are missing
11339 \layout Subsection
11340
11341 Interfacing with Assembly Routines
11342 \begin_inset LatexCommand \index{Assembler routines}
11343
11344 \end_inset
11345
11346
11347 \layout Subsubsection
11348
11349 Global Registers used for Parameter Passing
11350 \begin_inset LatexCommand \index{Parameter passing}
11351
11352 \end_inset
11353
11354
11355 \layout Standard
11356
11357 The compiler always uses the global registers
11358 \emph on
11359 DPL, DPH
11360 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
11361
11362 \end_inset
11363
11364 , B
11365 \begin_inset LatexCommand \index{B (register)}
11366
11367 \end_inset
11368
11369
11370 \emph default
11371 and
11372 \emph on
11373  ACC
11374 \begin_inset LatexCommand \index{ACC}
11375
11376 \end_inset
11377
11378
11379 \emph default
11380  to pass the first parameter to a routine.
11381  The second parameter onwards is either allocated on the stack (for reentrant
11382  routines or if -
11383 \begin_inset ERT
11384 status Collapsed
11385
11386 \layout Standard
11387
11388 \backslash
11389 /
11390 \end_inset
11391
11392 -stack-auto is used) or in the internal / external ram (depending on the
11393  memory model).
11394
11395 \layout Subsubsection
11396
11397 Assembler Routine(non-reentrant
11398 \begin_inset LatexCommand \index{reentrant}
11399
11400 \end_inset
11401
11402 )
11403 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
11404
11405 \end_inset
11406
11407
11408 \layout Standard
11409
11410 In the following example the function c_func calls an assembler routine
11411  asm_func, which takes two parameters.
11412 \layout Verse
11413
11414
11415 \family typewriter
11416 extern int asm_func(unsigned char, unsigned char);
11417 \newline
11418
11419 \newline
11420 int c_func (unsigned char i, unsigned char j)
11421 \newline
11422 {
11423 \newline
11424 \SpecialChar ~
11425 \SpecialChar ~
11426 \SpecialChar ~
11427 \SpecialChar ~
11428 return asm_func(i,j);
11429 \newline
11430 }
11431 \newline
11432
11433 \newline
11434 int main()
11435 \newline
11436 {
11437 \newline
11438 \SpecialChar ~
11439 \SpecialChar ~
11440 \SpecialChar ~
11441 \SpecialChar ~
11442 return c_func(10,9);
11443 \newline
11444 }
11445 \layout Standard
11446
11447 The corresponding assembler function is:
11448 \layout Verse
11449
11450
11451 \family typewriter
11452 .globl _asm_func_PARM_2
11453 \newline
11454 \SpecialChar ~
11455 \SpecialChar ~
11456 \SpecialChar ~
11457 \SpecialChar ~
11458 \SpecialChar ~
11459 \SpecialChar ~
11460 \SpecialChar ~
11461 \SpecialChar ~
11462 .globl _asm_func
11463 \newline
11464 \SpecialChar ~
11465 \SpecialChar ~
11466 \SpecialChar ~
11467 \SpecialChar ~
11468 \SpecialChar ~
11469 \SpecialChar ~
11470 \SpecialChar ~
11471 \SpecialChar ~
11472 .area OSEG
11473 \newline
11474 _asm_func_PARM_2:
11475 \newline
11476 \SpecialChar ~
11477 \SpecialChar ~
11478 \SpecialChar ~
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 \SpecialChar ~
11482 \SpecialChar ~
11483 \SpecialChar ~
11484 .ds      1
11485 \newline
11486 \SpecialChar ~
11487 \SpecialChar ~
11488 \SpecialChar ~
11489 \SpecialChar ~
11490 \SpecialChar ~
11491 \SpecialChar ~
11492 \SpecialChar ~
11493 \SpecialChar ~
11494 .area CSEG
11495 \newline
11496 _asm_func:
11497 \newline
11498 \SpecialChar ~
11499 \SpecialChar ~
11500 \SpecialChar ~
11501 \SpecialChar ~
11502 \SpecialChar ~
11503 \SpecialChar ~
11504 \SpecialChar ~
11505 \SpecialChar ~
11506 mov    a,dpl
11507 \newline
11508 \SpecialChar ~
11509 \SpecialChar ~
11510 \SpecialChar ~
11511 \SpecialChar ~
11512 \SpecialChar ~
11513 \SpecialChar ~
11514 \SpecialChar ~
11515 \SpecialChar ~
11516 add    a,_asm_func_PARM_2
11517 \newline
11518 \SpecialChar ~
11519 \SpecialChar ~
11520 \SpecialChar ~
11521 \SpecialChar ~
11522 \SpecialChar ~
11523 \SpecialChar ~
11524 \SpecialChar ~
11525 \SpecialChar ~
11526 mov    dpl,a
11527 \newline
11528 \SpecialChar ~
11529 \SpecialChar ~
11530 \SpecialChar ~
11531 \SpecialChar ~
11532 \SpecialChar ~
11533 \SpecialChar ~
11534 \SpecialChar ~
11535 \SpecialChar ~
11536 mov\SpecialChar ~
11537 \SpecialChar ~
11538 \SpecialChar ~
11539 \SpecialChar ~
11540 dpl
11541 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
11542
11543 \end_inset
11544
11545 ,#0x00
11546 \newline
11547 \SpecialChar ~
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 \SpecialChar ~
11553 \SpecialChar ~
11554 \SpecialChar ~
11555 ret
11556 \layout Standard
11557
11558 Note here that the return values are placed in 'dpl' - One byte return value,
11559  'dpl' LSB & 'dph' MSB for two byte values.
11560  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
11561 b' & 'acc' for four byte values.
11562 \layout Standard
11563
11564 The parameter naming convention is _<function_name>_PARM_<n>, where n is
11565  the parameter number starting from 1, and counting from the left.
11566  The first parameter is passed in
11567 \begin_inset Quotes eld
11568 \end_inset
11569
11570 dpl
11571 \begin_inset Quotes erd
11572 \end_inset
11573
11574  for One bye parameter,
11575 \begin_inset Quotes eld
11576 \end_inset
11577
11578 dptr
11579 \begin_inset Quotes erd
11580 \end_inset
11581
11582  if two bytes,
11583 \begin_inset Quotes eld
11584 \end_inset
11585
11586 b,dptr
11587 \begin_inset Quotes erd
11588 \end_inset
11589
11590  for three bytes and
11591 \begin_inset Quotes eld
11592 \end_inset
11593
11594 acc,b,dptr
11595 \begin_inset Quotes erd
11596 \end_inset
11597
11598  for four bytes, the variable name for the second parameter will be _<function_n
11599 ame>_PARM_2.
11600 \newline
11601
11602 \newline
11603 Assemble the assembler routine with the following command:
11604 \newline
11605
11606 \newline
11607
11608 \family sans
11609 \series bold
11610 asx8051 -losg asmfunc.asm
11611 \newline
11612
11613 \newline
11614
11615 \family default
11616 \series default
11617 Then compile and link the assembler routine to the C source file with the
11618  following command:
11619 \newline
11620
11621 \newline
11622
11623 \family sans
11624 \series bold
11625 sdcc cfunc.c asmfunc.rel
11626 \layout Subsubsection
11627
11628 Assembler Routine(reentrant
11629 \begin_inset LatexCommand \index{reentrant}
11630
11631 \end_inset
11632
11633 )
11634 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
11635
11636 \end_inset
11637
11638
11639 \layout Standard
11640
11641 In this case the second parameter onwards will be passed on the stack, the
11642  parameters are pushed from right to left i.e.
11643  after the call the left most parameter will be on the top of the stack.
11644  Here is an example:
11645 \layout Verse
11646
11647
11648 \family typewriter
11649 extern int asm_func(unsigned char, unsigned char);
11650 \newline
11651
11652 \newline
11653 int c_func (unsigned char i, unsigned char j) reentrant
11654 \newline
11655 {
11656 \newline
11657 \SpecialChar ~
11658 \SpecialChar ~
11659 \SpecialChar ~
11660 \SpecialChar ~
11661 return asm_func(i,j);
11662 \newline
11663 }
11664 \newline
11665
11666 \newline
11667 int main()
11668 \newline
11669 {
11670 \newline
11671 \SpecialChar ~
11672 \SpecialChar ~
11673 \SpecialChar ~
11674 \SpecialChar ~
11675 return c_func(10,9);
11676 \newline
11677 }
11678 \layout Standard
11679
11680 The corresponding assembler routine is:
11681 \layout Verse
11682
11683
11684 \family typewriter
11685 .globl _asm_func
11686 \newline
11687 _asm_func:
11688 \newline
11689 \SpecialChar ~
11690 \SpecialChar ~
11691 \SpecialChar ~
11692 \SpecialChar ~
11693 push  _bp
11694 \newline
11695 \SpecialChar ~
11696 \SpecialChar ~
11697 \SpecialChar ~
11698 \SpecialChar ~
11699 mov _bp,sp
11700 \newline
11701 \SpecialChar ~
11702 \SpecialChar ~
11703 \SpecialChar ~
11704 \SpecialChar ~
11705 mov  r2,dpl
11706 \newline
11707 \SpecialChar ~
11708 \SpecialChar ~
11709 \SpecialChar ~
11710 \SpecialChar ~
11711 mov  a,_bp
11712 \newline
11713 \SpecialChar ~
11714 \SpecialChar ~
11715 \SpecialChar ~
11716 \SpecialChar ~
11717 clr  c
11718 \newline
11719 \SpecialChar ~
11720 \SpecialChar ~
11721 \SpecialChar ~
11722 \SpecialChar ~
11723 add  a,#0xfd
11724 \newline
11725 \SpecialChar ~
11726 \SpecialChar ~
11727 \SpecialChar ~
11728 \SpecialChar ~
11729 mov  r0,a
11730 \newline
11731 \SpecialChar ~
11732 \SpecialChar ~
11733 \SpecialChar ~
11734 \SpecialChar ~
11735 add  a,#0xfc
11736 \newline
11737 \SpecialChar ~
11738 \SpecialChar ~
11739 \SpecialChar ~
11740 \SpecialChar ~
11741 mov  r1,a
11742 \newline
11743 \SpecialChar ~
11744 \SpecialChar ~
11745 \SpecialChar ~
11746 \SpecialChar ~
11747 mov  a,@r0
11748 \newline
11749 \SpecialChar ~
11750 \SpecialChar ~
11751 \SpecialChar ~
11752 \SpecialChar ~
11753 add  a,r2
11754 \newline
11755 \SpecialChar ~
11756 \SpecialChar ~
11757 \SpecialChar ~
11758 \SpecialChar ~
11759 mov  dpl,a
11760 \newline
11761 \SpecialChar ~
11762 \SpecialChar ~
11763 \SpecialChar ~
11764 \SpecialChar ~
11765 mov  dph,#0x00
11766 \newline
11767 \SpecialChar ~
11768 \SpecialChar ~
11769 \SpecialChar ~
11770 \SpecialChar ~
11771 mov  sp,_bp
11772 \newline
11773 \SpecialChar ~
11774 \SpecialChar ~
11775 \SpecialChar ~
11776 \SpecialChar ~
11777 pop  _bp
11778 \newline
11779 \SpecialChar ~
11780 \SpecialChar ~
11781 \SpecialChar ~
11782 \SpecialChar ~
11783 ret
11784 \layout Standard
11785
11786 The compiling and linking procedure remains the same, however note the extra
11787  entry & exit linkage required for the assembler code, _bp is the stack
11788  frame pointer and is used to compute the offset into the stack for parameters
11789  and local variables.
11790 \layout Subsection
11791
11792 External Stack
11793 \begin_inset LatexCommand \index{stack}
11794
11795 \end_inset
11796
11797
11798 \begin_inset LatexCommand \index{External stack}
11799
11800 \end_inset
11801
11802
11803 \layout Standard
11804
11805 The external stack is located at the start of the external ram segment,
11806  and is 256 bytes in size.
11807  When -
11808 \begin_inset ERT
11809 status Collapsed
11810
11811 \layout Standard
11812
11813 \backslash
11814 /
11815 \end_inset
11816
11817 -xstack option is used to compile the program, the parameters and local
11818  variables of all reentrant functions are allocated in this area.
11819  This option is provided for programs with large stack space requirements.
11820  When used with the -
11821 \begin_inset ERT
11822 status Collapsed
11823
11824 \layout Standard
11825
11826 \backslash
11827 /
11828 \end_inset
11829
11830 -stack-auto option, all parameters and local variables are allocated on
11831  the external stack (note support libraries will need to be recompiled with
11832  the same options).
11833 \layout Standard
11834
11835 The compiler outputs the higher order address byte of the external ram segment
11836  into PORT P2, therefore when using the External Stack option, this port
11837  MAY NOT be used by the application program.
11838 \layout Subsection
11839
11840 ANSI-Compliance
11841 \begin_inset LatexCommand \index{ANSI-compliance}
11842
11843 \end_inset
11844
11845
11846 \layout Standard
11847
11848 Deviations from the compliance:
11849 \layout Itemize
11850
11851 functions are not always reentrant.
11852 \layout Itemize
11853
11854 structures cannot be assigned values directly, cannot be passed as function
11855  parameters or assigned to each other and cannot be a return value from
11856  a function, e.g.:
11857 \begin_deeper
11858 \layout Verse
11859
11860
11861 \family typewriter
11862 struct s { ...
11863  };
11864 \newline
11865 struct s s1, s2;
11866 \newline
11867 foo()
11868 \newline
11869 {
11870 \newline
11871 \SpecialChar ~
11872 \SpecialChar ~
11873 \SpecialChar ~
11874 \SpecialChar ~
11875 ...
11876
11877 \newline
11878 \SpecialChar ~
11879 \SpecialChar ~
11880 \SpecialChar ~
11881 \SpecialChar ~
11882 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
11883 \newline
11884 \SpecialChar ~
11885 \SpecialChar ~
11886 \SpecialChar ~
11887 \SpecialChar ~
11888 ...
11889
11890 \newline
11891 }
11892 \newline
11893 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
11894  */
11895 \newline
11896 {
11897 \newline
11898 \SpecialChar ~
11899 \SpecialChar ~
11900 \SpecialChar ~
11901 \SpecialChar ~
11902 struct s rets;
11903 \newline
11904 \SpecialChar ~
11905 \SpecialChar ~
11906 \SpecialChar ~
11907 \SpecialChar ~
11908 ...
11909
11910 \newline
11911 \SpecialChar ~
11912 \SpecialChar ~
11913 \SpecialChar ~
11914 \SpecialChar ~
11915 return rets;/* is invalid in SDCC although allowed in ANSI */
11916 \newline
11917 }
11918 \end_deeper
11919 \layout Itemize
11920
11921 'long long
11922 \begin_inset LatexCommand \index{long long (not supported)}
11923
11924 \end_inset
11925
11926 ' (64 bit integers
11927 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
11928
11929 \end_inset
11930
11931 ) not supported.
11932 \layout Itemize
11933
11934 'double
11935 \begin_inset LatexCommand \index{double (not supported)}
11936
11937 \end_inset
11938
11939 ' precision floating point
11940 \begin_inset LatexCommand \index{Floating point support}
11941
11942 \end_inset
11943
11944 not supported.
11945 \layout Itemize
11946
11947 No support for setjmp and longjmp (for now).
11948 \layout Itemize
11949
11950 Old K&R style
11951 \begin_inset LatexCommand \index{K\&R style}
11952
11953 \end_inset
11954
11955  function declarations are NOT allowed.
11956 \begin_deeper
11957 \layout Verse
11958
11959
11960 \family typewriter
11961 foo(i,j) /* this old style of function declarations */
11962 \newline
11963 int i,j; /* are valid in ANSI but not valid in SDCC */
11964 \newline
11965 {
11966 \newline
11967 \SpecialChar ~
11968 \SpecialChar ~
11969 \SpecialChar ~
11970 \SpecialChar ~
11971 ...
11972
11973 \newline
11974 }
11975 \end_deeper
11976 \layout Itemize
11977
11978 functions declared as pointers must be dereferenced during the call.
11979 \begin_deeper
11980 \layout Verse
11981
11982
11983 \family typewriter
11984 int (*foo)();
11985 \newline
11986 ...
11987
11988 \newline
11989 /* has to be called like this */
11990 \newline
11991 (*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
11992 \end_deeper
11993 \layout Subsection
11994
11995 Cyclomatic Complexity
11996 \begin_inset LatexCommand \index{Cyclomatic complexity}
11997
11998 \end_inset
11999
12000
12001 \layout Standard
12002
12003 Cyclomatic complexity of a function is defined as the number of independent
12004  paths the program can take during execution of the function.
12005  This is an important number since it defines the number test cases you
12006  have to generate to validate the function.
12007  The accepted industry standard for complexity number is 10, if the cyclomatic
12008  complexity reported by SDCC exceeds 10 you should think about simplification
12009  of the function logic.
12010  Note that the complexity level is not related to the number of lines of
12011  code in a function.
12012  Large functions can have low complexity, and small functions can have large
12013  complexity levels.
12014
12015 \newline
12016
12017 \newline
12018 SDCC uses the following formula to compute the complexity:
12019 \newline
12020
12021 \layout Standard
12022
12023 complexity = (number of edges in control flow graph) - (number of nodes
12024  in control flow graph) + 2;
12025 \newline
12026
12027 \newline
12028 Having said that the industry standard is 10, you should be aware that in
12029  some cases it be may unavoidable to have a complexity level of less than
12030  10.
12031  For example if you have switch statement with more than 10 case labels,
12032  each case label adds one to the complexity level.
12033  The complexity level is by no means an absolute measure of the algorithmic
12034  complexity of the function, it does however provide a good starting point
12035  for which functions you might look at for further optimization.
12036 \layout Section
12037 \pagebreak_top
12038 TIPS
12039 \layout Standard
12040
12041 Here are a few guidelines that will help the compiler generate more efficient
12042  code, some of the tips are specific to this compiler others are generally
12043  good programming practice.
12044 \layout Itemize
12045
12046 Use the smallest data type to represent your data-value.
12047  If it is known in advance that the value is going to be less than 256 then
12048  use an 'unsigned char' instead of a 'short' or 'int'.
12049 \layout Itemize
12050
12051 Use unsigned when it is known in advance that the value is not going to
12052  be negative.
12053  This helps especially if you are doing division or multiplication.
12054 \layout Itemize
12055
12056 NEVER jump into a LOOP.
12057 \layout Itemize
12058
12059 Declare the variables to be local whenever possible, especially loop control
12060  variables (induction).
12061 \layout Itemize
12062
12063 Since the compiler does not always do implicit integral promotion, the programme
12064 r should do an explicit cast when integral promotion is required.
12065 \layout Itemize
12066
12067 Reducing the size of division, multiplication & modulus operations can reduce
12068  code size substantially.
12069  Take the following code for example.
12070 \begin_deeper
12071 \layout Verse
12072
12073
12074 \family typewriter
12075 foobar(unsigned int p1, unsigned char ch)
12076 \newline
12077 {
12078 \newline
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 \SpecialChar ~
12083 unsigned char ch1 = p1 % ch ;
12084 \newline
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 \SpecialChar ~
12088 \SpecialChar ~
12089 ....
12090 \newline
12091 }
12092 \layout Standard
12093
12094 For the modulus operation the variable ch will be promoted to unsigned int
12095  first then the modulus operation will be performed (this will lead to a
12096  call to support routine _moduint()), and the result will be casted to a
12097  char.
12098  If the code is changed to
12099 \layout Verse
12100
12101
12102 \family typewriter
12103 foobar(unsigned int p1, unsigned char ch)
12104 \newline
12105 {
12106 \newline
12107 \SpecialChar ~
12108 \SpecialChar ~
12109 \SpecialChar ~
12110 \SpecialChar ~
12111 unsigned char ch1 = (unsigned char)p1 % ch ;
12112 \newline
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 \SpecialChar ~
12116 \SpecialChar ~
12117 ....
12118 \newline
12119 }
12120 \layout Standard
12121
12122 It would substantially reduce the code generated (future versions of the
12123  compiler will be smart enough to detect such optimization opportunities).
12124 \end_deeper
12125 \layout Subsection
12126
12127 Notes on MCS51 memory
12128 \begin_inset LatexCommand \index{MCS51 memory}
12129
12130 \end_inset
12131
12132  layout
12133 \layout Standard
12134
12135 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
12136  RAM memory which is structured as follows
12137 \newline
12138
12139 \newline
12140 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
12141
12142 \newline
12143 - Bytes 20-2F - 16 bytes to hold 128 bit variables and,
12144 \newline
12145 - Bytes 30-7F - 80 bytes for general purpose use.
12146 \newline
12147
12148 \layout Standard
12149
12150 Additionally some members of the MCS51 family may have up to 128 bytes of
12151  additional, indirectly addressable, internal RAM memory (
12152 \emph on
12153 idata
12154 \emph default
12155 ).
12156  Furthermore, some chips may have some built in external memory (
12157 \emph on
12158 xdata
12159 \emph default
12160 ) which should not be confused with the internal, directly addressable RAM
12161  memory (
12162 \emph on
12163 data
12164 \emph default
12165 ).
12166  Usually this built in
12167 \emph on
12168 xdata
12169 \emph default
12170  memory has to be activated before using it (you can probably find this
12171  information on the datasheet of the microcontroller your are using).
12172 \layout Standard
12173
12174 Normally SDCC will only use the first bank
12175 \begin_inset LatexCommand \index{bank}
12176
12177 \end_inset
12178
12179  of registers (register bank 0), but it is possible to specify that other
12180  banks of registers should be used in interrupt
12181 \begin_inset LatexCommand \index{interrupt}
12182
12183 \end_inset
12184
12185  routines.
12186  By default, the compiler will place the stack after the last byte of allocated
12187  memory for variables.
12188  For example, if the first 2 banks of registers are used, and only four
12189  bytes are used for
12190 \emph on
12191 data
12192 \emph default
12193  variables, it will position the base of the internal stack at address 20
12194  (0x14).
12195  This implies that as the stack
12196 \begin_inset LatexCommand \index{stack}
12197
12198 \end_inset
12199
12200  grows, it will use up the remaining register banks, and the 16 bytes used
12201  by the 128 bit variables, and 80 bytes for general purpose use.
12202  If any bit variables are used, the data variables will be placed after
12203  the byte holding the last bit variable.
12204  For example, if register banks 0 and 1 are used, and there are 9 bit variables
12205  (two bytes used),
12206 \emph on
12207 data
12208 \emph default
12209  variables will be placed starting at address 0x22.
12210  You can also use -
12211 \begin_inset ERT
12212 status Collapsed
12213
12214 \layout Standard
12215
12216 \backslash
12217 /
12218 \end_inset
12219
12220 -data-loc
12221 \begin_inset LatexCommand \index{-\/-data-loc}
12222
12223 \end_inset
12224
12225  to specify the start address of the
12226 \emph on
12227 data
12228 \emph default
12229  and -
12230 \begin_inset ERT
12231 status Collapsed
12232
12233 \layout Standard
12234
12235 \backslash
12236 /
12237 \end_inset
12238
12239 -iram-size to specify the size of the total internal RAM (
12240 \emph on
12241 data
12242 \emph default
12243 +
12244 \emph on
12245 idata
12246 \emph default
12247 ).
12248
12249 \layout Standard
12250
12251 By default the 8051 linker will place the stack after the last byte of data
12252  variables.
12253  Option -
12254 \begin_inset ERT
12255 status Collapsed
12256
12257 \layout Standard
12258
12259 \backslash
12260 /
12261 \end_inset
12262
12263 -stack-loc
12264 \begin_inset LatexCommand \index{-\/-stack-loc}
12265
12266 \end_inset
12267
12268  allows you to specify the start of the stack, i.e.
12269  you could start it after any data in the general purpose area.
12270  If your microcontroller has additional indirectly addressable internal
12271  RAM (
12272 \emph on
12273 idata
12274 \emph default
12275 ) you can place the stack on it.
12276  You may also need to use -
12277 \begin_inset ERT
12278 status Collapsed
12279
12280 \layout Standard
12281
12282 \backslash
12283 /
12284 \end_inset
12285
12286 -xdata-loc
12287 \begin_inset LatexCommand \index{-\/-data-loc}
12288
12289 \end_inset
12290
12291  to set the start address of the external RAM (
12292 \emph on
12293 xdata
12294 \emph default
12295 ) and -
12296 \begin_inset ERT
12297 status Collapsed
12298
12299 \layout Standard
12300
12301 \backslash
12302 /
12303 \end_inset
12304
12305 -xram-size
12306 \begin_inset LatexCommand \index{-\/-data-loc}
12307
12308 \end_inset
12309
12310  to specify its size.
12311  Same goes for the code memory, using -
12312 \begin_inset ERT
12313 status Collapsed
12314
12315 \layout Standard
12316
12317 \backslash
12318 /
12319 \end_inset
12320
12321 -code-loc
12322 \begin_inset LatexCommand \index{-\/-data-loc}
12323
12324 \end_inset
12325
12326  and -
12327 \begin_inset ERT
12328 status Collapsed
12329
12330 \layout Standard
12331
12332 \backslash
12333 /
12334 \end_inset
12335
12336 -code-size
12337 \begin_inset LatexCommand \index{-\/-data-loc}
12338
12339 \end_inset
12340
12341 .
12342  If in doubt, don't specify any options and see if the resulting memory
12343  layout is appropriate, then you can adjust it.
12344 \layout Standard
12345
12346 The 8051 linker generates two files with memory allocation information.
12347  The first, with extension .map shows all the variables and segments.
12348  The second with extension .mem shows the final memory layout.
12349  The linker will complaint either if memory segments overlap, there is not
12350  enough memory, or there is not enough space for stack.
12351  If you get any linking warnings and/or errors related to stack or segments
12352  allocation, take a look at either the .map or .mem files to find out what
12353  the problem is.
12354  The .mem file may even suggest a solution to the problem.
12355 \layout Subsection
12356
12357 Tools
12358 \begin_inset LatexCommand \index{Tools}
12359
12360 \end_inset
12361
12362  included in the distribution
12363 \layout Standard
12364
12365
12366 \begin_inset  Tabular
12367 <lyxtabular version="3" rows="12" columns="3">
12368 <features>
12369 <column alignment="center" valignment="top" leftline="true" width="0pt">
12370 <column alignment="center" valignment="top" leftline="true" width="0pt">
12371 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
12372 <row topline="true" bottomline="true">
12373 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12374 \begin_inset Text
12375
12376 \layout Standard
12377
12378 Name
12379 \end_inset
12380 </cell>
12381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12382 \begin_inset Text
12383
12384 \layout Standard
12385
12386 Purpose
12387 \end_inset
12388 </cell>
12389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12390 \begin_inset Text
12391
12392 \layout Standard
12393
12394 Directory
12395 \end_inset
12396 </cell>
12397 </row>
12398 <row topline="true">
12399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12400 \begin_inset Text
12401
12402 \layout Standard
12403
12404 uCsim
12405 \end_inset
12406 </cell>
12407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12408 \begin_inset Text
12409
12410 \layout Standard
12411
12412 Simulator for various architectures
12413 \end_inset
12414 </cell>
12415 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12416 \begin_inset Text
12417
12418 \layout Standard
12419
12420 sdcc/sim/ucsim
12421 \end_inset
12422 </cell>
12423 </row>
12424 <row topline="true">
12425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12426 \begin_inset Text
12427
12428 \layout Standard
12429
12430 keil2sdcc.pl
12431 \end_inset
12432 </cell>
12433 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12434 \begin_inset Text
12435
12436 \layout Standard
12437
12438 header file conversion
12439 \end_inset
12440 </cell>
12441 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12442 \begin_inset Text
12443
12444 \layout Standard
12445
12446 sdcc/support/scripts
12447 \end_inset
12448 </cell>
12449 </row>
12450 <row topline="true">
12451 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12452 \begin_inset Text
12453
12454 \layout Standard
12455
12456 mh2h.c
12457 \end_inset
12458 </cell>
12459 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12460 \begin_inset Text
12461
12462 \layout Standard
12463
12464 header file conversion
12465 \end_inset
12466 </cell>
12467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12468 \begin_inset Text
12469
12470 \layout Standard
12471
12472 sdcc/support/scripts
12473 \end_inset
12474 </cell>
12475 </row>
12476 <row topline="true">
12477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12478 \begin_inset Text
12479
12480 \layout Standard
12481
12482 as-gbz80
12483 \end_inset
12484 </cell>
12485 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12486 \begin_inset Text
12487
12488 \layout Standard
12489
12490 Assembler
12491 \end_inset
12492 </cell>
12493 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12494 \begin_inset Text
12495
12496 \layout Standard
12497
12498
12499 \family roman
12500 \series medium
12501 \shape up
12502 \size normal
12503 \emph off
12504 \bar no
12505 \noun off
12506 \color none
12507 sdcc/bin
12508 \end_inset
12509 </cell>
12510 </row>
12511 <row topline="true">
12512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12513 \begin_inset Text
12514
12515 \layout Standard
12516
12517 as-z80
12518 \end_inset
12519 </cell>
12520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12521 \begin_inset Text
12522
12523 \layout Standard
12524
12525 Assembler
12526 \end_inset
12527 </cell>
12528 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12529 \begin_inset Text
12530
12531 \layout Standard
12532
12533
12534 \family roman
12535 \series medium
12536 \shape up
12537 \size normal
12538 \emph off
12539 \bar no
12540 \noun off
12541 \color none
12542 sdcc/bin
12543 \end_inset
12544 </cell>
12545 </row>
12546 <row topline="true">
12547 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12548 \begin_inset Text
12549
12550 \layout Standard
12551
12552 asx8051
12553 \end_inset
12554 </cell>
12555 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12556 \begin_inset Text
12557
12558 \layout Standard
12559
12560 Assembler
12561 \end_inset
12562 </cell>
12563 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12564 \begin_inset Text
12565
12566 \layout Standard
12567
12568
12569 \family roman
12570 \series medium
12571 \shape up
12572 \size normal
12573 \emph off
12574 \bar no
12575 \noun off
12576 \color none
12577 sdcc/bin
12578 \end_inset
12579 </cell>
12580 </row>
12581 <row topline="true">
12582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12583 \begin_inset Text
12584
12585 \layout Standard
12586
12587 sdcdb
12588 \end_inset
12589 </cell>
12590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12591 \begin_inset Text
12592
12593 \layout Standard
12594
12595 Simulator
12596 \end_inset
12597 </cell>
12598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12599 \begin_inset Text
12600
12601 \layout Standard
12602
12603
12604 \family roman
12605 \series medium
12606 \shape up
12607 \size normal
12608 \emph off
12609 \bar no
12610 \noun off
12611 \color none
12612 sdcc/bin
12613 \end_inset
12614 </cell>
12615 </row>
12616 <row topline="true">
12617 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12618 \begin_inset Text
12619
12620 \layout Standard
12621
12622 aslink
12623 \end_inset
12624 </cell>
12625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12626 \begin_inset Text
12627
12628 \layout Standard
12629
12630 Linker
12631 \end_inset
12632 </cell>
12633 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12634 \begin_inset Text
12635
12636 \layout Standard
12637
12638
12639 \family roman
12640 \series medium
12641 \shape up
12642 \size normal
12643 \emph off
12644 \bar no
12645 \noun off
12646 \color none
12647 sdcc/bin
12648 \end_inset
12649 </cell>
12650 </row>
12651 <row topline="true">
12652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12653 \begin_inset Text
12654
12655 \layout Standard
12656
12657 link-z80
12658 \end_inset
12659 </cell>
12660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12661 \begin_inset Text
12662
12663 \layout Standard
12664
12665 Linker
12666 \end_inset
12667 </cell>
12668 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12669 \begin_inset Text
12670
12671 \layout Standard
12672
12673
12674 \family roman
12675 \series medium
12676 \shape up
12677 \size normal
12678 \emph off
12679 \bar no
12680 \noun off
12681 \color none
12682 sdcc/bin
12683 \end_inset
12684 </cell>
12685 </row>
12686 <row topline="true">
12687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12688 \begin_inset Text
12689
12690 \layout Standard
12691
12692 link-gbz80
12693 \end_inset
12694 </cell>
12695 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12696 \begin_inset Text
12697
12698 \layout Standard
12699
12700 Linker
12701 \end_inset
12702 </cell>
12703 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12704 \begin_inset Text
12705
12706 \layout Standard
12707
12708
12709 \family roman
12710 \series medium
12711 \shape up
12712 \size normal
12713 \emph off
12714 \bar no
12715 \noun off
12716 \color none
12717 sdcc/bin
12718 \end_inset
12719 </cell>
12720 </row>
12721 <row topline="true" bottomline="true">
12722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12723 \begin_inset Text
12724
12725 \layout Standard
12726
12727 packihx
12728 \end_inset
12729 </cell>
12730 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12731 \begin_inset Text
12732
12733 \layout Standard
12734
12735 ihx packer
12736 \end_inset
12737 </cell>
12738 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12739 \begin_inset Text
12740
12741 \layout Standard
12742
12743
12744 \family roman
12745 \series medium
12746 \shape up
12747 \size normal
12748 \emph off
12749 \bar no
12750 \noun off
12751 \color none
12752 sdcc/bin
12753 \end_inset
12754 </cell>
12755 </row>
12756 </lyxtabular>
12757
12758 \end_inset
12759
12760
12761 \layout Subsection
12762
12763 Related open source tools
12764 \begin_inset LatexCommand \index{Related tools}
12765
12766 \end_inset
12767
12768
12769 \layout Standard
12770
12771
12772 \begin_inset  Tabular
12773 <lyxtabular version="3" rows="7" columns="3">
12774 <features>
12775 <column alignment="center" valignment="top" leftline="true" width="0pt">
12776 <column alignment="center" valignment="top" leftline="true" width="0pt">
12777 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
12778 <row topline="true" bottomline="true">
12779 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12780 \begin_inset Text
12781
12782 \layout Standard
12783
12784 Name
12785 \end_inset
12786 </cell>
12787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12788 \begin_inset Text
12789
12790 \layout Standard
12791
12792 Purpose
12793 \end_inset
12794 </cell>
12795 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12796 \begin_inset Text
12797
12798 \layout Standard
12799
12800 Where to get
12801 \end_inset
12802 </cell>
12803 </row>
12804 <row topline="true">
12805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12806 \begin_inset Text
12807
12808 \layout Standard
12809
12810 gpsim
12811 \begin_inset LatexCommand \index{gpsim}
12812
12813 \end_inset
12814
12815
12816 \end_inset
12817 </cell>
12818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12819 \begin_inset Text
12820
12821 \layout Standard
12822
12823 PIC simulator
12824 \end_inset
12825 </cell>
12826 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12827 \begin_inset Text
12828
12829 \layout Standard
12830
12831
12832 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
12833
12834 \end_inset
12835
12836
12837 \end_inset
12838 </cell>
12839 </row>
12840 <row topline="true">
12841 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12842 \begin_inset Text
12843
12844 \layout Standard
12845
12846 srecord
12847 \begin_inset LatexCommand \index{srecord}
12848
12849 \end_inset
12850
12851
12852 \end_inset
12853 </cell>
12854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12855 \begin_inset Text
12856
12857 \layout Standard
12858
12859 Object file conversion, checksumming, ...
12860 \end_inset
12861 </cell>
12862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12863 \begin_inset Text
12864
12865 \layout Standard
12866
12867
12868 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
12869
12870 \end_inset
12871
12872
12873 \end_inset
12874 </cell>
12875 </row>
12876 <row topline="true">
12877 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12878 \begin_inset Text
12879
12880 \layout Standard
12881
12882 objdump
12883 \begin_inset LatexCommand \index{objdump}
12884
12885 \end_inset
12886
12887
12888 \end_inset
12889 </cell>
12890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12891 \begin_inset Text
12892
12893 \layout Standard
12894
12895 Object file conversion, ...
12896 \end_inset
12897 </cell>
12898 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12899 \begin_inset Text
12900
12901 \layout Standard
12902
12903 Part of binutils (should be there anyway)
12904 \end_inset
12905 </cell>
12906 </row>
12907 <row topline="true">
12908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12909 \begin_inset Text
12910
12911 \layout Standard
12912
12913 doxygen
12914 \begin_inset LatexCommand \index{doxygen}
12915
12916 \end_inset
12917
12918
12919 \end_inset
12920 </cell>
12921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12922 \begin_inset Text
12923
12924 \layout Standard
12925
12926 Source code documentation system
12927 \end_inset
12928 </cell>
12929 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12930 \begin_inset Text
12931
12932 \layout Standard
12933
12934
12935 \begin_inset LatexCommand \url{http://www.doxygen.org}
12936
12937 \end_inset
12938
12939
12940 \end_inset
12941 </cell>
12942 </row>
12943 <row topline="true">
12944 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12945 \begin_inset Text
12946
12947 \layout Standard
12948
12949 splint
12950 \begin_inset LatexCommand \index{splint}
12951
12952 \end_inset
12953
12954
12955 \end_inset
12956 </cell>
12957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12958 \begin_inset Text
12959
12960 \layout Standard
12961
12962 Statically checks c sources
12963 \end_inset
12964 </cell>
12965 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12966 \begin_inset Text
12967
12968 \layout Standard
12969
12970
12971 \begin_inset LatexCommand \url{http://www.splint.org}
12972
12973 \end_inset
12974
12975
12976 \end_inset
12977 </cell>
12978 </row>
12979 <row topline="true" bottomline="true">
12980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12981 \begin_inset Text
12982
12983 \layout Standard
12984
12985 ddd
12986 \begin_inset LatexCommand \index{ddd}
12987
12988 \end_inset
12989
12990
12991 \end_inset
12992 </cell>
12993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12994 \begin_inset Text
12995
12996 \layout Standard
12997
12998 Debugger, serves nicely as GUI to sdcdb
12999 \begin_inset LatexCommand \index{sdcdb}
13000
13001 \end_inset
13002
13003
13004 \end_inset
13005 </cell>
13006 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13007 \begin_inset Text
13008
13009 \layout Standard
13010
13011
13012 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
13013
13014 \end_inset
13015
13016
13017 \end_inset
13018 </cell>
13019 </row>
13020 </lyxtabular>
13021
13022 \end_inset
13023
13024
13025 \layout Subsection
13026
13027 Related documentation / recommended reading
13028 \layout Standard
13029
13030
13031 \begin_inset  Tabular
13032 <lyxtabular version="3" rows="5" columns="3">
13033 <features>
13034 <column alignment="center" valignment="top" leftline="true" width="0pt">
13035 <column alignment="center" valignment="top" leftline="true" width="0pt">
13036 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
13037 <row topline="true" bottomline="true">
13038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13039 \begin_inset Text
13040
13041 \layout Standard
13042
13043 Name
13044 \end_inset
13045 </cell>
13046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13047 \begin_inset Text
13048
13049 \layout Standard
13050
13051 Subject / Title
13052 \end_inset
13053 </cell>
13054 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13055 \begin_inset Text
13056
13057 \layout Standard
13058
13059 Where to get
13060 \end_inset
13061 </cell>
13062 </row>
13063 <row topline="true">
13064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13065 \begin_inset Text
13066
13067 \layout Standard
13068
13069 S.
13070  S.
13071  Muchnick
13072 \end_inset
13073 </cell>
13074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13075 \begin_inset Text
13076
13077 \layout Standard
13078
13079 Advanced Compiler Design and Implementation
13080 \end_inset
13081 </cell>
13082 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13083 \begin_inset Text
13084
13085 \layout Standard
13086
13087 bookstore
13088 \end_inset
13089 </cell>
13090 </row>
13091 <row topline="true">
13092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13093 \begin_inset Text
13094
13095 \layout Standard
13096
13097
13098 \family roman
13099 \series medium
13100 \shape up
13101 \size normal
13102 \emph off
13103 \bar no
13104 \noun off
13105 \color none
13106 c-refcard.pdf
13107 \end_inset
13108 </cell>
13109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13110 \begin_inset Text
13111
13112 \layout Standard
13113
13114 C Reference Card
13115 \begin_inset LatexCommand \index{C Reference card}
13116
13117 \end_inset
13118
13119 , 2 pages
13120 \end_inset
13121 </cell>
13122 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13123 \begin_inset Text
13124
13125 \layout Standard
13126
13127
13128 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
13129
13130 \end_inset
13131
13132
13133 \end_inset
13134 </cell>
13135 </row>
13136 <row topline="true">
13137 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13138 \begin_inset Text
13139
13140 \layout Standard
13141
13142 test_suite_spec.pdf
13143 \end_inset
13144 </cell>
13145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13146 \begin_inset Text
13147
13148 \layout Standard
13149
13150 sdcc regression test
13151 \begin_inset LatexCommand \index{Regression test}
13152
13153 \end_inset
13154
13155
13156 \end_inset
13157 </cell>
13158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13159 \begin_inset Text
13160
13161 \layout Standard
13162
13163 sdcc/doc
13164 \end_inset
13165 </cell>
13166 </row>
13167 <row topline="true" bottomline="true">
13168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13169 \begin_inset Text
13170
13171 \layout Standard
13172
13173
13174 \family roman
13175 \series medium
13176 \shape up
13177 \size normal
13178 \emph off
13179 \bar no
13180 \noun off
13181 \color none
13182 cdbfileformat.pd
13183 \family default
13184 \series default
13185 \shape default
13186 \size default
13187 \emph default
13188 \bar default
13189 \noun default
13190 \color default
13191 f
13192 \end_inset
13193 </cell>
13194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13195 \begin_inset Text
13196
13197 \layout Standard
13198
13199 sdcc internal documentation
13200 \end_inset
13201 </cell>
13202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13203 \begin_inset Text
13204
13205 \layout Standard
13206
13207 sdcc/doc
13208 \end_inset
13209 </cell>
13210 </row>
13211 </lyxtabular>
13212
13213 \end_inset
13214
13215
13216 \layout Section
13217 \pagebreak_top
13218 Retargetting for other MCUs.
13219 \layout Standard
13220
13221 The issues for retargetting the compiler are far too numerous to be covered
13222  by this document.
13223  What follows is a brief description of each of the seven phases of the
13224  compiler and its MCU dependency.
13225 \layout Itemize
13226
13227 Parsing the source and building the annotated parse tree.
13228  This phase is largely MCU independent (except for the language extensions).
13229  Syntax & semantic checks are also done in this phase, along with some initial
13230  optimizations like back patching labels and the pattern matching optimizations
13231  like bit-rotation etc.
13232 \layout Itemize
13233
13234 The second phase involves generating an intermediate code which can be easy
13235  manipulated during the later phases.
13236  This phase is entirely MCU independent.
13237  The intermediate code generation assumes the target machine has unlimited
13238  number of registers, and designates them with the name iTemp.
13239  The compiler can be made to dump a human readable form of the code generated
13240  by using the -
13241 \begin_inset ERT
13242 status Collapsed
13243
13244 \layout Standard
13245
13246 \backslash
13247 /
13248 \end_inset
13249
13250 -dumpraw option.
13251 \layout Itemize
13252
13253 This phase does the bulk of the standard optimizations and is also MCU independe
13254 nt.
13255  This phase can be broken down into several sub-phases:
13256 \newline
13257
13258 \newline
13259 Break down intermediate code (iCode) into basic blocks.
13260 \newline
13261 Do control flow & data flow analysis on the basic blocks.
13262 \newline
13263 Do local common subexpression elimination, then global subexpression elimination
13264 \newline
13265 Dead code elimination
13266 \newline
13267 Loop optimizations
13268 \newline
13269 If loop optimizations caused any changes then do 'global subexpression eliminati
13270 on' and 'dead code elimination' again.
13271 \layout Itemize
13272
13273 This phase determines the live-ranges; by live range I mean those iTemp
13274  variables defined by the compiler that still survive after all the optimization
13275 s.
13276  Live range analysis
13277 \begin_inset LatexCommand \index{Live range analysis}
13278
13279 \end_inset
13280
13281  is essential for register allocation, since these computation determines
13282  which of these iTemps will be assigned to registers, and for how long.
13283 \layout Itemize
13284
13285 Phase five is register allocation.
13286  There are two parts to this process.
13287 \newline
13288
13289 \newline
13290 The first part I call 'register packing' (for lack of a better term).
13291  In this case several MCU specific expression folding is done to reduce
13292  register pressure.
13293 \newline
13294
13295 \newline
13296 The second part is more MCU independent and deals with allocating registers
13297  to the remaining live ranges.
13298  A lot of MCU specific code does creep into this phase because of the limited
13299  number of index registers available in the 8051.
13300 \layout Itemize
13301
13302 The Code generation phase is (unhappily), entirely MCU dependent and very
13303  little (if any at all) of this code can be reused for other MCU.
13304  However the scheme for allocating a homogenized assembler operand for each
13305  iCode operand may be reused.
13306 \layout Itemize
13307
13308 As mentioned in the optimization section the peep-hole optimizer is rule
13309  based system, which can reprogrammed for other MCUs.
13310 \layout Section
13311 \pagebreak_top
13312 SDCDB
13313 \begin_inset LatexCommand \index{sdcdb}
13314
13315 \end_inset
13316
13317  - Source Level Debugger
13318 \begin_inset LatexCommand \index{Debugger}
13319
13320 \end_inset
13321
13322
13323 \layout Standard
13324
13325 SDCC is distributed with a source level debugger.
13326  The debugger uses a command line interface, the command repertoire of the
13327  debugger has been kept as close to gdb
13328 \begin_inset LatexCommand \index{gdb}
13329
13330 \end_inset
13331
13332  (the GNU debugger) as possible.
13333  The configuration and build process is part of the standard compiler installati
13334 on, which also builds and installs the debugger in the target directory
13335  specified during configuration.
13336  The debugger allows you debug BOTH at the C source and at the ASM source
13337  level.
13338 \layout Subsection
13339
13340 Compiling for Debugging
13341 \layout Standard
13342
13343 The \SpecialChar \-
13344 \SpecialChar \-
13345 debug option must be specified for all files for which debug information
13346  is to be generated.
13347  The complier generates a .adb file for each of these files.
13348  The linker creates the .cdb file from the .adb files and the address information.
13349  This .cdb is used by the debugger.
13350 \layout Subsection
13351
13352 How the Debugger Works
13353 \layout Standard
13354
13355 When the -
13356 \begin_inset ERT
13357 status Collapsed
13358
13359 \layout Standard
13360
13361 \backslash
13362 /
13363 \end_inset
13364
13365 -debug option is specified the compiler generates extra symbol information
13366  some of which are put into the the assembler source and some are put into
13367  the .adb file.
13368   Then the linker creates the .cdb file from the individual .adb files with
13369  the address information for the symbols.
13370  The debugger reads the symbolic information generated by the compiler &
13371  the address information generated by the linker.
13372  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
13373  execution is controlled by the debugger.
13374  When a command is issued for the debugger, it translates it into appropriate
13375  commands for the simulator.
13376 \layout Subsection
13377
13378 Starting the Debugger
13379 \layout Standard
13380
13381 The debugger can be started using the following command line.
13382  (Assume the file you are debugging has the file name foo).
13383 \newline
13384
13385 \newline
13386
13387 \family sans
13388 \series bold
13389 sdcdb foo
13390 \newline
13391
13392 \family default
13393 \series default
13394
13395 \newline
13396 The debugger will look for the following files.
13397 \layout Itemize
13398
13399 foo.c - the source file.
13400 \layout Itemize
13401
13402 foo.cdb - the debugger symbol information file.
13403 \layout Itemize
13404
13405 foo.ihx - the Intel hex format
13406 \begin_inset LatexCommand \index{Intel hex format}
13407
13408 \end_inset
13409
13410  object file.
13411 \layout Subsection
13412
13413 Command Line Options.
13414 \layout Itemize
13415
13416 -
13417 \begin_inset ERT
13418 status Collapsed
13419
13420 \layout Standard
13421
13422 \backslash
13423 /
13424 \end_inset
13425
13426 -directory=<source file directory> this option can used to specify the directory
13427  search list.
13428  The debugger will look into the directory list specified for source, cdb
13429  & ihx files.
13430  The items in the directory list must be separated by ':', e.g.
13431  if the source files can be in the directories /home/src1 and /home/src2,
13432  the -
13433 \begin_inset ERT
13434 status Collapsed
13435
13436 \layout Standard
13437
13438 \backslash
13439 /
13440 \end_inset
13441
13442 -directory option should be -
13443 \begin_inset ERT
13444 status Collapsed
13445
13446 \layout Standard
13447
13448 \backslash
13449 /
13450 \end_inset
13451
13452 -directory=/home/src1:/home/src2.
13453  Note there can be no spaces in the option.
13454
13455 \layout Itemize
13456
13457 -cd <directory> - change to the <directory>.
13458 \layout Itemize
13459
13460 -fullname - used by GUI front ends.
13461 \layout Itemize
13462
13463 -cpu <cpu-type> - this argument is passed to the simulator please see the
13464  simulator docs for details.
13465 \layout Itemize
13466
13467 -X <Clock frequency > this options is passed to the simulator please see
13468  the simulator docs for details.
13469 \layout Itemize
13470
13471 -s <serial port file> passed to simulator see the simulator docs for details.
13472 \layout Itemize
13473
13474 -S <serial in,out> passed to simulator see the simulator docs for details.
13475 \layout Subsection
13476
13477 Debugger Commands.
13478 \layout Standard
13479
13480 As mention earlier the command interface for the debugger has been deliberately
13481  kept as close the GNU debugger gdb, as possible.
13482  This will help the integration with existing graphical user interfaces
13483  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
13484 \layout Subsubsection
13485
13486 break [line | file:line | function | file:function]
13487 \layout Standard
13488
13489 Set breakpoint at specified line or function:
13490 \newline
13491
13492 \newline
13493
13494 \family sans
13495 \series bold
13496 sdcdb>break 100
13497 \newline
13498 sdcdb>break foo.c:100
13499 \newline
13500 sdcdb>break funcfoo
13501 \newline
13502 sdcdb>break foo.c:funcfoo
13503 \layout Subsubsection
13504
13505 clear [line | file:line | function | file:function ]
13506 \layout Standard
13507
13508 Clear breakpoint at specified line or function:
13509 \newline
13510
13511 \newline
13512
13513 \family sans
13514 \series bold
13515 sdcdb>clear 100
13516 \newline
13517 sdcdb>clear foo.c:100
13518 \newline
13519 sdcdb>clear funcfoo
13520 \newline
13521 sdcdb>clear foo.c:funcfoo
13522 \layout Subsubsection
13523
13524 continue
13525 \layout Standard
13526
13527 Continue program being debugged, after breakpoint.
13528 \layout Subsubsection
13529
13530 finish
13531 \layout Standard
13532
13533 Execute till the end of the current function.
13534 \layout Subsubsection
13535
13536 delete [n]
13537 \layout Standard
13538
13539 Delete breakpoint number 'n'.
13540  If used without any option clear ALL user defined break points.
13541 \layout Subsubsection
13542
13543 info [break | stack | frame | registers ]
13544 \layout Itemize
13545
13546 info break - list all breakpoints
13547 \layout Itemize
13548
13549 info stack - show the function call stack.
13550 \layout Itemize
13551
13552 info frame - show information about the current execution frame.
13553 \layout Itemize
13554
13555 info registers - show content of all registers.
13556 \layout Subsubsection
13557
13558 step
13559 \layout Standard
13560
13561 Step program until it reaches a different source line.
13562 \layout Subsubsection
13563
13564 next
13565 \layout Standard
13566
13567 Step program, proceeding through subroutine calls.
13568 \layout Subsubsection
13569
13570 run
13571 \layout Standard
13572
13573 Start debugged program.
13574 \layout Subsubsection
13575
13576 ptype variable
13577 \layout Standard
13578
13579 Print type information of the variable.
13580 \layout Subsubsection
13581
13582 print variable
13583 \layout Standard
13584
13585 print value of variable.
13586 \layout Subsubsection
13587
13588 file filename
13589 \layout Standard
13590
13591 load the given file name.
13592  Note this is an alternate method of loading file for debugging.
13593 \layout Subsubsection
13594
13595 frame
13596 \layout Standard
13597
13598 print information about current frame.
13599 \layout Subsubsection
13600
13601 set srcmode
13602 \layout Standard
13603
13604 Toggle between C source & assembly source.
13605 \layout Subsubsection
13606
13607 ! simulator command
13608 \layout Standard
13609
13610 Send the string following '!' to the simulator, the simulator response is
13611  displayed.
13612  Note the debugger does not interpret the command being sent to the simulator,
13613  so if a command like 'go' is sent the debugger can loose its execution
13614  context and may display incorrect values.
13615 \layout Subsubsection
13616
13617 quit.
13618 \layout Standard
13619
13620 "Watch me now.
13621  Iam going Down.
13622  My name is Bobby Brown"
13623 \layout Subsection
13624
13625 Interfacing with XEmacs
13626 \begin_inset LatexCommand \index{XEmacs}
13627
13628 \end_inset
13629
13630
13631 \begin_inset LatexCommand \index{Emacs}
13632
13633 \end_inset
13634
13635 .
13636 \layout Standard
13637
13638 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
13639  sdcdb.el and sdcdbsrc.el.
13640  These two files can be found in the $(prefix)/bin directory after the installat
13641 ion is complete.
13642  These files need to be loaded into XEmacs for the interface to work.
13643  This can be done at XEmacs startup time by inserting the following into
13644  your '.xemacs' file (which can be found in your HOME directory):
13645 \newline
13646
13647 \newline
13648
13649 \family typewriter
13650 (load-file sdcdbsrc.el)
13651 \family default
13652
13653 \newline
13654
13655 \newline
13656 .xemacs is a lisp file so the () around the command is REQUIRED.
13657  The files can also be loaded dynamically while XEmacs is running, set the
13658  environment variable 'EMACSLOADPATH' to the installation bin directory
13659  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
13660  To start the interface enter the following command:
13661 \newline
13662
13663 \newline
13664
13665 \family sans
13666 \series bold
13667 ESC-x sdcdbsrc
13668 \family default
13669 \series default
13670
13671 \newline
13672
13673 \newline
13674 You will prompted to enter the file name to be debugged.
13675
13676 \newline
13677
13678 \newline
13679 The command line options that are passed to the simulator directly are bound
13680  to default values in the file sdcdbsrc.el.
13681  The variables are listed below, these values maybe changed as required.
13682 \layout Itemize
13683
13684 sdcdbsrc-cpu-type '51
13685 \layout Itemize
13686
13687 sdcdbsrc-frequency '11059200
13688 \layout Itemize
13689
13690 sdcdbsrc-serial nil
13691 \layout Standard
13692
13693 The following is a list of key mapping for the debugger interface.
13694 \layout Standard
13695
13696 \SpecialChar ~
13697
13698 \family typewriter
13699
13700 \newline
13701 ;; Current Listing ::
13702 \newline
13703 ;;key\SpecialChar ~
13704 \SpecialChar ~
13705 \SpecialChar ~
13706 \SpecialChar ~
13707 \SpecialChar ~
13708 \SpecialChar ~
13709 \SpecialChar ~
13710 \SpecialChar ~
13711 \SpecialChar ~
13712 \SpecialChar ~
13713 \SpecialChar ~
13714 \SpecialChar ~
13715 \SpecialChar ~
13716 \SpecialChar ~
13717 \SpecialChar ~
13718 binding\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 \SpecialChar ~
13735 \SpecialChar ~
13736 \SpecialChar ~
13737 \SpecialChar ~
13738 \SpecialChar ~
13739 \SpecialChar ~
13740 Comment
13741 \newline
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 \SpecialChar ~
13774 \SpecialChar ~
13775 \SpecialChar ~
13776 \SpecialChar ~
13777 \SpecialChar ~
13778 \SpecialChar ~
13779 --------
13780 \newline
13781 ;;
13782 \newline
13783 ;; n\SpecialChar ~
13784 \SpecialChar ~
13785 \SpecialChar ~
13786 \SpecialChar ~
13787 \SpecialChar ~
13788 \SpecialChar ~
13789 \SpecialChar ~
13790 \SpecialChar ~
13791 \SpecialChar ~
13792 \SpecialChar ~
13793 \SpecialChar ~
13794 \SpecialChar ~
13795 \SpecialChar ~
13796 \SpecialChar ~
13797  sdcdb-next-from-src\SpecialChar ~
13798 \SpecialChar ~
13799 \SpecialChar ~
13800 \SpecialChar ~
13801 \SpecialChar ~
13802 \SpecialChar ~
13803 \SpecialChar ~
13804 \SpecialChar ~
13805 \SpecialChar ~
13806 \SpecialChar ~
13807 SDCDB next command
13808 \newline
13809 ;; b\SpecialChar ~
13810 \SpecialChar ~
13811 \SpecialChar ~
13812 \SpecialChar ~
13813 \SpecialChar ~
13814 \SpecialChar ~
13815 \SpecialChar ~
13816 \SpecialChar ~
13817 \SpecialChar ~
13818 \SpecialChar ~
13819 \SpecialChar ~
13820 \SpecialChar ~
13821 \SpecialChar ~
13822 \SpecialChar ~
13823  sdcdb-back-from-src\SpecialChar ~
13824 \SpecialChar ~
13825 \SpecialChar ~
13826 \SpecialChar ~
13827 \SpecialChar ~
13828 \SpecialChar ~
13829 \SpecialChar ~
13830 \SpecialChar ~
13831 \SpecialChar ~
13832 \SpecialChar ~
13833 SDCDB back command
13834 \newline
13835 ;; c\SpecialChar ~
13836 \SpecialChar ~
13837 \SpecialChar ~
13838 \SpecialChar ~
13839 \SpecialChar ~
13840 \SpecialChar ~
13841 \SpecialChar ~
13842 \SpecialChar ~
13843 \SpecialChar ~
13844 \SpecialChar ~
13845 \SpecialChar ~
13846 \SpecialChar ~
13847 \SpecialChar ~
13848 \SpecialChar ~
13849  sdcdb-cont-from-src\SpecialChar ~
13850 \SpecialChar ~
13851 \SpecialChar ~
13852 \SpecialChar ~
13853 \SpecialChar ~
13854 \SpecialChar ~
13855 \SpecialChar ~
13856 \SpecialChar ~
13857 \SpecialChar ~
13858 \SpecialChar ~
13859 SDCDB continue command
13860 \newline
13861 ;; s\SpecialChar ~
13862 \SpecialChar ~
13863 \SpecialChar ~
13864 \SpecialChar ~
13865 \SpecialChar ~
13866 \SpecialChar ~
13867 \SpecialChar ~
13868 \SpecialChar ~
13869 \SpecialChar ~
13870 \SpecialChar ~
13871 \SpecialChar ~
13872 \SpecialChar ~
13873 \SpecialChar ~
13874 \SpecialChar ~
13875  sdcdb-step-from-src\SpecialChar ~
13876 \SpecialChar ~
13877 \SpecialChar ~
13878 \SpecialChar ~
13879 \SpecialChar ~
13880 \SpecialChar ~
13881 \SpecialChar ~
13882 \SpecialChar ~
13883 \SpecialChar ~
13884 \SpecialChar ~
13885 SDCDB step command
13886 \newline
13887 ;; ?\SpecialChar ~
13888 \SpecialChar ~
13889 \SpecialChar ~
13890 \SpecialChar ~
13891 \SpecialChar ~
13892 \SpecialChar ~
13893 \SpecialChar ~
13894 \SpecialChar ~
13895 \SpecialChar ~
13896 \SpecialChar ~
13897 \SpecialChar ~
13898 \SpecialChar ~
13899 \SpecialChar ~
13900 \SpecialChar ~
13901  sdcdb-whatis-c-sexp\SpecialChar ~
13902 \SpecialChar ~
13903 \SpecialChar ~
13904 \SpecialChar ~
13905 \SpecialChar ~
13906 \SpecialChar ~
13907 \SpecialChar ~
13908 \SpecialChar ~
13909 \SpecialChar ~
13910 \SpecialChar ~
13911 SDCDB ptypecommand for data at
13912 \newline
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 \SpecialChar ~
13954 \SpecialChar ~
13955 \SpecialChar ~
13956 \SpecialChar ~
13957 \SpecialChar ~
13958 \SpecialChar ~
13959  buffer point
13960 \newline
13961 ;; x\SpecialChar ~
13962 \SpecialChar ~
13963 \SpecialChar ~
13964 \SpecialChar ~
13965 \SpecialChar ~
13966 \SpecialChar ~
13967 \SpecialChar ~
13968 \SpecialChar ~
13969 \SpecialChar ~
13970 \SpecialChar ~
13971 \SpecialChar ~
13972 \SpecialChar ~
13973 \SpecialChar ~
13974 \SpecialChar ~
13975  sdcdbsrc-delete\SpecialChar ~
13976 \SpecialChar ~
13977 \SpecialChar ~
13978 \SpecialChar ~
13979 \SpecialChar ~
13980 \SpecialChar ~
13981 \SpecialChar ~
13982 \SpecialChar ~
13983 \SpecialChar ~
13984 \SpecialChar ~
13985 \SpecialChar ~
13986 \SpecialChar ~
13987 \SpecialChar ~
13988 \SpecialChar ~
13989 SDCDB Delete all breakpoints if no arg
13990 \newline
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 \SpecialChar ~
14032 \SpecialChar ~
14033 \SpecialChar ~
14034 \SpecialChar ~
14035 \SpecialChar ~
14036 \SpecialChar ~
14037 given or delete arg (C-u arg x)
14038 \newline
14039 ;; m\SpecialChar ~
14040 \SpecialChar ~
14041 \SpecialChar ~
14042 \SpecialChar ~
14043 \SpecialChar ~
14044 \SpecialChar ~
14045 \SpecialChar ~
14046 \SpecialChar ~
14047 \SpecialChar ~
14048 \SpecialChar ~
14049 \SpecialChar ~
14050 \SpecialChar ~
14051 \SpecialChar ~
14052 \SpecialChar ~
14053  sdcdbsrc-frame\SpecialChar ~
14054 \SpecialChar ~
14055 \SpecialChar ~
14056 \SpecialChar ~
14057 \SpecialChar ~
14058 \SpecialChar ~
14059 \SpecialChar ~
14060 \SpecialChar ~
14061 \SpecialChar ~
14062 \SpecialChar ~
14063 \SpecialChar ~
14064 \SpecialChar ~
14065 \SpecialChar ~
14066 \SpecialChar ~
14067 \SpecialChar ~
14068 SDCDB Display current frame if no arg,
14069 \newline
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 \SpecialChar ~
14112 \SpecialChar ~
14113 \SpecialChar ~
14114 \SpecialChar ~
14115 \SpecialChar ~
14116 \SpecialChar ~
14117 given or display frame arg
14118 \newline
14119 ;;\SpecialChar ~
14120 \SpecialChar ~
14121 \SpecialChar ~
14122 \SpecialChar ~
14123 \SpecialChar ~
14124 \SpecialChar ~
14125 \SpecialChar ~
14126 \SpecialChar ~
14127 \SpecialChar ~
14128 \SpecialChar ~
14129 \SpecialChar ~
14130 \SpecialChar ~
14131 \SpecialChar ~
14132 \SpecialChar ~
14133 \SpecialChar ~
14134 \SpecialChar ~
14135 \SpecialChar ~
14136 \SpecialChar ~
14137 \SpecialChar ~
14138 \SpecialChar ~
14139 \SpecialChar ~
14140 \SpecialChar ~
14141 \SpecialChar ~
14142 \SpecialChar ~
14143 \SpecialChar ~
14144 \SpecialChar ~
14145 \SpecialChar ~
14146 \SpecialChar ~
14147 \SpecialChar ~
14148 \SpecialChar ~
14149 \SpecialChar ~
14150 \SpecialChar ~
14151 \SpecialChar ~
14152 \SpecialChar ~
14153 \SpecialChar ~
14154 \SpecialChar ~
14155 \SpecialChar ~
14156 \SpecialChar ~
14157 \SpecialChar ~
14158 \SpecialChar ~
14159 \SpecialChar ~
14160 \SpecialChar ~
14161 \SpecialChar ~
14162 \SpecialChar ~
14163 \SpecialChar ~
14164 \SpecialChar ~
14165 \SpecialChar ~
14166 buffer point
14167 \newline
14168 ;; !\SpecialChar ~
14169 \SpecialChar ~
14170 \SpecialChar ~
14171 \SpecialChar ~
14172 \SpecialChar ~
14173 \SpecialChar ~
14174 \SpecialChar ~
14175 \SpecialChar ~
14176 \SpecialChar ~
14177 \SpecialChar ~
14178 \SpecialChar ~
14179 \SpecialChar ~
14180 \SpecialChar ~
14181 \SpecialChar ~
14182  sdcdbsrc-goto-sdcdb\SpecialChar ~
14183 \SpecialChar ~
14184 \SpecialChar ~
14185 \SpecialChar ~
14186 \SpecialChar ~
14187 \SpecialChar ~
14188 \SpecialChar ~
14189 \SpecialChar ~
14190 \SpecialChar ~
14191 \SpecialChar ~
14192 Goto the SDCDB output buffer
14193 \newline
14194 ;; p\SpecialChar ~
14195 \SpecialChar ~
14196 \SpecialChar ~
14197 \SpecialChar ~
14198 \SpecialChar ~
14199 \SpecialChar ~
14200 \SpecialChar ~
14201 \SpecialChar ~
14202 \SpecialChar ~
14203 \SpecialChar ~
14204 \SpecialChar ~
14205 \SpecialChar ~
14206 \SpecialChar ~
14207 \SpecialChar ~
14208  sdcdb-print-c-sexp\SpecialChar ~
14209 \SpecialChar ~
14210 \SpecialChar ~
14211 \SpecialChar ~
14212 \SpecialChar ~
14213 \SpecialChar ~
14214 \SpecialChar ~
14215 \SpecialChar ~
14216 \SpecialChar ~
14217 \SpecialChar ~
14218 \SpecialChar ~
14219 SDCDB print command for data at
14220 \newline
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 \SpecialChar ~
14262 \SpecialChar ~
14263 \SpecialChar ~
14264 \SpecialChar ~
14265 \SpecialChar ~
14266 \SpecialChar ~
14267  buffer point
14268 \newline
14269 ;; g\SpecialChar ~
14270 \SpecialChar ~
14271 \SpecialChar ~
14272 \SpecialChar ~
14273 \SpecialChar ~
14274 \SpecialChar ~
14275 \SpecialChar ~
14276 \SpecialChar ~
14277 \SpecialChar ~
14278 \SpecialChar ~
14279 \SpecialChar ~
14280 \SpecialChar ~
14281 \SpecialChar ~
14282 \SpecialChar ~
14283  sdcdbsrc-goto-sdcdb\SpecialChar ~
14284 \SpecialChar ~
14285 \SpecialChar ~
14286 \SpecialChar ~
14287 \SpecialChar ~
14288 \SpecialChar ~
14289 \SpecialChar ~
14290 \SpecialChar ~
14291 \SpecialChar ~
14292 \SpecialChar ~
14293 Goto the SDCDB output buffer
14294 \newline
14295 ;; t\SpecialChar ~
14296 \SpecialChar ~
14297 \SpecialChar ~
14298 \SpecialChar ~
14299 \SpecialChar ~
14300 \SpecialChar ~
14301 \SpecialChar ~
14302 \SpecialChar ~
14303 \SpecialChar ~
14304 \SpecialChar ~
14305 \SpecialChar ~
14306 \SpecialChar ~
14307 \SpecialChar ~
14308 \SpecialChar ~
14309  sdcdbsrc-mode\SpecialChar ~
14310 \SpecialChar ~
14311 \SpecialChar ~
14312 \SpecialChar ~
14313 \SpecialChar ~
14314 \SpecialChar ~
14315 \SpecialChar ~
14316 \SpecialChar ~
14317 \SpecialChar ~
14318 \SpecialChar ~
14319 \SpecialChar ~
14320 \SpecialChar ~
14321 \SpecialChar ~
14322 \SpecialChar ~
14323 \SpecialChar ~
14324 \SpecialChar ~
14325 Toggles Sdcdbsrc mode (turns it off)
14326 \newline
14327 ;;
14328 \newline
14329 ;; C-c C-f\SpecialChar ~
14330 \SpecialChar ~
14331 \SpecialChar ~
14332 \SpecialChar ~
14333 \SpecialChar ~
14334 \SpecialChar ~
14335 \SpecialChar ~
14336 \SpecialChar ~
14337  sdcdb-finish-from-src\SpecialChar ~
14338 \SpecialChar ~
14339 \SpecialChar ~
14340 \SpecialChar ~
14341 \SpecialChar ~
14342 \SpecialChar ~
14343 \SpecialChar ~
14344 \SpecialChar ~
14345 SDCDB finish command
14346 \newline
14347 ;;
14348 \newline
14349 ;; C-x SPC\SpecialChar ~
14350 \SpecialChar ~
14351 \SpecialChar ~
14352 \SpecialChar ~
14353 \SpecialChar ~
14354 \SpecialChar ~
14355 \SpecialChar ~
14356 \SpecialChar ~
14357  sdcdb-break\SpecialChar ~
14358 \SpecialChar ~
14359 \SpecialChar ~
14360 \SpecialChar ~
14361 \SpecialChar ~
14362 \SpecialChar ~
14363 \SpecialChar ~
14364 \SpecialChar ~
14365 \SpecialChar ~
14366 \SpecialChar ~
14367 \SpecialChar ~
14368 \SpecialChar ~
14369 \SpecialChar ~
14370 \SpecialChar ~
14371 \SpecialChar ~
14372 \SpecialChar ~
14373 \SpecialChar ~
14374 \SpecialChar ~
14375 Set break for line with point
14376 \newline
14377 ;; ESC t\SpecialChar ~
14378 \SpecialChar ~
14379 \SpecialChar ~
14380 \SpecialChar ~
14381 \SpecialChar ~
14382 \SpecialChar ~
14383 \SpecialChar ~
14384 \SpecialChar ~
14385 \SpecialChar ~
14386 \SpecialChar ~
14387  sdcdbsrc-mode\SpecialChar ~
14388 \SpecialChar ~
14389 \SpecialChar ~
14390 \SpecialChar ~
14391 \SpecialChar ~
14392 \SpecialChar ~
14393 \SpecialChar ~
14394 \SpecialChar ~
14395 \SpecialChar ~
14396 \SpecialChar ~
14397 \SpecialChar ~
14398 \SpecialChar ~
14399 \SpecialChar ~
14400 \SpecialChar ~
14401 \SpecialChar ~
14402 \SpecialChar ~
14403 Toggle Sdcdbsrc mode
14404 \newline
14405 ;; ESC m\SpecialChar ~
14406 \SpecialChar ~
14407 \SpecialChar ~
14408 \SpecialChar ~
14409 \SpecialChar ~
14410 \SpecialChar ~
14411 \SpecialChar ~
14412 \SpecialChar ~
14413 \SpecialChar ~
14414 \SpecialChar ~
14415  sdcdbsrc-srcmode\SpecialChar ~
14416 \SpecialChar ~
14417 \SpecialChar ~
14418 \SpecialChar ~
14419 \SpecialChar ~
14420 \SpecialChar ~
14421 \SpecialChar ~
14422 \SpecialChar ~
14423 \SpecialChar ~
14424 \SpecialChar ~
14425 \SpecialChar ~
14426 \SpecialChar ~
14427  Toggle list mode
14428 \newline
14429 ;;
14430 \family default
14431
14432 \newline
14433
14434 \layout Section
14435
14436 Other Processors
14437 \layout Subsection
14438
14439 The Z80 and gbz80 port
14440 \layout Standard
14441
14442 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
14443  The port is incomplete - long support is incomplete (mul, div and mod are
14444  unimplemented), and both float and bitfield support is missing.
14445  Apart from that the code generated is correct.
14446 \layout Standard
14447
14448 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
14449  The stack frame is similar to that generated by the IAR Z80 compiler.
14450  IX is used as the base pointer, HL is used as a temporary register, and
14451  BC and DE are available for holding variables.
14452  IY is currently unused.
14453  Return values are stored in HL.
14454  One bad side effect of using IX as the base pointer is that a functions
14455  stack frame is limited to 127 bytes - this will be fixed in a later version.
14456 \layout Section
14457 \pagebreak_top
14458 Support
14459 \begin_inset LatexCommand \index{Support}
14460
14461 \end_inset
14462
14463
14464 \layout Standard
14465
14466 SDCC has grown to be a large project.
14467  The compiler alone (without the preprocessor, assembler and linker) is
14468  about 40,000 lines of code (blank stripped).
14469  The open source nature of this project is a key to its continued growth
14470  and support.
14471  You gain the benefit and support of many active software developers and
14472  end users.
14473  Is SDCC perfect? No, that's why we need your help.
14474  The developers take pride in fixing reported bugs.
14475  You can help by reporting the bugs and helping other SDCC users.
14476  There are lots of ways to contribute, and we encourage you to take part
14477  in making SDCC a great software package.
14478
14479 \layout Standard
14480
14481 The SDCC project is hosted on the sdcc sourceforge site at
14482 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
14483
14484 \end_inset
14485
14486 .
14487  You'll find the complete set of mailing lists
14488 \begin_inset LatexCommand \index{Mailing list}
14489
14490 \end_inset
14491
14492 , forums, bug reporting system, patch submission
14493 \begin_inset LatexCommand \index{Patch submission}
14494
14495 \end_inset
14496
14497  system, download
14498 \begin_inset LatexCommand \index{download}
14499
14500 \end_inset
14501
14502  area and cvs code repository
14503 \begin_inset LatexCommand \index{cvs code repository}
14504
14505 \end_inset
14506
14507  there.
14508 \layout Subsection
14509
14510 Reporting Bugs
14511 \begin_inset LatexCommand \index{Bugs}
14512
14513 \end_inset
14514
14515
14516 \begin_inset LatexCommand \index{Reporting bugs}
14517
14518 \end_inset
14519
14520
14521 \layout Standard
14522
14523 The recommended way of reporting bugs is using the infrastructure of the
14524  sourceforge site.
14525  You can follow the status of bug reports there and have an overview about
14526  the known bugs.
14527 \layout Standard
14528
14529 Bug reports are automatically forwarded to the developer mailing list and
14530  will be fixed ASAP.
14531  When reporting a bug, it is very useful to include a small test program
14532  which reproduces the problem.
14533  If you can isolate the problem by looking at the generated assembly code,
14534  this can be very helpful.
14535  Compiling your program with the -
14536 \begin_inset ERT
14537 status Collapsed
14538
14539 \layout Standard
14540
14541 \backslash
14542 /
14543 \end_inset
14544
14545 -dumpall
14546 \begin_inset LatexCommand \index{-\/-dumpall}
14547
14548 \end_inset
14549
14550  option can sometimes be useful in locating optimization problems.
14551 \layout Standard
14552
14553 Please have a short check that you are using a recent version of SDCC and
14554  the bug is not yet known.
14555  This is the link for reporting bugs:
14556 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
14557
14558 \end_inset
14559
14560 .
14561 \layout Subsection
14562
14563 Requesting Features
14564 \begin_inset LatexCommand \index{Feature request}
14565
14566 \end_inset
14567
14568
14569 \begin_inset LatexCommand \index{Requesting features}
14570
14571 \end_inset
14572
14573
14574 \layout Standard
14575
14576 Like bug reports feature requests are forwarded to the developer mailing
14577  list.
14578  This is the link for requesting features:
14579 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
14580
14581 \end_inset
14582
14583 .
14584 \layout Subsection
14585
14586 Getting Help
14587 \layout Standard
14588
14589 These links should take you directly to the
14590 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
14591
14592 \end_inset
14593
14594
14595 \begin_inset Foot
14596 collapsed false
14597
14598 \layout Standard
14599
14600 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
14601  automated messages (mid 2003)
14602 \end_inset
14603
14604  and the
14605 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
14606
14607 \end_inset
14608
14609 , lists and forums are archived so if you are lucky someone already had
14610  a similar problem.
14611 \layout Subsection
14612
14613 ChangeLog
14614 \begin_inset LatexCommand \index{Changelog}
14615
14616 \end_inset
14617
14618
14619 \layout Standard
14620
14621 You can follow the status of the cvs version
14622 \begin_inset LatexCommand \index{version}
14623
14624 \end_inset
14625
14626  of SDCC by watching the file
14627 \begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
14628
14629 \end_inset
14630
14631  in the cvs-repository.
14632 \layout Subsection
14633
14634 Release policy
14635 \begin_inset LatexCommand \index{Release policy}
14636
14637 \end_inset
14638
14639
14640 \layout Standard
14641
14642 Historically there often were long delays between official releases and
14643  the sourceforge download area tends to get not updated at all.
14644  Current excuses might refer to problems with live range analysis, but if
14645  this is fixed, the next problem rising is that another excuse will have
14646  to be found.
14647  Kidding aside, we have to get better there!
14648 \layout Subsection
14649
14650 Examples
14651 \begin_inset LatexCommand \index{Examples}
14652
14653 \end_inset
14654
14655
14656 \layout Standard
14657
14658 You'll find some small examples in the directory sdcc/device/examples/
14659 \layout Comment
14660
14661 Maybe we should include some links to real world applications.
14662  Preferably pointer to pointers (one for each architecture) so this stays
14663  manageable here?
14664 \layout Subsection
14665
14666 Quality control
14667 \begin_inset LatexCommand \index{Quality control}
14668
14669 \end_inset
14670
14671
14672 \layout Standard
14673
14674 The compiler is passed through nightly compile and build checks.
14675  The so called
14676 \shape italic
14677 regression tests
14678 \shape default
14679
14680 \begin_inset LatexCommand \index{Regression test}
14681
14682 \end_inset
14683
14684  check that SDCC itself compiles flawlessly on several platforms and checks
14685  the quality of the code generated by SDCC by running the code through simulator
14686 s.
14687  There is a separate document
14688 \shape italic
14689 test_suite.pdf
14690 \begin_inset LatexCommand \index{Test suite}
14691
14692 \end_inset
14693
14694
14695 \shape default
14696  about this.
14697 \layout Standard
14698
14699 You'll find the test code in the directory
14700 \shape italic
14701 sdcc/support/regression
14702 \shape default
14703 .
14704  You can run these tests manually by running
14705 \family sans
14706 make
14707 \family default
14708  in this directory (or f.e.
14709
14710 \family sans
14711 make test-mcs51
14712 \family default
14713  if you don't want to run the complete tests).
14714  The test code might also be interesting if you want to look for examples
14715 \begin_inset LatexCommand \index{Examples}
14716
14717 \end_inset
14718
14719  checking corner cases of SDCC or if you plan to submit patches
14720 \begin_inset LatexCommand \index{Patch submission}
14721
14722 \end_inset
14723
14724 .
14725 \layout Standard
14726
14727 The pic port uses a different set of regression tests, you'll find them
14728  in the directory
14729 \shape italic
14730 sdcc/src/regression
14731 \shape default
14732 .
14733 \layout Section
14734 \pagebreak_top
14735 Compiler internals
14736 \begin_inset LatexCommand \index{Compiler internals}
14737
14738 \end_inset
14739
14740
14741 \layout Subsection
14742
14743 The anatomy of the compiler
14744 \layout Standard
14745
14746
14747 \shape italic
14748 This is an excerpt from an article published in Circuit Cellar Magazine
14749  in august 2000.
14750  It's a little outdated (the compiler is much more efficient now and user/develo
14751 per friendly), but pretty well exposes the guts of it all.
14752 \shape default
14753
14754 \newline
14755
14756 \newline
14757 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
14758  It is fairly easy to retarget for other 8-bit MCU.
14759  Here we take a look at some of the internals of the compiler.
14760
14761 \layout Paragraph*
14762
14763 Parsing
14764 \begin_inset LatexCommand \index{Parsing}
14765
14766 \end_inset
14767
14768
14769 \layout Standard
14770
14771 Parsing the input source file and creating an AST (Annotated Syntax Tree
14772 \begin_inset LatexCommand \index{Annotated syntax tree}
14773
14774 \end_inset
14775
14776 ).
14777  This phase also involves propagating types (annotating each node of the
14778  parse tree with type information) and semantic analysis.
14779  There are some MCU specific parsing rules.
14780  For example the storage classes, the extended storage classes are MCU specific
14781  while there may be a xdata storage class for 8051 there is no such storage
14782  class for z80 or Atmel AVR.
14783  SDCC allows MCU specific storage class extensions, i.e.
14784  xdata will be treated as a storage class specifier when parsing 8051 C
14785  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
14786  C code.
14787 \layout Paragraph*
14788
14789 Generating iCode
14790 \begin_inset LatexCommand \index{iCode}
14791
14792 \end_inset
14793
14794
14795 \layout Standard
14796
14797 Intermediate code generation.
14798  In this phase the AST is broken down into three-operand form (iCode).
14799  These three operand forms are represented as doubly linked lists.
14800  ICode is the term given to the intermediate form generated by the compiler.
14801  ICode example section shows some examples of iCode generated for some simple
14802  C source functions.
14803 \layout Paragraph*
14804
14805 Optimizations
14806 \begin_inset LatexCommand \index{Optimizations}
14807
14808 \end_inset
14809
14810 .
14811 \layout Standard
14812
14813 Bulk of the target independent optimizations is performed in this phase.
14814  The optimizations include constant propagation, common sub-expression eliminati
14815 on, loop invariant code movement, strength reduction of loop induction variables
14816  and dead-code elimination.
14817 \layout Paragraph*
14818
14819 Live range analysis
14820 \begin_inset LatexCommand \index{Live range analysis}
14821
14822 \end_inset
14823
14824
14825 \layout Standard
14826
14827 During intermediate code generation phase, the compiler assumes the target
14828  machine has infinite number of registers and generates a lot of temporary
14829  variables.
14830  The live range computation determines the lifetime of each of these compiler-ge
14831 nerated temporaries.
14832  A picture speaks a thousand words.
14833  ICode example sections show the live range annotations for each of the
14834  operand.
14835  It is important to note here, each iCode is assigned a number in the order
14836  of its execution in the function.
14837  The live ranges are computed in terms of these numbers.
14838  The from number is the number of the iCode which first defines the operand
14839  and the to number signifies the iCode which uses this operand last.
14840 \layout Paragraph*
14841
14842 Register Allocation
14843 \begin_inset LatexCommand \index{Register allocation}
14844
14845 \end_inset
14846
14847
14848 \layout Standard
14849
14850 The register allocation determines the type and number of registers needed
14851  by each operand.
14852  In most MCUs only a few registers can be used for indirect addressing.
14853  In case of 8051 for example the registers R0 & R1 can be used to indirectly
14854  address the internal ram and DPTR to indirectly address the external ram.
14855  The compiler will try to allocate the appropriate register to pointer variables
14856  if it can.
14857  ICode example section shows the operands annotated with the registers assigned
14858  to them.
14859  The compiler will try to keep operands in registers as much as possible;
14860  there are several schemes the compiler uses to do achieve this.
14861  When the compiler runs out of registers the compiler will check to see
14862  if there are any live operands which is not used or defined in the current
14863  basic block being processed, if there are any found then it will push that
14864  operand and use the registers in this block, the operand will then be popped
14865  at the end of the basic block.
14866
14867 \layout Standard
14868
14869 There are other MCU specific considerations in this phase.
14870  Some MCUs have an accumulator; very short-lived operands could be assigned
14871  to the accumulator instead of general-purpose register.
14872 \layout Paragraph*
14873
14874 Code generation
14875 \layout Standard
14876
14877 Figure II gives a table of iCode operations supported by the compiler.
14878  The code generation involves translating these operations into corresponding
14879  assembly code for the processor.
14880  This sounds overly simple but that is the essence of code generation.
14881  Some of the iCode operations are generated on a MCU specific manner for
14882  example, the z80 port does not use registers to pass parameters so the
14883  SEND and RECV iCode operations will not be generated, and it also does
14884  not support JUMPTABLES.
14885
14886 \newline
14887
14888 \series bold
14889 \shape italic
14890 \color red
14891 <Where is Figure II ?>
14892 \layout Paragraph*
14893
14894 ICode Example
14895 \begin_inset LatexCommand \index{iCode}
14896
14897 \end_inset
14898
14899
14900 \layout Standard
14901
14902 This section shows some details of iCode.
14903  The example C code does not do anything useful; it is used as an example
14904  to illustrate the intermediate code generated by the compiler.
14905 \layout Verse
14906
14907
14908 \family typewriter
14909 1.\SpecialChar ~
14910 xdata int * p;
14911 \newline
14912 2.\SpecialChar ~
14913 int gint;
14914 \newline
14915 3.\SpecialChar ~
14916 /* This function does nothing useful.
14917  It is used
14918 \newline
14919 4.\SpecialChar ~
14920 \SpecialChar ~
14921 \SpecialChar ~
14922 \SpecialChar ~
14923 for the purpose of explaining iCode */
14924 \newline
14925 5.\SpecialChar ~
14926 short function (data int *x)
14927 \newline
14928 6.\SpecialChar ~
14929 {
14930 \newline
14931 7.\SpecialChar ~
14932 \SpecialChar ~
14933 \SpecialChar ~
14934 short i=10; /* dead initialization eliminated */
14935 \newline
14936 8.\SpecialChar ~
14937 \SpecialChar ~
14938 \SpecialChar ~
14939 short sum=10; /* dead initialization eliminated */
14940 \newline
14941 9.\SpecialChar ~
14942 \SpecialChar ~
14943 \SpecialChar ~
14944 short mul;
14945 \newline
14946 10.\SpecialChar ~
14947 \SpecialChar ~
14948 int j ;
14949 \newline
14950 11.\SpecialChar ~
14951 \SpecialChar ~
14952 while (*x) *x++ = *p++;
14953 \newline
14954 12.\SpecialChar ~
14955 \SpecialChar ~
14956 \SpecialChar ~
14957 \SpecialChar ~
14958 sum = 0 ;
14959 \newline
14960 13.\SpecialChar ~
14961 \SpecialChar ~
14962 mul = 0;
14963 \newline
14964 14.\SpecialChar ~
14965 \SpecialChar ~
14966 /* compiler detects i,j to be induction variables */
14967 \newline
14968 15.\SpecialChar ~
14969 \SpecialChar ~
14970 for (i = 0, j = 10 ; i < 10 ; i++, j--) {
14971 \newline
14972 16.\SpecialChar ~
14973 \SpecialChar ~
14974 \SpecialChar ~
14975 \SpecialChar ~
14976 sum += i;
14977 \newline
14978 17.\SpecialChar ~
14979 \SpecialChar ~
14980 \SpecialChar ~
14981 \SpecialChar ~
14982 mul += i * 3; /* this multiplication remains */
14983 \newline
14984 18.\SpecialChar ~
14985 \SpecialChar ~
14986 \SpecialChar ~
14987 \SpecialChar ~
14988 gint += j * 3;/* this multiplication changed to addition */
14989 \newline
14990 19.\SpecialChar ~
14991 \SpecialChar ~
14992 }
14993 \newline
14994 20.\SpecialChar ~
14995 \SpecialChar ~
14996 return sum+mul;
14997 \newline
14998 21.\SpecialChar ~
14999 }
15000 \layout Standard
15001
15002 In addition to the operands each iCode contains information about the filename
15003  and line it corresponds to in the source file.
15004  The first field in the listing should be interpreted as follows:
15005 \newline
15006
15007 \shape italic
15008 \size footnotesize
15009 Filename(linenumber: iCode Execution sequence number : ICode hash table
15010  key : loop depth of the iCode).
15011 \shape default
15012 \size default
15013
15014 \newline
15015 Then follows the human readable form of the ICode operation.
15016  Each operand of this triplet form can be of three basic types a) compiler
15017  generated temporary b) user defined variable c) a constant value.
15018  Note that local variables and parameters are replaced by compiler generated
15019  temporaries.
15020  Live ranges
15021 \begin_inset LatexCommand \index{Live range analysis}
15022
15023 \end_inset
15024
15025  are computed only for temporaries (i.e.
15026  live ranges are not computed for global variables).
15027  Registers
15028 \begin_inset LatexCommand \index{Register allocation}
15029
15030 \end_inset
15031
15032  are allocated for temporaries only.
15033  Operands are formatted in the following manner:
15034 \newline
15035
15036 \shape italic
15037 \size footnotesize
15038 Operand Name [lr live-from : live-to ] { type information } [ registers
15039  allocated ].
15040 \shape default
15041 \size default
15042
15043 \newline
15044 As mentioned earlier the live ranges are computed in terms of the execution
15045  sequence number of the iCodes, for example
15046 \newline
15047 the iTemp0 is live from (i.e.
15048  first defined in iCode with execution sequence number 3, and is last used
15049  in the iCode with sequence number 5).
15050  For induction variables such as iTemp21 the live range computation extends
15051  the lifetime from the start to the end of the loop.
15052 \newline
15053 The register allocator used the live range information to allocate registers,
15054  the same registers may be used for different temporaries if their live
15055  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
15056  iTemp17 since their live ranges do not overlap.
15057  In addition the allocator also takes into consideration the type and usage
15058  of a temporary, for example itemp6 is a pointer to near space and is used
15059  as to fetch data from (i.e.
15060  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
15061  Some short lived temporaries are allocated to special registers which have
15062  meaning to the code generator e.g.
15063  iTemp13 is allocated to a pseudo register CC which tells the back end that
15064  the temporary is used only for a conditional jump the code generation makes
15065  use of this information to optimize a compare and jump ICode.
15066 \newline
15067 There are several loop optimizations
15068 \begin_inset LatexCommand \index{Loop optimization}
15069
15070 \end_inset
15071
15072  performed by the compiler.
15073  It can detect induction variables iTemp21(i) and iTemp23(j).
15074  Also note the compiler does selective strength reduction
15075 \begin_inset LatexCommand \index{Strength reduction}
15076
15077 \end_inset
15078
15079 , i.e.
15080  the multiplication of an induction variable in line 18 (gint = j * 3) is
15081  changed to addition, a new temporary iTemp17 is allocated and assigned
15082  a initial value, a constant 3 is then added for each iteration of the loop.
15083  The compiler does not change the multiplication
15084 \begin_inset LatexCommand \index{Multiplication}
15085
15086 \end_inset
15087
15088  in line 17 however since the processor does support an 8 * 8 bit multiplication.
15089 \newline
15090 Note the dead code elimination
15091 \begin_inset LatexCommand \index{Dead-code elimination}
15092
15093 \end_inset
15094
15095  optimization eliminated the dead assignments in line 7 & 8 to I and sum
15096  respectively.
15097 \newline
15098
15099 \layout Standard
15100
15101
15102 \size footnotesize
15103 Sample.c (5:1:0:0) _entry($9) :
15104 \layout Standard
15105
15106
15107 \size footnotesize
15108 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
15109 \layout Standard
15110
15111
15112 \size footnotesize
15113 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
15114 \layout Standard
15115
15116
15117 \size footnotesize
15118 Sample.c(11:4:53:0) preHeaderLbl0($11) :
15119 \layout Standard
15120
15121
15122 \size footnotesize
15123 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
15124  * int}[r2]
15125 \layout Standard
15126
15127
15128 \size footnotesize
15129 Sample.c(11:6:5:1) _whilecontinue_0($1) :
15130 \layout Standard
15131
15132
15133 \size footnotesize
15134 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
15135  int}[r0]]
15136 \layout Standard
15137
15138
15139 \size footnotesize
15140 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
15141 \layout Standard
15142
15143
15144 \size footnotesize
15145 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
15146  * int}
15147 \layout Standard
15148
15149
15150 \size footnotesize
15151 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
15152  {short}
15153 \layout Standard
15154
15155
15156 \size footnotesize
15157 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
15158  * int}[DPTR]]
15159 \layout Standard
15160
15161
15162 \size footnotesize
15163 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
15164 }[r2 r3]
15165 \layout Standard
15166
15167
15168 \size footnotesize
15169 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
15170  * int}[r0] + 0x2 {short}
15171 \layout Standard
15172
15173
15174 \size footnotesize
15175 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
15176 \layout Standard
15177
15178
15179 \size footnotesize
15180 Sample.c(11:17:21:0)_whilebreak_0($3) :
15181 \layout Standard
15182
15183
15184 \size footnotesize
15185 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
15186 \layout Standard
15187
15188
15189 \size footnotesize
15190 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
15191 \layout Standard
15192
15193
15194 \size footnotesize
15195 Sample.c(15:20:54:0)preHeaderLbl1($13) :
15196 \layout Standard
15197
15198
15199 \size footnotesize
15200 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
15201 \layout Standard
15202
15203
15204 \size footnotesize
15205 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
15206 \layout Standard
15207
15208
15209 \size footnotesize
15210 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
15211 \layout Standard
15212
15213
15214 \size footnotesize
15215 Sample.c(15:24:26:1)_forcond_0($4) :
15216 \layout Standard
15217
15218
15219 \size footnotesize
15220 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
15221  < 0xa {short}
15222 \layout Standard
15223
15224
15225 \size footnotesize
15226 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
15227 \layout Standard
15228
15229
15230 \size footnotesize
15231 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
15232  + ITemp21 [lr21:38]{short}[r4]
15233 \layout Standard
15234
15235
15236 \size footnotesize
15237 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
15238  * 0x3 {short}
15239 \layout Standard
15240
15241
15242 \size footnotesize
15243 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
15244  + iTemp15 [lr29:30]{short}[r1]
15245 \layout Standard
15246
15247
15248 \size footnotesize
15249 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
15250  r0]- 0x3 {short}
15251 \layout Standard
15252
15253
15254 \size footnotesize
15255 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
15256 int}[r7 r0]
15257 \layout Standard
15258
15259
15260 \size footnotesize
15261 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
15262  + 0x1 {short}
15263 \layout Standard
15264
15265
15266 \size footnotesize
15267 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
15268  r6]- 0x1 {short}
15269 \layout Standard
15270
15271
15272 \size footnotesize
15273 Sample.c(19:38:47:1) goto _forcond_0($4)
15274 \layout Standard
15275
15276
15277 \size footnotesize
15278 Sample.c(19:39:48:0)_forbreak_0($7) :
15279 \layout Standard
15280
15281
15282 \size footnotesize
15283 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
15284  + ITemp11 [lr19:40]{short}[r3]
15285 \layout Standard
15286
15287
15288 \size footnotesize
15289 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
15290 \layout Standard
15291
15292
15293 \size footnotesize
15294 Sample.c(20:42:51:0)_return($8) :
15295 \layout Standard
15296
15297
15298 \size footnotesize
15299 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
15300 \size default
15301
15302 \newline
15303
15304 \newline
15305 Finally the code generated for this function:
15306 \newline
15307
15308 \layout Standard
15309
15310
15311 \size footnotesize
15312 .area DSEG (DATA)
15313 \layout Standard
15314
15315
15316 \size footnotesize
15317 _p::
15318 \layout Standard
15319
15320
15321 \size footnotesize
15322 \SpecialChar ~
15323 \SpecialChar ~
15324 .ds 2
15325 \layout Standard
15326
15327
15328 \size footnotesize
15329 _gint::
15330 \layout Standard
15331
15332
15333 \size footnotesize
15334 \SpecialChar ~
15335 \SpecialChar ~
15336 .ds 2
15337 \layout Standard
15338
15339
15340 \size footnotesize
15341 ; sample.c 5
15342 \layout Standard
15343
15344
15345 \size footnotesize
15346 ; ----------------------------------------------
15347 \layout Standard
15348
15349
15350 \size footnotesize
15351 ; function function
15352 \layout Standard
15353
15354
15355 \size footnotesize
15356 ; ----------------------------------------------
15357 \layout Standard
15358
15359
15360 \size footnotesize
15361 _function:
15362 \layout Standard
15363
15364
15365 \size footnotesize
15366 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
15367 \layout Standard
15368
15369
15370 \size footnotesize
15371 \SpecialChar ~
15372 \SpecialChar ~
15373 mov r2,dpl
15374 \layout Standard
15375
15376
15377 \size footnotesize
15378 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
15379 \layout Standard
15380
15381
15382 \size footnotesize
15383 \SpecialChar ~
15384 \SpecialChar ~
15385 mov ar0,r2
15386 \layout Standard
15387
15388
15389 \size footnotesize
15390 ;_whilecontinue_0($1) :
15391 \layout Standard
15392
15393
15394 \size footnotesize
15395 00101$:
15396 \layout Standard
15397
15398
15399 \size footnotesize
15400 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
15401 \layout Standard
15402
15403
15404 \size footnotesize
15405 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
15406 \layout Standard
15407
15408
15409 \size footnotesize
15410 \SpecialChar ~
15411 \SpecialChar ~
15412 mov ar2,@r0
15413 \layout Standard
15414
15415
15416 \size footnotesize
15417 \SpecialChar ~
15418 \SpecialChar ~
15419 inc r0
15420 \layout Standard
15421
15422
15423 \size footnotesize
15424 \SpecialChar ~
15425 \SpecialChar ~
15426 mov ar3,@r0
15427 \layout Standard
15428
15429
15430 \size footnotesize
15431 \SpecialChar ~
15432 \SpecialChar ~
15433 dec r0
15434 \layout Standard
15435
15436
15437 \size footnotesize
15438 \SpecialChar ~
15439 \SpecialChar ~
15440 mov a,r2
15441 \layout Standard
15442
15443
15444 \size footnotesize
15445 \SpecialChar ~
15446 \SpecialChar ~
15447 orl a,r3
15448 \layout Standard
15449
15450
15451 \size footnotesize
15452 \SpecialChar ~
15453 \SpecialChar ~
15454 jz 00103$
15455 \layout Standard
15456
15457
15458 \size footnotesize
15459 00114$:
15460 \layout Standard
15461
15462
15463 \size footnotesize
15464 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
15465 \layout Standard
15466
15467
15468 \size footnotesize
15469 \SpecialChar ~
15470 \SpecialChar ~
15471 mov dpl,_p
15472 \layout Standard
15473
15474
15475 \size footnotesize
15476 \SpecialChar ~
15477 \SpecialChar ~
15478 mov dph,(_p + 1)
15479 \layout Standard
15480
15481
15482 \size footnotesize
15483 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
15484 \layout Standard
15485
15486
15487 \size footnotesize
15488 \SpecialChar ~
15489 \SpecialChar ~
15490 mov a,#0x02
15491 \layout Standard
15492
15493
15494 \size footnotesize
15495 \SpecialChar ~
15496 \SpecialChar ~
15497 add a,_p
15498 \layout Standard
15499
15500
15501 \size footnotesize
15502 \SpecialChar ~
15503 \SpecialChar ~
15504 mov _p,a
15505 \layout Standard
15506
15507
15508 \size footnotesize
15509 \SpecialChar ~
15510 \SpecialChar ~
15511 clr a
15512 \layout Standard
15513
15514
15515 \size footnotesize
15516 \SpecialChar ~
15517 \SpecialChar ~
15518 addc a,(_p + 1)
15519 \layout Standard
15520
15521
15522 \size footnotesize
15523 \SpecialChar ~
15524 \SpecialChar ~
15525 mov (_p + 1),a
15526 \layout Standard
15527
15528
15529 \size footnotesize
15530 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
15531 \layout Standard
15532
15533
15534 \size footnotesize
15535 \SpecialChar ~
15536 \SpecialChar ~
15537 movx a,@dptr
15538 \layout Standard
15539
15540
15541 \size footnotesize
15542 \SpecialChar ~
15543 \SpecialChar ~
15544 mov r2,a
15545 \layout Standard
15546
15547
15548 \size footnotesize
15549 \SpecialChar ~
15550 \SpecialChar ~
15551 inc dptr
15552 \layout Standard
15553
15554
15555 \size footnotesize
15556 \SpecialChar ~
15557 \SpecialChar ~
15558 movx a,@dptr
15559 \layout Standard
15560
15561
15562 \size footnotesize
15563 \SpecialChar ~
15564 \SpecialChar ~
15565 mov r3,a
15566 \layout Standard
15567
15568
15569 \size footnotesize
15570 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
15571 \layout Standard
15572
15573
15574 \size footnotesize
15575 \SpecialChar ~
15576 \SpecialChar ~
15577 mov @r0,ar2
15578 \layout Standard
15579
15580
15581 \size footnotesize
15582 \SpecialChar ~
15583 \SpecialChar ~
15584 inc r0
15585 \layout Standard
15586
15587
15588 \size footnotesize
15589 \SpecialChar ~
15590 \SpecialChar ~
15591 mov @r0,ar3
15592 \layout Standard
15593
15594
15595 \size footnotesize
15596 ; iTemp6 [lr5:16]{_near * int}[r0] =
15597 \layout Standard
15598
15599
15600 \size footnotesize
15601 ; iTemp6 [lr5:16]{_near * int}[r0] +
15602 \layout Standard
15603
15604
15605 \size footnotesize
15606 ; 0x2 {short}
15607 \layout Standard
15608
15609
15610 \size footnotesize
15611 \SpecialChar ~
15612 \SpecialChar ~
15613 inc r0
15614 \layout Standard
15615
15616
15617 \size footnotesize
15618 ; goto _whilecontinue_0($1)
15619 \layout Standard
15620
15621
15622 \size footnotesize
15623 \SpecialChar ~
15624 \SpecialChar ~
15625 sjmp 00101$
15626 \layout Standard
15627
15628
15629 \size footnotesize
15630 ; _whilebreak_0($3) :
15631 \layout Standard
15632
15633
15634 \size footnotesize
15635 00103$:
15636 \layout Standard
15637
15638
15639 \size footnotesize
15640 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
15641 \layout Standard
15642
15643
15644 \size footnotesize
15645 \SpecialChar ~
15646 \SpecialChar ~
15647 mov r2,#0x00
15648 \layout Standard
15649
15650
15651 \size footnotesize
15652 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
15653 \layout Standard
15654
15655
15656 \size footnotesize
15657 \SpecialChar ~
15658 \SpecialChar ~
15659 mov r3,#0x00
15660 \layout Standard
15661
15662
15663 \size footnotesize
15664 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
15665 \layout Standard
15666
15667
15668 \size footnotesize
15669 \SpecialChar ~
15670 \SpecialChar ~
15671 mov r4,#0x00
15672 \layout Standard
15673
15674
15675 \size footnotesize
15676 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
15677 \layout Standard
15678
15679
15680 \size footnotesize
15681 \SpecialChar ~
15682 \SpecialChar ~
15683 mov r5,#0x0A
15684 \layout Standard
15685
15686
15687 \size footnotesize
15688 \SpecialChar ~
15689 \SpecialChar ~
15690 mov r6,#0x00
15691 \layout Standard
15692
15693
15694 \size footnotesize
15695 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
15696 \layout Standard
15697
15698
15699 \size footnotesize
15700 \SpecialChar ~
15701 \SpecialChar ~
15702 mov r7,#0x1E
15703 \layout Standard
15704
15705
15706 \size footnotesize
15707 \SpecialChar ~
15708 \SpecialChar ~
15709 mov r0,#0x00
15710 \layout Standard
15711
15712
15713 \size footnotesize
15714 ; _forcond_0($4) :
15715 \layout Standard
15716
15717
15718 \size footnotesize
15719 00104$:
15720 \layout Standard
15721
15722
15723 \size footnotesize
15724 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
15725 \layout Standard
15726
15727
15728 \size footnotesize
15729 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
15730 \layout Standard
15731
15732
15733 \size footnotesize
15734 \SpecialChar ~
15735 \SpecialChar ~
15736 clr c
15737 \layout Standard
15738
15739
15740 \size footnotesize
15741 \SpecialChar ~
15742 \SpecialChar ~
15743 mov a,r4
15744 \layout Standard
15745
15746
15747 \size footnotesize
15748 \SpecialChar ~
15749 \SpecialChar ~
15750 xrl a,#0x80
15751 \layout Standard
15752
15753
15754 \size footnotesize
15755 \SpecialChar ~
15756 \SpecialChar ~
15757 subb a,#0x8a
15758 \layout Standard
15759
15760
15761 \size footnotesize
15762 \SpecialChar ~
15763 \SpecialChar ~
15764 jnc 00107$
15765 \layout Standard
15766
15767
15768 \size footnotesize
15769 00115$:
15770 \layout Standard
15771
15772
15773 \size footnotesize
15774 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
15775 \layout Standard
15776
15777
15778 \size footnotesize
15779 ; iTemp21 [lr21:38]{short}[r4]
15780 \layout Standard
15781
15782
15783 \size footnotesize
15784 \SpecialChar ~
15785 \SpecialChar ~
15786 mov a,r4
15787 \layout Standard
15788
15789
15790 \size footnotesize
15791 \SpecialChar ~
15792 \SpecialChar ~
15793 add a,r2
15794 \layout Standard
15795
15796
15797 \size footnotesize
15798 \SpecialChar ~
15799 \SpecialChar ~
15800 mov r2,a
15801 \layout Standard
15802
15803
15804 \size footnotesize
15805 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
15806 \layout Standard
15807
15808
15809 \size footnotesize
15810 \SpecialChar ~
15811 \SpecialChar ~
15812 mov b,#0x03
15813 \layout Standard
15814
15815
15816 \size footnotesize
15817 \SpecialChar ~
15818 \SpecialChar ~
15819 mov a,r4
15820 \layout Standard
15821
15822
15823 \size footnotesize
15824 \SpecialChar ~
15825 \SpecialChar ~
15826 mul ab
15827 \layout Standard
15828
15829
15830 \size footnotesize
15831 \SpecialChar ~
15832 \SpecialChar ~
15833 mov r1,a
15834 \layout Standard
15835
15836
15837 \size footnotesize
15838 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
15839 \layout Standard
15840
15841
15842 \size footnotesize
15843 ; iTemp15 [lr29:30]{short}[r1]
15844 \layout Standard
15845
15846
15847 \size footnotesize
15848 \SpecialChar ~
15849 \SpecialChar ~
15850 add a,r3
15851 \layout Standard
15852
15853
15854 \size footnotesize
15855 \SpecialChar ~
15856 \SpecialChar ~
15857 mov r3,a
15858 \layout Standard
15859
15860
15861 \size footnotesize
15862 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
15863 \layout Standard
15864
15865
15866 \size footnotesize
15867 \SpecialChar ~
15868 \SpecialChar ~
15869 mov a,r7
15870 \layout Standard
15871
15872
15873 \size footnotesize
15874 \SpecialChar ~
15875 \SpecialChar ~
15876 add a,#0xfd
15877 \layout Standard
15878
15879
15880 \size footnotesize
15881 \SpecialChar ~
15882 \SpecialChar ~
15883 mov r7,a
15884 \layout Standard
15885
15886
15887 \size footnotesize
15888 \SpecialChar ~
15889 \SpecialChar ~
15890 mov a,r0
15891 \layout Standard
15892
15893
15894 \size footnotesize
15895 \SpecialChar ~
15896 \SpecialChar ~
15897 addc a,#0xff
15898 \layout Standard
15899
15900
15901 \size footnotesize
15902 \SpecialChar ~
15903 \SpecialChar ~
15904 mov r0,a
15905 \layout Standard
15906
15907
15908 \size footnotesize
15909 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
15910 \layout Standard
15911
15912
15913 \size footnotesize
15914 \SpecialChar ~
15915 \SpecialChar ~
15916 mov a,r7
15917 \layout Standard
15918
15919
15920 \size footnotesize
15921 \SpecialChar ~
15922 \SpecialChar ~
15923 add a,_gint
15924 \layout Standard
15925
15926
15927 \size footnotesize
15928 \SpecialChar ~
15929 \SpecialChar ~
15930 mov _gint,a
15931 \layout Standard
15932
15933
15934 \size footnotesize
15935 \SpecialChar ~
15936 \SpecialChar ~
15937 mov a,r0
15938 \layout Standard
15939
15940
15941 \size footnotesize
15942 \SpecialChar ~
15943 \SpecialChar ~
15944 addc a,(_gint + 1)
15945 \layout Standard
15946
15947
15948 \size footnotesize
15949 \SpecialChar ~
15950 \SpecialChar ~
15951 mov (_gint + 1),a
15952 \layout Standard
15953
15954
15955 \size footnotesize
15956 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
15957 \layout Standard
15958
15959
15960 \size footnotesize
15961 \SpecialChar ~
15962 \SpecialChar ~
15963 inc r4
15964 \layout Standard
15965
15966
15967 \size footnotesize
15968 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
15969 \layout Standard
15970
15971
15972 \size footnotesize
15973 \SpecialChar ~
15974 \SpecialChar ~
15975 dec r5
15976 \layout Standard
15977
15978
15979 \size footnotesize
15980 \SpecialChar ~
15981 \SpecialChar ~
15982 cjne r5,#0xff,00104$
15983 \layout Standard
15984
15985
15986 \size footnotesize
15987 \SpecialChar ~
15988 \SpecialChar ~
15989 dec r6
15990 \layout Standard
15991
15992
15993 \size footnotesize
15994 ; goto _forcond_0($4)
15995 \layout Standard
15996
15997
15998 \size footnotesize
15999 \SpecialChar ~
16000 \SpecialChar ~
16001 sjmp 00104$
16002 \layout Standard
16003
16004
16005 \size footnotesize
16006 ; _forbreak_0($7) :
16007 \layout Standard
16008
16009
16010 \size footnotesize
16011 00107$:
16012 \layout Standard
16013
16014
16015 \size footnotesize
16016 ; ret iTemp24 [lr40:41]{short}
16017 \layout Standard
16018
16019
16020 \size footnotesize
16021 \SpecialChar ~
16022 \SpecialChar ~
16023 mov a,r3
16024 \layout Standard
16025
16026
16027 \size footnotesize
16028 \SpecialChar ~
16029 \SpecialChar ~
16030 add a,r2
16031 \layout Standard
16032
16033
16034 \size footnotesize
16035 \SpecialChar ~
16036 \SpecialChar ~
16037 mov dpl,a
16038 \layout Standard
16039
16040
16041 \size footnotesize
16042 ; _return($8) :
16043 \layout Standard
16044
16045
16046 \size footnotesize
16047 00108$:
16048 \layout Standard
16049
16050
16051 \size footnotesize
16052 \SpecialChar ~
16053 \SpecialChar ~
16054 ret
16055 \newline
16056
16057 \layout Subsection
16058
16059 A few words about basic block successors, predecessors and dominators
16060 \layout Standard
16061
16062 Successors are basic blocks
16063 \begin_inset LatexCommand \index{Basic blocks}
16064
16065 \end_inset
16066
16067  that might execute after this basic block.
16068 \newline
16069 Predecessors are basic blocks that might execute before reaching this basic
16070  block.
16071 \newline
16072 Dominators are basic blocks that WILL execute before reaching this basic
16073  block.
16074 \newline
16075
16076 \layout Standard
16077
16078 [basic block 1]
16079 \layout Standard
16080
16081 if (something)
16082 \layout Standard
16083
16084 [basic block 2]
16085 \layout Standard
16086
16087 else
16088 \layout Standard
16089
16090 [basic block 3]
16091 \layout Standard
16092
16093 [basic block 4]
16094 \newline
16095
16096 \layout Standard
16097
16098 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
16099 \layout Standard
16100
16101 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
16102 \layout Standard
16103
16104 c) domVect of [BB4] = BB1 ...
16105  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
16106  was executed.
16107 \layout Section
16108
16109 Acknowledgments
16110 \layout Standard
16111
16112
16113 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
16114
16115 \end_inset
16116
16117
16118 \newline
16119
16120 \newline
16121
16122 \emph on
16123 Thanks to all the other volunteer developers who have helped with coding,
16124  testing, web-page creation, distribution sets, etc.
16125  You know who you are :-)
16126 \emph default
16127
16128 \newline
16129
16130 \layout Standard
16131
16132 This document was initially written by Sandeep Dutta
16133 \layout Standard
16134
16135 All product names mentioned herein may be trademarks
16136 \begin_inset LatexCommand \index{Trademarks}
16137
16138 \end_inset
16139
16140  of their respective companies.
16141
16142 \layout Section
16143
16144 Alphabetical index
16145 \layout Standard
16146
16147 To avoid confusion, the installation and building options for sdcc itself
16148  (chapter 2) are not part of the index.
16149 \layout Standard
16150
16151
16152 \begin_inset LatexCommand \printindex{}
16153
16154 \end_inset
16155
16156
16157 \the_end