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