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