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