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