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 book
   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, HC08, manual, mcs51, PIC, 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 Date
  76
  77
  78 \size normal
  79 2.3.6
  80 \size footnotesize
  81
  82 \newline
  83 $Date$
  84 \newline
  85 $Revision$
  86 \layout Comment
  87
  88 The above strings enclosed in $ are automatically updated by cvs
  89 \layout Standard
  90
  91
  92 \begin_inset LatexCommand \tableofcontents{}
  93
  94 \end_inset
  95
  96
  97 \layout Chapter
  98
  99 Introduction
 100 \layout Section
 101
 102 About SDCC
 103 \layout Standard
 104
 105
 106 \series bold
 107 SDCC
 108 \series default
 109  is a Freeware, retargettable, optimizing ANSI-C compiler by
 110 \series bold
 111 Sandeep Dutta
 112 \series default
 113  designed for 8 bit Microprocessors.
 114  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 115  8051, 8052
 116 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 117
 118 \end_inset
 119
 120 , etc.), Dallas DS80C390 variants, Motorola HC08 and Zilog Z80 based MCUs.
 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 Section
 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 Section
 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 Section
 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 Section
 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 Section
 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 Section
 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 Chapter
 491
 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 Section
 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 Section
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 Section
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 Section
2791
2792 Building SDCC
2793 \begin_inset LatexCommand \index{Building SDCC}
2794
2795 \end_inset
2796
2797
2798 \layout Subsection
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 Subsection
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 Subsection
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 Subsection
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 Subsection
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 Subsection
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 Subsection
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 Subsection
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 Section
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.knoppix.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 Section
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 Section
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 Section
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 Subsection
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 Subsection
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 Subsection
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 Subsection
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 Section
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 Subsection
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 Subsection
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 Subsection
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 Subsection
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 Subsection
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 Chapter
3988
3989 Using SDCC
3990 \layout Section
3991
3992 Compiling
3993 \layout Subsection
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{<file>.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{<file>.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{<file>.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{<file>.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{<file>.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{<file>.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{<file>.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{<file>.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{<file>.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{<file> (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{<file>.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 Subsection
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 Subsection
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 Section
4466
4467 Command Line Options
4468 \begin_inset LatexCommand \index{Command Line Options}
4469
4470 \end_inset
4471
4472
4473 \layout Subsection
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{gbz80 (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 Subsection
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 List
4888 \labelwidthstring 00.00.0000
4889
4890
4891 \series bold
4892 -Wp\SpecialChar ~
4893 preprocessorOption[,preprocessorOption]
4894 \series default
4895
4896 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
4897
4898 \end_inset
4899
4900 ...
4901  Pass the preprocessorOption to the preprocessor.
4902 \layout Subsection
4903
4904 Linker Options
4905 \begin_inset LatexCommand \index{Options linker}
4906
4907 \end_inset
4908
4909
4910 \begin_inset LatexCommand \index{Linker options}
4911
4912 \end_inset
4913
4914
4915 \layout List
4916 \labelwidthstring 00.00.0000
4917
4918
4919 \series bold
4920 -L\SpecialChar ~
4921 -
4922 \series default
4923
4924 \begin_inset ERT
4925 status Collapsed
4926
4927 \layout Standard
4928
4929 \backslash
4930 /
4931 \end_inset
4932
4933
4934 \series bold
4935 -lib-path
4936 \begin_inset LatexCommand \index{-\/-lib-path <path>}
4937
4938 \end_inset
4939
4940
4941 \begin_inset LatexCommand \index{-L -\/-lib-path}
4942
4943 \end_inset
4944
4945
4946 \series default
4947 \SpecialChar ~
4948 <absolute path to additional libraries> This option is passed to the linkage
4949  editor's additional libraries
4950 \begin_inset LatexCommand \index{Libraries}
4951
4952 \end_inset
4953
4954  search path.
4955  The path name must be absolute.
4956  Additional library files may be specified in the command line.
4957  See section Compiling programs for more details.
4958 \layout List
4959 \labelwidthstring 00.00.0000
4960
4961
4962 \series bold
4963 -
4964 \begin_inset ERT
4965 status Collapsed
4966
4967 \layout Standard
4968
4969 \backslash
4970 /
4971 \end_inset
4972
4973 -xram-loc
4974 \series default
4975
4976 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
4977
4978 \end_inset
4979
4980 \SpecialChar ~
4981 <Value> The start location of the external ram
4982 \begin_inset LatexCommand \index{xdata}
4983
4984 \end_inset
4985
4986 , default value is 0.
4987  The value entered can be in Hexadecimal or Decimal format, e.g.: -
4988 \begin_inset ERT
4989 status Collapsed
4990
4991 \layout Standard
4992
4993 \backslash
4994 /
4995 \end_inset
4996
4997 -xram-loc 0x8000 or -
4998 \begin_inset ERT
4999 status Collapsed
5000
5001 \layout Standard
5002
5003 \backslash
5004 /
5005 \end_inset
5006
5007 -xram-loc 32768.
5008 \layout List
5009 \labelwidthstring 00.00.0000
5010
5011
5012 \series bold
5013 -
5014 \begin_inset ERT
5015 status Collapsed
5016
5017 \layout Standard
5018
5019 \backslash
5020 /
5021 \end_inset
5022
5023 -code-loc
5024 \series default
5025
5026 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5027
5028 \end_inset
5029
5030 \SpecialChar ~
5031 <Value> The start location of the code
5032 \begin_inset LatexCommand \index{code}
5033
5034 \end_inset
5035
5036  segment, default value 0.
5037  Note when this option is used the interrupt vector table is also relocated
5038  to the given address.
5039  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5040 \begin_inset ERT
5041 status Collapsed
5042
5043 \layout Standard
5044
5045 \backslash
5046 /
5047 \end_inset
5048
5049 -code-loc 0x8000 or -
5050 \begin_inset ERT
5051 status Collapsed
5052
5053 \layout Standard
5054
5055 \backslash
5056 /
5057 \end_inset
5058
5059 -code-loc 32768.
5060 \layout List
5061 \labelwidthstring 00.00.0000
5062
5063
5064 \series bold
5065 -
5066 \begin_inset ERT
5067 status Collapsed
5068
5069 \layout Standard
5070
5071 \backslash
5072 /
5073 \end_inset
5074
5075 -stack-loc
5076 \series default
5077
5078 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5079
5080 \end_inset
5081
5082 \SpecialChar ~
5083 <Value> By default the stack
5084 \begin_inset LatexCommand \index{stack}
5085
5086 \end_inset
5087
5088  is placed after the data segment.
5089  Using this option the stack can be placed anywhere in the internal memory
5090  space of the 8051.
5091  The value entered can be in Hexadecimal or Decimal format, e.g.
5092  -
5093 \begin_inset ERT
5094 status Collapsed
5095
5096 \layout Standard
5097
5098 \backslash
5099 /
5100 \end_inset
5101
5102 -stack-loc 0x20 or -
5103 \begin_inset ERT
5104 status Collapsed
5105
5106 \layout Standard
5107
5108 \backslash
5109 /
5110 \end_inset
5111
5112 -stack-loc 32.
5113  Since the sp register is incremented before a push or call, the initial
5114  sp will be set to one byte prior the provided value.
5115  The provided value should not overlap any other memory areas such as used
5116  register banks or the data segment and with enough space for the current
5117  application.
5118 \layout List
5119 \labelwidthstring 00.00.0000
5120
5121
5122 \series bold
5123 -
5124 \begin_inset ERT
5125 status Collapsed
5126
5127 \layout Standard
5128
5129 \backslash
5130 /
5131 \end_inset
5132
5133 -data-loc
5134 \series default
5135
5136 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5137
5138 \end_inset
5139
5140 \SpecialChar ~
5141 <Value> The start location of the internal ram data
5142 \begin_inset LatexCommand \index{data}
5143
5144 \end_inset
5145
5146  segment.
5147  The value entered can be in Hexadecimal or Decimal format, eg.
5148  -
5149 \begin_inset ERT
5150 status Collapsed
5151
5152 \layout Standard
5153
5154 \backslash
5155 /
5156 \end_inset
5157
5158 -data-loc 0x20 or -
5159 \begin_inset ERT
5160 status Collapsed
5161
5162 \layout Standard
5163
5164 \backslash
5165 /
5166 \end_inset
5167
5168 -data-loc 32.
5169  (By default, the start location of the internal ram data segment  is set
5170  as low as possible in memory, taking into account the used register banks
5171  and the bit segment at address 0x20.
5172  For example if register banks 0 and 1 are used without bit variables, the
5173  data segment will be set, if -
5174 \begin_inset ERT
5175 status Collapsed
5176
5177 \layout Standard
5178
5179 \backslash
5180 /
5181 \end_inset
5182
5183 -data-loc is not used, to location 0x10.)
5184 \layout List
5185 \labelwidthstring 00.00.0000
5186
5187
5188 \series bold
5189 -
5190 \begin_inset ERT
5191 status Collapsed
5192
5193 \layout Standard
5194
5195 \backslash
5196 /
5197 \end_inset
5198
5199 -idata-loc
5200 \series default
5201
5202 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5203
5204 \end_inset
5205
5206 \SpecialChar ~
5207 <Value> The start location of the indirectly addressable internal ram
5208 \begin_inset LatexCommand \index{idata}
5209
5210 \end_inset
5211
5212  of the 8051, default value is 0x80.
5213  The value entered can be in Hexadecimal or Decimal format, eg.
5214  -
5215 \begin_inset ERT
5216 status Collapsed
5217
5218 \layout Standard
5219
5220 \backslash
5221 /
5222 \end_inset
5223
5224 -idata-loc 0x88 or -
5225 \begin_inset ERT
5226 status Collapsed
5227
5228 \layout Standard
5229
5230 \backslash
5231 /
5232 \end_inset
5233
5234 -idata-loc 136.
5235 \layout List
5236 \labelwidthstring 00.00.0000
5237
5238
5239 \series bold
5240 -
5241 \begin_inset ERT
5242 status Collapsed
5243
5244 \layout Standard
5245
5246 \backslash
5247 /
5248 \end_inset
5249
5250 -bit-loc
5251 \series default
5252 \SpecialChar ~
5253 <Value> The start location of the bit
5254 \begin_inset LatexCommand \index{bit}
5255
5256 \end_inset
5257
5258  addressable internal ram of the 8051.
5259  This is
5260 \emph on
5261 not
5262 \emph default
5263  implemented yet.
5264  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5265 -bBSEG=<Value>.
5266 \layout List
5267 \labelwidthstring 00.00.0000
5268
5269
5270 \series bold
5271 -
5272 \begin_inset ERT
5273 status Collapsed
5274
5275 \layout Standard
5276
5277 \backslash
5278 /
5279 \end_inset
5280
5281 -out-fmt-ihx
5282 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5283
5284 \end_inset
5285
5286
5287 \bar under
5288
5289 \series default
5290 \bar default
5291 The linker output (final object code) is in Intel Hex format.
5292 \begin_inset LatexCommand \index{Intel hex format}
5293
5294 \end_inset
5295
5296  (This is the default option).
5297 \layout List
5298 \labelwidthstring 00.00.0000
5299
5300
5301 \series bold
5302 -
5303 \begin_inset ERT
5304 status Collapsed
5305
5306 \layout Standard
5307
5308 \backslash
5309 /
5310 \end_inset
5311
5312 -out-fmt-s19
5313 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5314
5315 \end_inset
5316
5317
5318 \bar under
5319
5320 \series default
5321 \bar default
5322 The linker output (final object code) is in Motorola S19 format
5323 \begin_inset LatexCommand \index{Motorola S19 format}
5324
5325 \end_inset
5326
5327 .
5328 \layout List
5329 \labelwidthstring 00.00.0000
5330
5331
5332 \series bold
5333 -Wl\SpecialChar ~
5334 linkOption[,linkOption]
5335 \series default
5336
5337 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5338
5339 \end_inset
5340
5341 ...
5342  Pass the linkOption to the linker.
5343 \layout Subsection
5344
5345 MCS51 Options
5346 \begin_inset LatexCommand \index{Options MCS51}
5347
5348 \end_inset
5349
5350
5351 \begin_inset LatexCommand \index{MCS51 options}
5352
5353 \end_inset
5354
5355
5356 \layout List
5357 \labelwidthstring 00.00.0000
5358
5359
5360 \series bold
5361 -
5362 \begin_inset ERT
5363 status Collapsed
5364
5365 \layout Standard
5366
5367 \backslash
5368 /
5369 \end_inset
5370
5371 -model-small
5372 \begin_inset LatexCommand \index{-\/-model-small}
5373
5374 \end_inset
5375
5376
5377 \series default
5378 \size large
5379 \emph on
5380
5381 \size default
5382 \emph default
5383 Generate code for Small Model programs see section Memory Models for more
5384  details.
5385  This is the default model.
5386 \layout List
5387 \labelwidthstring 00.00.0000
5388
5389
5390 \series bold
5391 -
5392 \begin_inset ERT
5393 status Collapsed
5394
5395 \layout Standard
5396
5397 \backslash
5398 /
5399 \end_inset
5400
5401 -model-large
5402 \begin_inset LatexCommand \index{-\/-model-large}
5403
5404 \end_inset
5405
5406
5407 \series default
5408  Generate code for Large model programs see section Memory Models for more
5409  details.
5410  If this option is used all source files in the project have to be compiled
5411  with this option.
5412 \layout List
5413 \labelwidthstring 00.00.0000
5414
5415
5416 \series bold
5417 -
5418 \begin_inset ERT
5419 status Collapsed
5420
5421 \layout Standard
5422
5423 \backslash
5424 /
5425 \end_inset
5426
5427 -xstack
5428 \begin_inset LatexCommand \index{-\/-xstack}
5429
5430 \end_inset
5431
5432
5433 \series default
5434  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5435  variables and passing parameters.
5436  See section
5437 \begin_inset LatexCommand \ref{sub:External-Stack}
5438
5439 \end_inset
5440
5441 \SpecialChar ~
5442  External Stack for more details.
5443 \layout List
5444 \labelwidthstring 00.00.0000
5445
5446
5447 \series bold
5448 -
5449 \begin_inset ERT
5450 status Collapsed
5451
5452 \layout Standard
5453
5454 \backslash
5455 /
5456 \end_inset
5457
5458 -iram-size
5459 \series default
5460 \SpecialChar ~
5461 <Value>
5462 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
5463
5464 \end_inset
5465
5466  Causes the linker to check if the internal ram usage is within limits of
5467  the given value.
5468 \layout List
5469 \labelwidthstring 00.00.0000
5470
5471
5472 \series bold
5473 -
5474 \begin_inset ERT
5475 status Collapsed
5476
5477 \layout Standard
5478
5479 \backslash
5480 /
5481 \end_inset
5482
5483 -xram-size
5484 \series default
5485 \SpecialChar ~
5486 <Value>
5487 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
5488
5489 \end_inset
5490
5491  Causes the linker to check if the external ram usage is within limits of
5492  the given value.
5493 \layout List
5494 \labelwidthstring 00.00.0000
5495
5496
5497 \series bold
5498 -
5499 \begin_inset ERT
5500 status Collapsed
5501
5502 \layout Standard
5503
5504 \backslash
5505 /
5506 \end_inset
5507
5508 -code-size
5509 \series default
5510 \SpecialChar ~
5511 <Value>
5512 \begin_inset LatexCommand \index{-\/-code-size <Value>}
5513
5514 \end_inset
5515
5516  Causes the linker to check if the code memory usage is within limits of
5517  the given value.
5518 \layout Subsection
5519
5520 DS390 Options
5521 \begin_inset LatexCommand \index{Options DS390}
5522
5523 \end_inset
5524
5525
5526 \begin_inset LatexCommand \index{DS390 options}
5527
5528 \end_inset
5529
5530
5531 \layout List
5532 \labelwidthstring 00.00.0000
5533
5534
5535 \series bold
5536 -
5537 \begin_inset ERT
5538 status Collapsed
5539
5540 \layout Standard
5541
5542 \backslash
5543 /
5544 \end_inset
5545
5546 -model-flat24
5547 \series default
5548
5549 \begin_inset LatexCommand \index{-\/-model-flat24}
5550
5551 \end_inset
5552
5553
5554 \size large
5555 \emph on
5556
5557 \size default
5558 \emph default
5559 Generate 24-bit flat mode code.
5560  This is the one and only that the ds390 code generator supports right now
5561  and is default when using
5562 \emph on
5563 -mds390
5564 \emph default
5565 .
5566  See section Memory Models for more details.
5567 \layout List
5568 \labelwidthstring 00.00.0000
5569
5570
5571 \series bold
5572 -
5573 \begin_inset ERT
5574 status Collapsed
5575
5576 \layout Standard
5577
5578 \backslash
5579 /
5580 \end_inset
5581
5582 -protect-sp-update
5583 \begin_inset LatexCommand \index{-\/-protect-sp-update}
5584
5585 \end_inset
5586
5587
5588 \series default
5589  disable interrupts during ESP:SP updates
5590 \layout List
5591 \labelwidthstring 00.00.0000
5592
5593
5594 \series bold
5595 -
5596 \begin_inset ERT
5597 status Collapsed
5598
5599 \layout Standard
5600
5601 \backslash
5602 /
5603 \end_inset
5604
5605 -stack-10bit
5606 \series default
5607
5608 \begin_inset LatexCommand \index{-\/-stack-10bit}
5609
5610 \end_inset
5611
5612  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
5613  This is the one and only that the ds390 code generator supports right now
5614  and is default when using
5615 \emph on
5616 -mds390
5617 \emph default
5618 .
5619  In this mode, the stack is located in the lower 1K of the internal RAM,
5620  which is mapped to 0x400000.
5621  Note that the support is incomplete, since it still uses a single byte
5622  as the stack pointer.
5623  This means that only the lower 256 bytes of the potential 1K stack space
5624  will actually be used.
5625  However, this does allow you to reclaim the precious 256 bytes of low RAM
5626  for use for the DATA and IDATA segments.
5627  The compiler will not generate any code to put the processor into 10 bit
5628  stack mode.
5629  It is important to ensure that the processor is in this mode before calling
5630  any re-entrant functions compiled with this option.
5631  In principle, this should work with the
5632 \emph on
5633 -
5634 \begin_inset ERT
5635 status Collapsed
5636
5637 \layout Standard
5638
5639 \backslash
5640 /
5641 \end_inset
5642
5643 -stack-auto
5644 \begin_inset LatexCommand \index{-\/-stack-auto}
5645
5646 \end_inset
5647
5648
5649 \emph default
5650  option, but that has not been tested.
5651  It is incompatible with the
5652 \emph on
5653 -
5654 \begin_inset ERT
5655 status Collapsed
5656
5657 \layout Standard
5658
5659 \backslash
5660 /
5661 \end_inset
5662
5663 -xstack
5664 \begin_inset LatexCommand \index{-\/-xstack}
5665
5666 \end_inset
5667
5668
5669 \emph default
5670  option.
5671  It also only makes sense if the processor is in 24 bit contiguous addressing
5672  mode (see the
5673 \emph on
5674 -
5675 \begin_inset ERT
5676 status Collapsed
5677
5678 \layout Standard
5679
5680 \backslash
5681 /
5682 \end_inset
5683
5684 -model-flat24 option
5685 \emph default
5686 ).
5687 \layout List
5688 \labelwidthstring 00.00.0000
5689
5690
5691 \series bold
5692 -
5693 \begin_inset ERT
5694 status Collapsed
5695
5696 \layout Standard
5697
5698 \backslash
5699 /
5700 \end_inset
5701
5702 -stack-probe
5703 \begin_inset LatexCommand \index{-\/-stack-probe}
5704
5705 \end_inset
5706
5707
5708 \series default
5709  insert call to function __stack_probe at each function prologue
5710 \layout List
5711 \labelwidthstring 00.00.0000
5712
5713
5714 \series bold
5715 -
5716 \begin_inset ERT
5717 status Collapsed
5718
5719 \layout Standard
5720
5721 \backslash
5722 /
5723 \end_inset
5724
5725 -tini-libid
5726 \begin_inset LatexCommand \index{-\/-tini-libid}
5727
5728 \end_inset
5729
5730
5731 \series default
5732  <nnnn> LibraryID used in -mTININative
5733 \layout List
5734 \labelwidthstring 00.00.0000
5735
5736
5737 \series bold
5738 -
5739 \begin_inset ERT
5740 status Collapsed
5741
5742 \layout Standard
5743
5744 \backslash
5745 /
5746 \end_inset
5747
5748 -use-accelerator
5749 \begin_inset LatexCommand \index{-\/-use-accelerator}
5750
5751 \end_inset
5752
5753
5754 \series default
5755  generate code for DS390 Arithmetic Accelerator
5756 \layout Subsection
5757
5758 Z80 Options
5759 \begin_inset LatexCommand \index{Options Z80}
5760
5761 \end_inset
5762
5763
5764 \begin_inset LatexCommand \index{Z80 options}
5765
5766 \end_inset
5767
5768
5769 \layout List
5770 \labelwidthstring 00.00.0000
5771
5772
5773 \series bold
5774 -
5775 \begin_inset ERT
5776 status Collapsed
5777
5778 \layout Standard
5779
5780 \backslash
5781 /
5782 \end_inset
5783
5784 -callee-saves-bc
5785 \series default
5786
5787 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
5788
5789 \end_inset
5790
5791
5792 \size large
5793 \emph on
5794
5795 \size default
5796 \emph default
5797 Force a called function to always save BC.
5798 \layout List
5799 \labelwidthstring 00.00.0000
5800
5801
5802 \series bold
5803 -
5804 \begin_inset ERT
5805 status Collapsed
5806
5807 \layout Standard
5808
5809 \backslash
5810 /
5811 \end_inset
5812
5813 -no-std-crt0
5814 \series default
5815
5816 \begin_inset LatexCommand \index{-\/-no-std-crt0}
5817
5818 \end_inset
5819
5820  When linking, skip the standard crt0.o object file.
5821  You must provide your own crt0.o for your system when linking.
5822
5823 \layout Subsection
5824
5825 Optimization Options
5826 \begin_inset LatexCommand \index{Options optimization}
5827
5828 \end_inset
5829
5830
5831 \begin_inset LatexCommand \index{Optimization options}
5832
5833 \end_inset
5834
5835
5836 \layout List
5837 \labelwidthstring 00.00.0000
5838
5839
5840 \series bold
5841 -
5842 \begin_inset ERT
5843 status Collapsed
5844
5845 \layout Standard
5846
5847 \backslash
5848 /
5849 \end_inset
5850
5851 -nogcse
5852 \begin_inset LatexCommand \index{-\/-nogcse}
5853
5854 \end_inset
5855
5856
5857 \series default
5858  Will not do global subexpression elimination, this option may be used when
5859  the compiler creates undesirably large stack/data spaces to store compiler
5860  temporaries.
5861  A warning message will be generated when this happens and the compiler
5862  will indicate the number of extra bytes it allocated.
5863  It recommended that this option NOT be used, #pragma\SpecialChar ~
5864 NOGCSE
5865 \begin_inset LatexCommand \index{\#pragma NOGCSE}
5866
5867 \end_inset
5868
5869  can be used to turn off global subexpression elimination
5870 \begin_inset LatexCommand \index{Subexpression elimination}
5871
5872 \end_inset
5873
5874  for a given function only.
5875 \layout List
5876 \labelwidthstring 00.00.0000
5877
5878
5879 \series bold
5880 -
5881 \begin_inset ERT
5882 status Collapsed
5883
5884 \layout Standard
5885
5886 \backslash
5887 /
5888 \end_inset
5889
5890 -noinvariant
5891 \begin_inset LatexCommand \index{-\/-noinvariant}
5892
5893 \end_inset
5894
5895
5896 \series default
5897  Will not do loop invariant optimizations, this may be turned off for reasons
5898  explained for the previous option.
5899  For more details of loop optimizations performed see section Loop Invariants.It
5900  recommended that this option NOT be used, #pragma\SpecialChar ~
5901 NOINVARIANT
5902 \begin_inset LatexCommand \index{\#pragma NOINVARIANT}
5903
5904 \end_inset
5905
5906  can be used to turn off invariant optimizations for a given function only.
5907 \layout List
5908 \labelwidthstring 00.00.0000
5909
5910
5911 \series bold
5912 -
5913 \begin_inset ERT
5914 status Collapsed
5915
5916 \layout Standard
5917
5918 \backslash
5919 /
5920 \end_inset
5921
5922 -noinduction
5923 \begin_inset LatexCommand \index{-\/-noinduction}
5924
5925 \end_inset
5926
5927
5928 \series default
5929  Will not do loop induction optimizations, see section strength reduction
5930  for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
5931 NOINDUCT
5932 ION
5933 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
5934
5935 \end_inset
5936
5937  can be used to turn off induction optimizations for a given function only.
5938 \layout List
5939 \labelwidthstring 00.00.0000
5940
5941
5942 \series bold
5943 -
5944 \begin_inset ERT
5945 status Collapsed
5946
5947 \layout Standard
5948
5949 \backslash
5950 /
5951 \end_inset
5952
5953 -nojtbound
5954 \begin_inset LatexCommand \index{-\/-nojtbound}
5955
5956 \end_inset
5957
5958
5959 \size large
5960 \bar under
5961
5962 \series default
5963 \size default
5964 \bar default
5965  Will not generate boundary condition check when switch statements
5966 \begin_inset LatexCommand \index{switch statement}
5967
5968 \end_inset
5969
5970  are implemented using jump-tables.
5971  See section
5972 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
5973
5974 \end_inset
5975
5976 \SpecialChar ~
5977 Switch Statements for more details.
5978  It is recommended that this option is NOT used, #pragma\SpecialChar ~
5979 NOJTBOUND
5980 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
5981
5982 \end_inset
5983
5984  can be used to turn off boundary checking for jump tables for a given function
5985  only.
5986 \layout List
5987 \labelwidthstring 00.00.0000
5988
5989
5990 \series bold
5991 -
5992 \begin_inset ERT
5993 status Collapsed
5994
5995 \layout Standard
5996
5997 \backslash
5998 /
5999 \end_inset
6000
6001 -noloopreverse
6002 \begin_inset LatexCommand \index{-\/-noloopreverse}
6003
6004 \end_inset
6005
6006
6007 \series default
6008 \size large
6009
6010 \size default
6011 Will not do loop reversal
6012 \begin_inset LatexCommand \index{Loop reversing}
6013
6014 \end_inset
6015
6016 optimization.
6017 \layout List
6018 \labelwidthstring 00.00.0000
6019
6020 -
6021 \begin_inset ERT
6022 status Collapsed
6023
6024 \layout Standard
6025
6026 \backslash
6027 /
6028 \end_inset
6029
6030 -
6031 \series bold
6032 nolabelopt
6033 \series default
6034
6035 \begin_inset LatexCommand \index{-\/-nolabelopt }
6036
6037 \end_inset
6038
6039 Will not optimize labels (makes the dumpfiles more readable).
6040 \layout List
6041 \labelwidthstring 00.00.0000
6042
6043
6044 \series bold
6045 -
6046 \begin_inset ERT
6047 status Collapsed
6048
6049 \layout Standard
6050
6051 \backslash
6052 /
6053 \end_inset
6054
6055 -no-xinit-opt
6056 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6057
6058 \end_inset
6059
6060
6061 \series default
6062  Will not memcpy initialized data from code space into xdata space.
6063  This saves a few bytes in code space if you don't have initialized data.
6064 \layout Subsection
6065
6066 Other Options
6067 \begin_inset LatexCommand \index{Options other}
6068
6069 \end_inset
6070
6071
6072 \layout List
6073 \labelwidthstring 00.00.0000
6074
6075
6076 \series bold
6077 -c\SpecialChar ~
6078 -
6079 \begin_inset ERT
6080 status Collapsed
6081
6082 \layout Standard
6083
6084 \backslash
6085 /
6086 \end_inset
6087
6088 -compile-only
6089 \begin_inset LatexCommand \index{-\/-compile-only}
6090
6091 \end_inset
6092
6093
6094 \begin_inset LatexCommand \index{-c -\/-compile-only}
6095
6096 \end_inset
6097
6098
6099 \series default
6100  will compile and assemble the source, but will not call the linkage editor.
6101 \layout List
6102 \labelwidthstring 00.00.0000
6103
6104
6105 \series bold
6106 -
6107 \series default
6108
6109 \begin_inset ERT
6110 status Collapsed
6111
6112 \layout Standard
6113
6114 \backslash
6115 /
6116 \end_inset
6117
6118
6119 \series bold
6120 -c1mode
6121 \begin_inset LatexCommand \index{-\/-c1mode}
6122
6123 \end_inset
6124
6125
6126 \series default
6127  reads the preprocessed source from standard input and compiles it.
6128  The file name for the assembler output must be specified using the -o option.
6129 \layout List
6130 \labelwidthstring 00.00.0000
6131
6132
6133 \series bold
6134 -E
6135 \begin_inset LatexCommand \index{-E}
6136
6137 \end_inset
6138
6139
6140 \series default
6141  Run only the C preprocessor.
6142  Preprocess all the C source files specified and output the results to standard
6143  output.
6144 \layout List
6145 \labelwidthstring 00.00.0000
6146
6147
6148 \series bold
6149 -o\SpecialChar ~
6150 <path/file>
6151 \begin_inset LatexCommand \index{-o <path/file>}
6152
6153 \end_inset
6154
6155
6156 \series default
6157 The output path resp.
6158  file where everything will be placed.
6159  If the parameter is a path, it must have a trailing slash (or backslash
6160  for the Windows binaries) to be recognized as a path.
6161
6162 \layout List
6163 \labelwidthstring 00.00.0000
6164
6165
6166 \series bold
6167 -
6168 \begin_inset ERT
6169 status Collapsed
6170
6171 \layout Standard
6172
6173 \backslash
6174 /
6175 \end_inset
6176
6177 -stack-auto
6178 \begin_inset LatexCommand \index{-\/-stack-auto}
6179
6180 \end_inset
6181
6182
6183 \series default
6184 \size large
6185 \emph on
6186
6187 \size default
6188 \emph default
6189 All functions in the source file will be compiled as
6190 \emph on
6191 reentrant
6192 \emph default
6193
6194 \begin_inset LatexCommand \index{reentrant}
6195
6196 \end_inset
6197
6198 , i.e.
6199  the parameters and local variables will be allocated on the stack
6200 \begin_inset LatexCommand \index{stack}
6201
6202 \end_inset
6203
6204 .
6205  see section Parameters and Local Variables for more details.
6206  If this option is used all source files in the project should be compiled
6207  with this option.
6208
6209 \layout List
6210 \labelwidthstring 00.00.0000
6211
6212
6213 \series bold
6214 -
6215 \begin_inset ERT
6216 status Collapsed
6217
6218 \layout Standard
6219
6220 \backslash
6221 /
6222 \end_inset
6223
6224 -callee-saves
6225 \begin_inset LatexCommand \index{-\/-callee-saves}
6226
6227 \end_inset
6228
6229  function1[,function2][,function3]....
6230
6231 \series default
6232  The compiler by default uses a caller saves convention for register saving
6233  across function calls, however this can cause unnecessary register pushing
6234  & popping when calling small functions from larger functions.
6235  This option can be used to switch the register saving convention for the
6236  function names specified.
6237  The compiler will not save registers when calling these functions, no extra
6238  code will be generated at the entry & exit (function prologue
6239 \series bold
6240
6241 \begin_inset LatexCommand \index{function prologue}
6242
6243 \end_inset
6244
6245
6246 \series default
6247  & epilogue
6248 \series bold
6249
6250 \begin_inset LatexCommand \index{function epilogue}
6251
6252 \end_inset
6253
6254
6255 \series default
6256 ) for these functions to save & restore the registers used by these functions,
6257  this can SUBSTANTIALLY reduce code & improve run time performance of the
6258  generated code.
6259  In the future the compiler (with inter procedural analysis) will be able
6260  to determine the appropriate scheme to use for each function call.
6261  DO NOT use this option for built-in functions such as _mulint..., if this
6262  option is used for a library function the appropriate library function
6263  needs to be recompiled with the same option.
6264  If the project consists of multiple source files then all the source file
6265  should be compiled with the same -
6266 \begin_inset ERT
6267 status Collapsed
6268
6269 \layout Standard
6270
6271 \backslash
6272 /
6273 \end_inset
6274
6275 -callee-saves option string.
6276  Also see #pragma\SpecialChar ~
6277 CALLEE-SAVES
6278 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
6279
6280 \end_inset
6281
6282 .
6283 \layout List
6284 \labelwidthstring 00.00.0000
6285
6286
6287 \series bold
6288 -
6289 \begin_inset ERT
6290 status Collapsed
6291
6292 \layout Standard
6293
6294 \backslash
6295 /
6296 \end_inset
6297
6298 -debug
6299 \begin_inset LatexCommand \index{-\/-debug}
6300
6301 \end_inset
6302
6303
6304 \bar under
6305
6306 \series default
6307 \bar default
6308 When this option is used the compiler will generate debug information, that
6309  can be used with the SDCDB.
6310  The debug information is collected in a file with .cdb extension.
6311  For more information see documentation for SDCDB.
6312 \layout List
6313 \labelwidthstring 00.00.0000
6314
6315
6316 \series bold
6317 -S
6318 \begin_inset LatexCommand \index{-S}
6319
6320 \end_inset
6321
6322
6323 \size large
6324 \bar under
6325
6326 \series default
6327 \size default
6328 \bar default
6329 Stop after the stage of compilation proper; do not assemble.
6330  The output is an assembler code file for the input file specified.
6331 \layout List
6332 \labelwidthstring 00.00.0000
6333
6334
6335 \series bold
6336 -
6337 \begin_inset ERT
6338 status Collapsed
6339
6340 \layout Standard
6341
6342 \backslash
6343 /
6344 \end_inset
6345
6346 -int-long-reent
6347 \begin_inset LatexCommand \index{-\/-int-long-reent}
6348
6349 \end_inset
6350
6351
6352 \series default
6353  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
6354  Note by default these libraries are compiled as non-reentrant.
6355  See section Installation for more details.
6356 \layout List
6357 \labelwidthstring 00.00.0000
6358
6359
6360 \series bold
6361 -
6362 \begin_inset ERT
6363 status Collapsed
6364
6365 \layout Standard
6366
6367 \backslash
6368 /
6369 \end_inset
6370
6371 -cyclomatic
6372 \begin_inset LatexCommand \index{-\/-cyclomatic}
6373
6374 \end_inset
6375
6376
6377 \bar under
6378
6379 \series default
6380 \bar default
6381 This option will cause the compiler to generate an information message for
6382  each function in the source file.
6383  The message contains some
6384 \emph on
6385 important
6386 \emph default
6387  information about the function.
6388  The number of edges and nodes the compiler detected in the control flow
6389  graph of the function, and most importantly the
6390 \emph on
6391 cyclomatic complexity
6392 \begin_inset LatexCommand \index{Cyclomatic complexity}
6393
6394 \end_inset
6395
6396
6397 \emph default
6398  see section on Cyclomatic Complexity for more details.
6399 \layout List
6400 \labelwidthstring 00.00.0000
6401
6402
6403 \series bold
6404 -
6405 \begin_inset ERT
6406 status Collapsed
6407
6408 \layout Standard
6409
6410 \backslash
6411 /
6412 \end_inset
6413
6414 -float-reent
6415 \begin_inset LatexCommand \index{-\/-float-reent}
6416
6417 \end_inset
6418
6419
6420 \bar under
6421
6422 \series default
6423 \bar default
6424  Floating point library is compiled as reentrant
6425 \begin_inset LatexCommand \index{reentrant}
6426
6427 \end_inset
6428
6429 .
6430  See section Installation for more details.
6431 \layout List
6432 \labelwidthstring 00.00.0000
6433
6434
6435 \series bold
6436 -
6437 \begin_inset ERT
6438 status Collapsed
6439
6440 \layout Standard
6441
6442 \backslash
6443 /
6444 \end_inset
6445
6446 -nooverlay
6447 \begin_inset LatexCommand \index{-\/-nooverlay}
6448
6449 \end_inset
6450
6451
6452 \series default
6453   The compiler will not overlay parameters and local variables of any function,
6454  see section Parameters and local variables for more details.
6455 \layout List
6456 \labelwidthstring 00.00.0000
6457
6458
6459 \series bold
6460 -
6461 \begin_inset ERT
6462 status Collapsed
6463
6464 \layout Standard
6465
6466 \backslash
6467 /
6468 \end_inset
6469
6470 -main-return
6471 \begin_inset LatexCommand \index{-\/-main-return}
6472
6473 \end_inset
6474
6475
6476 \series default
6477  This option can be used when the code generated is called by a monitor
6478  program.
6479  The compiler will generate a 'ret' upon return from the 'main'
6480 \begin_inset LatexCommand \index{main return}
6481
6482 \end_inset
6483
6484  function.
6485  The default setting is to lock up i.e.
6486  generate a '
6487 \family typewriter
6488 ljmp .
6489 \family default
6490 '.
6491 \layout List
6492 \labelwidthstring 00.00.0000
6493
6494
6495 \series bold
6496 -
6497 \begin_inset ERT
6498 status Collapsed
6499
6500 \layout Standard
6501
6502 \backslash
6503 /
6504 \end_inset
6505
6506 -peep-file
6507 \series default
6508
6509 \begin_inset LatexCommand \index{-\/-peep-file}
6510
6511 \end_inset
6512
6513 \SpecialChar ~
6514 <filename> This option can be used to use additional rules to be used by
6515  the peep hole optimizer.
6516  See section
6517 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6518
6519 \end_inset
6520
6521 \SpecialChar ~
6522 Peep Hole optimizations for details on how to write these rules.
6523 \layout List
6524 \labelwidthstring 00.00.0000
6525
6526
6527 \series bold
6528 -
6529 \begin_inset ERT
6530 status Collapsed
6531
6532 \layout Standard
6533
6534 \backslash
6535 /
6536 \end_inset
6537
6538 -no-peep
6539 \begin_inset LatexCommand \index{-\/-no-peep}
6540
6541 \end_inset
6542
6543
6544 \series default
6545  Disable peep-hole optimization.
6546 \layout List
6547 \labelwidthstring 00.00.0000
6548
6549
6550 \series bold
6551 -
6552 \begin_inset ERT
6553 status Collapsed
6554
6555 \layout Standard
6556
6557 \backslash
6558 /
6559 \end_inset
6560
6561 -peep-asm
6562 \begin_inset LatexCommand \index{-\/-peep-asm}
6563
6564 \end_inset
6565
6566
6567 \series default
6568   Pass the inline assembler code through the peep hole optimizer.
6569  This can cause unexpected changes to inline assembler code, please go through
6570  the peephole optimizer
6571 \begin_inset LatexCommand \index{Peephole optimizer}
6572
6573 \end_inset
6574
6575  rules defined in the source file tree '<target>/peeph.def' before using
6576  this option.
6577 \layout List
6578 \labelwidthstring 00.00.0000
6579
6580
6581 \series bold
6582 -
6583 \begin_inset ERT
6584 status Collapsed
6585
6586 \layout Standard
6587
6588 \backslash
6589 /
6590 \end_inset
6591
6592 -nostdincl
6593 \begin_inset LatexCommand \index{-\/-nostdincl}
6594
6595 \end_inset
6596
6597
6598 \series default
6599  This will prevent the compiler from passing on the default include path
6600  to the preprocessor.
6601 \layout List
6602 \labelwidthstring 00.00.0000
6603
6604
6605 \series bold
6606 -
6607 \begin_inset ERT
6608 status Collapsed
6609
6610 \layout Standard
6611
6612 \backslash
6613 /
6614 \end_inset
6615
6616 -nostdlib
6617 \begin_inset LatexCommand \index{-\/-nostdlib}
6618
6619 \end_inset
6620
6621
6622 \series default
6623  This will prevent the compiler from passing on the default library
6624 \begin_inset LatexCommand \index{Libraries}
6625
6626 \end_inset
6627
6628  path to the linker.
6629 \layout List
6630 \labelwidthstring 00.00.0000
6631
6632
6633 \series bold
6634 -
6635 \begin_inset ERT
6636 status Collapsed
6637
6638 \layout Standard
6639
6640 \backslash
6641 /
6642 \end_inset
6643
6644 -verbose
6645 \begin_inset LatexCommand \index{-\/-verbose}
6646
6647 \end_inset
6648
6649
6650 \series default
6651  Shows the various actions the compiler is performing.
6652 \layout List
6653 \labelwidthstring 00.00.0000
6654
6655
6656 \series bold
6657 -V
6658 \begin_inset LatexCommand \index{-V}
6659
6660 \end_inset
6661
6662
6663 \series default
6664  Shows the actual commands the compiler is executing.
6665 \layout List
6666 \labelwidthstring 00.00.0000
6667
6668
6669 \series bold
6670 -
6671 \begin_inset ERT
6672 status Collapsed
6673
6674 \layout Standard
6675
6676 \backslash
6677 /
6678 \end_inset
6679
6680 -no-c-code-in-asm
6681 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
6682
6683 \end_inset
6684
6685
6686 \series default
6687  Hides your ugly and inefficient c-code from the asm file, so you can always
6688  blame the compiler :).
6689 \layout List
6690 \labelwidthstring 00.00.0000
6691
6692
6693 \series bold
6694 -
6695 \begin_inset ERT
6696 status Collapsed
6697
6698 \layout Standard
6699
6700 \backslash
6701 /
6702 \end_inset
6703
6704 -i-code-in-asm
6705 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
6706
6707 \end_inset
6708
6709
6710 \series default
6711  Include i-codes in the asm file.
6712  Sounds like noise but is most helpful for debugging the compiler itself.
6713 \layout List
6714 \labelwidthstring 00.00.0000
6715
6716
6717 \series bold
6718 -
6719 \begin_inset ERT
6720 status Collapsed
6721
6722 \layout Standard
6723
6724 \backslash
6725 /
6726 \end_inset
6727
6728 -less-pedantic
6729 \begin_inset LatexCommand \index{-\/-less-pedantic}
6730
6731 \end_inset
6732
6733
6734 \series default
6735  Disable some of the more pedantic warnings
6736 \begin_inset LatexCommand \index{Warnings}
6737
6738 \end_inset
6739
6740  (jwk burps: please be more specific here, please!).
6741  If you want rather more than less warnings you should consider using a
6742  separate tool dedicated to syntax checking like
6743 \begin_inset LatexCommand \url{www.splint.org}
6744
6745 \end_inset
6746
6747 .
6748 \layout List
6749 \labelwidthstring 00.00.0000
6750
6751
6752 \series bold
6753 -
6754 \begin_inset ERT
6755 status Collapsed
6756
6757 \layout Standard
6758
6759 \backslash
6760 /
6761 \end_inset
6762
6763 -print-search-dirs
6764 \begin_inset LatexCommand \index{-\/-print-search-dirs}
6765
6766 \end_inset
6767
6768
6769 \series default
6770  Display the directories in the compiler's search path
6771 \layout List
6772 \labelwidthstring 00.00.0000
6773
6774
6775 \series bold
6776 -
6777 \begin_inset ERT
6778 status Collapsed
6779
6780 \layout Standard
6781
6782 \backslash
6783 /
6784 \end_inset
6785
6786 -vc
6787 \begin_inset LatexCommand \index{-\/-vc}
6788
6789 \end_inset
6790
6791
6792 \series default
6793  Display errors and warnings using MSVC style, so you can use SDCC with
6794  visual studio.
6795 \layout List
6796 \labelwidthstring 00.00.0000
6797
6798
6799 \series bold
6800 -
6801 \begin_inset ERT
6802 status Collapsed
6803
6804 \layout Standard
6805
6806 \backslash
6807 /
6808 \end_inset
6809
6810 -use-stdout
6811 \begin_inset LatexCommand \index{-\/-use-stdout}
6812
6813 \end_inset
6814
6815
6816 \series default
6817  Send errors and warnings to stdout instead of stderr.
6818 \layout List
6819 \labelwidthstring 00.00.0000
6820
6821
6822 \series bold
6823 -Wa\SpecialChar ~
6824 asmOption[,asmOption]
6825 \series default
6826
6827 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
6828
6829 \end_inset
6830
6831 ...
6832  Pass the asmOption to the assembler.
6833 \layout Subsection
6834
6835 Intermediate Dump Options
6836 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
6837
6838 \end_inset
6839
6840
6841 \begin_inset LatexCommand \index{Options intermediate dump}
6842
6843 \end_inset
6844
6845
6846 \begin_inset LatexCommand \index{Intermediate dump options}
6847
6848 \end_inset
6849
6850
6851 \layout Standard
6852
6853 The following options are provided for the purpose of retargetting and debugging
6854  the compiler.
6855  These provided a means to dump the intermediate code (iCode
6856 \begin_inset LatexCommand \index{iCode}
6857
6858 \end_inset
6859
6860 ) generated by the compiler in human readable form at various stages of
6861  the compilation process.
6862
6863 \layout List
6864 \labelwidthstring 00.00.0000
6865
6866
6867 \series bold
6868 -
6869 \begin_inset ERT
6870 status Collapsed
6871
6872 \layout Standard
6873
6874 \backslash
6875 /
6876 \end_inset
6877
6878 -dumpraw
6879 \begin_inset LatexCommand \index{-\/-dumpraw}
6880
6881 \end_inset
6882
6883
6884 \series default
6885  This option will cause the compiler to dump the intermediate code into
6886  a file of named
6887 \emph on
6888 <source filename>.dumpraw
6889 \emph default
6890  just after the intermediate code has been generated for a function, i.e.
6891  before any optimizations are done.
6892  The basic blocks
6893 \begin_inset LatexCommand \index{Basic blocks}
6894
6895 \end_inset
6896
6897  at this stage ordered in the depth first number, so they may not be in
6898  sequence of execution.
6899 \layout List
6900 \labelwidthstring 00.00.0000
6901
6902
6903 \series bold
6904 -
6905 \begin_inset ERT
6906 status Collapsed
6907
6908 \layout Standard
6909
6910 \backslash
6911 /
6912 \end_inset
6913
6914 -dumpgcse
6915 \begin_inset LatexCommand \index{-\/-dumpgcse}
6916
6917 \end_inset
6918
6919
6920 \series default
6921  Will create a dump of iCode's, after global subexpression elimination
6922 \begin_inset LatexCommand \index{Global subexpression elimination}
6923
6924 \end_inset
6925
6926 , into a file named
6927 \emph on
6928 <source filename>.dumpgcse.
6929 \layout List
6930 \labelwidthstring 00.00.0000
6931
6932
6933 \series bold
6934 -
6935 \begin_inset ERT
6936 status Collapsed
6937
6938 \layout Standard
6939
6940 \backslash
6941 /
6942 \end_inset
6943
6944 -dumpdeadcode
6945 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
6946
6947 \end_inset
6948
6949
6950 \series default
6951  Will create a dump of iCode's, after deadcode elimination
6952 \begin_inset LatexCommand \index{Dead-code elimination}
6953
6954 \end_inset
6955
6956 , into a file named
6957 \emph on
6958 <source filename>.dumpdeadcode.
6959 \layout List
6960 \labelwidthstring 00.00.0000
6961
6962
6963 \series bold
6964 -
6965 \begin_inset ERT
6966 status Collapsed
6967
6968 \layout Standard
6969
6970 \backslash
6971 /
6972 \end_inset
6973
6974 -dumploop
6975 \begin_inset LatexCommand \index{-\/-dumploop}
6976
6977 \end_inset
6978
6979
6980 \series default
6981 \size large
6982
6983 \size default
6984 Will create a dump of iCode's, after loop optimizations
6985 \begin_inset LatexCommand \index{Loop optimization}
6986
6987 \end_inset
6988
6989 , into a file named
6990 \emph on
6991 <source filename>.dumploop.
6992 \layout List
6993 \labelwidthstring 00.00.0000
6994
6995
6996 \series bold
6997 -
6998 \begin_inset ERT
6999 status Collapsed
7000
7001 \layout Standard
7002
7003 \backslash
7004 /
7005 \end_inset
7006
7007 -dumprange
7008 \begin_inset LatexCommand \index{-\/-dumprange}
7009
7010 \end_inset
7011
7012
7013 \series default
7014 \size large
7015
7016 \size default
7017 Will create a dump of iCode's, after live range analysis
7018 \begin_inset LatexCommand \index{Live range analysis}
7019
7020 \end_inset
7021
7022 , into a file named
7023 \emph on
7024 <source filename>.dumprange.
7025 \layout List
7026 \labelwidthstring 00.00.0000
7027
7028
7029 \series bold
7030 -
7031 \begin_inset ERT
7032 status Collapsed
7033
7034 \layout Standard
7035
7036 \backslash
7037 /
7038 \end_inset
7039
7040 -dumlrange
7041 \begin_inset LatexCommand \index{-\/-dumlrange}
7042
7043 \end_inset
7044
7045
7046 \series default
7047  Will dump the life ranges
7048 \begin_inset LatexCommand \index{Live range analysis}
7049
7050 \end_inset
7051
7052  for all symbols.
7053 \layout List
7054 \labelwidthstring 00.00.0000
7055
7056
7057 \series bold
7058 -
7059 \begin_inset ERT
7060 status Collapsed
7061
7062 \layout Standard
7063
7064 \backslash
7065 /
7066 \end_inset
7067
7068 -dumpregassign
7069 \begin_inset LatexCommand \index{-\/-dumpregassign}
7070
7071 \end_inset
7072
7073
7074 \bar under
7075
7076 \series default
7077 \bar default
7078 Will create a dump of iCode's, after register assignment
7079 \begin_inset LatexCommand \index{Register assignment}
7080
7081 \end_inset
7082
7083 , into a file named
7084 \emph on
7085 <source filename>.dumprassgn.
7086 \layout List
7087 \labelwidthstring 00.00.0000
7088
7089
7090 \series bold
7091 -
7092 \begin_inset ERT
7093 status Collapsed
7094
7095 \layout Standard
7096
7097 \backslash
7098 /
7099 \end_inset
7100
7101 -dumplrange
7102 \begin_inset LatexCommand \index{-\/-dumplrange}
7103
7104 \end_inset
7105
7106
7107 \series default
7108  Will create a dump of the live ranges of iTemp's
7109 \layout List
7110 \labelwidthstring 00.00.0000
7111
7112
7113 \series bold
7114 -
7115 \begin_inset ERT
7116 status Collapsed
7117
7118 \layout Standard
7119
7120 \backslash
7121 /
7122 \end_inset
7123
7124 -dumpall
7125 \begin_inset LatexCommand \index{-\/-dumpall}
7126
7127 \end_inset
7128
7129
7130 \size large
7131 \bar under
7132
7133 \series default
7134 \size default
7135 \bar default
7136 Will cause all the above mentioned dumps to be created.
7137 \layout Subsection
7138
7139 Redirecting output on Windows Shells
7140 \layout Standard
7141
7142 By default SDCC writes it's error messages to
7143 \begin_inset Quotes sld
7144 \end_inset
7145
7146 standard error
7147 \begin_inset Quotes srd
7148 \end_inset
7149
7150 .
7151  To force all messages to
7152 \begin_inset Quotes sld
7153 \end_inset
7154
7155 standard output
7156 \begin_inset Quotes srd
7157 \end_inset
7158
7159  use
7160 \series bold
7161 -
7162 \series default
7163 \emph on
7164
7165 \begin_inset ERT
7166 status Collapsed
7167
7168 \layout Standard
7169
7170 \backslash
7171 /
7172 \end_inset
7173
7174
7175 \series bold
7176 \emph default
7177 -
7178 \series default
7179 use-stdout
7180 \begin_inset LatexCommand \index{-\/-use-stdout}
7181
7182 \end_inset
7183
7184 .
7185  Aditionaly, if you happen to have visual studio installed in your windows
7186  machine, you can use it to compile your sources using a custom build and
7187  the SDCC -
7188 \emph on
7189
7190 \begin_inset ERT
7191 status Collapsed
7192
7193 \layout Standard
7194
7195 \backslash
7196 /
7197 \end_inset
7198
7199
7200 \emph default
7201 -vc
7202 \begin_inset LatexCommand \index{-\/-vc}
7203
7204 \end_inset
7205
7206  option.
7207  Something like this should work:
7208 \newline
7209
7210 \newline
7211
7212 \series bold
7213 c:
7214 \backslash
7215 sdcc
7216 \backslash
7217 bin
7218 \backslash
7219 sdcc.exe -
7220 \series default
7221 \emph on
7222
7223 \begin_inset ERT
7224 status Collapsed
7225
7226 \layout Standard
7227
7228 \backslash
7229 /
7230 \end_inset
7231
7232
7233 \series bold
7234 \emph default
7235 -vc -
7236 \series default
7237 \emph on
7238
7239 \begin_inset ERT
7240 status Collapsed
7241
7242 \layout Standard
7243
7244 \backslash
7245 /
7246 \end_inset
7247
7248
7249 \series bold
7250 \emph default
7251 -model-large -c $(InputPath)
7252 \layout Section
7253
7254 Environment variables
7255 \begin_inset LatexCommand \index{Environment variables}
7256
7257 \end_inset
7258
7259
7260 \layout Standard
7261
7262 SDCC recognizes the following environment variables:
7263 \layout List
7264 \labelwidthstring 00.00.0000
7265
7266
7267 \series bold
7268 SDCC_LEAVE_SIGNALS
7269 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7270
7271 \end_inset
7272
7273
7274 \series default
7275  SDCC installs a signal handler
7276 \begin_inset LatexCommand \index{signal handler}
7277
7278 \end_inset
7279
7280  to be able to delete temporary files after an user break (^C) or an exception.
7281  If this environment variable is set, SDCC won't install the signal handler
7282  in order to be able to debug SDCC.
7283 \layout List
7284 \labelwidthstring 00.00.0000
7285
7286
7287 \series bold
7288 TMP,\SpecialChar ~
7289 TEMP,\SpecialChar ~
7290 TMPDIR
7291 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7292
7293 \end_inset
7294
7295
7296 \series default
7297  Path, where temporary files will be created.
7298  The order of the variables is the search order.
7299  In a standard *nix environment these variables are not set, and there's
7300  no need to set them.
7301  On Windows it's recommended to set one of them.
7302 \layout List
7303 \labelwidthstring 00.00.0000
7304
7305
7306 \series bold
7307 SDCC_HOME
7308 \begin_inset LatexCommand \index{SDCC\_HOME}
7309
7310 \end_inset
7311
7312
7313 \series default
7314  Path, see section
7315 \begin_inset LatexCommand \ref{sub:Install-paths}
7316
7317 \end_inset
7318
7319 \SpecialChar ~
7320
7321 \begin_inset Quotes sld
7322 \end_inset
7323
7324  Install Paths
7325 \begin_inset Quotes srd
7326 \end_inset
7327
7328 .
7329 \layout List
7330 \labelwidthstring 00.00.0000
7331
7332
7333 \series bold
7334 SDCC_INCLUDE
7335 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
7336
7337 \end_inset
7338
7339
7340 \series default
7341  Path, see section
7342 \begin_inset LatexCommand \ref{sub:Search-Paths}
7343
7344 \end_inset
7345
7346 \SpecialChar ~
7347
7348 \begin_inset Quotes sld
7349 \end_inset
7350
7351 Search Paths
7352 \begin_inset Quotes srd
7353 \end_inset
7354
7355 .
7356 \layout List
7357 \labelwidthstring 00.00.0000
7358
7359
7360 \series bold
7361 SDCC_LIB
7362 \begin_inset LatexCommand \index{SDCC\_LIB}
7363
7364 \end_inset
7365
7366
7367 \series default
7368  Path, see section
7369 \begin_inset LatexCommand \ref{sub:Search-Paths}
7370
7371 \end_inset
7372
7373 \SpecialChar ~
7374
7375 \begin_inset Quotes sld
7376 \end_inset
7377
7378 Search Paths
7379 \begin_inset Quotes srd
7380 \end_inset
7381
7382 ..
7383 \layout Standard
7384
7385 There are some more environment variables recognized by SDCC, but these
7386  are solely used for debugging purposes.
7387  They can change or disappear very quickly, and will never be documented.
7388 \layout Section
7389
7390 Storage Class Language Extensions
7391 \layout Subsection
7392
7393 MCS51/DS390 Storage Class
7394 \begin_inset LatexCommand \index{Storage class}
7395
7396 \end_inset
7397
7398  Language Extensions
7399 \layout Standard
7400
7401 In addition to the ANSI storage classes SDCC allows the following MCS51
7402  specific storage classes:
7403 \layout Subsubsection
7404
7405 data
7406 \begin_inset LatexCommand \index{data}
7407
7408 \end_inset
7409
7410
7411 \layout Standard
7412
7413 This is the
7414 \series bold
7415 default
7416 \series default
7417  storage class for the Small Memory model.
7418  Variables declared with this storage class will be allocated in the directly
7419  addressable portion of the internal RAM of a 8051, e.g.:
7420 \layout Verse
7421
7422
7423 \family typewriter
7424 data unsigned char test_data;
7425 \layout Standard
7426
7427 Writing 0x01 to this variable generates the assembly code:
7428 \layout Verse
7429
7430
7431 \family typewriter
7432 75*00 01\SpecialChar ~
7433 \SpecialChar ~
7434 \SpecialChar ~
7435 mov\SpecialChar ~
7436 \SpecialChar ~
7437 _test_data,#0x01
7438 \layout Subsubsection
7439
7440 xdata
7441 \begin_inset LatexCommand \index{xdata}
7442
7443 \end_inset
7444
7445
7446 \layout Standard
7447
7448 Variables declared with this storage class will be placed in the external
7449  RAM.
7450  This is the
7451 \series bold
7452 default
7453 \series default
7454  storage class for the Large Memory model, e.g.:
7455 \layout Verse
7456
7457
7458 \family typewriter
7459 xdata unsigned char test_xdata;
7460 \layout Standard
7461
7462 Writing 0x01 to this variable generates the assembly code:
7463 \layout Verse
7464
7465
7466 \family typewriter
7467 90s00r00\SpecialChar ~
7468 \SpecialChar ~
7469 \SpecialChar ~
7470 mov\SpecialChar ~
7471 \SpecialChar ~
7472 dptr,#_test_xdata
7473 \newline
7474 74\SpecialChar ~
7475 01\SpecialChar ~
7476 \SpecialChar ~
7477 \SpecialChar ~
7478 \SpecialChar ~
7479 \SpecialChar ~
7480 \SpecialChar ~
7481 mov\SpecialChar ~
7482 \SpecialChar ~
7483 a,#0x01
7484 \newline
7485 F0\SpecialChar ~
7486 \SpecialChar ~
7487 \SpecialChar ~
7488 \SpecialChar ~
7489 \SpecialChar ~
7490 \SpecialChar ~
7491 \SpecialChar ~
7492 \SpecialChar ~
7493 \SpecialChar ~
7494 movx\SpecialChar ~
7495 @dptr,a
7496 \layout Subsubsection
7497
7498 idata
7499 \begin_inset LatexCommand \index{idata}
7500
7501 \end_inset
7502
7503
7504 \layout Standard
7505
7506 Variables declared with this storage class will be allocated into the indirectly
7507  addressable portion of the internal ram of a 8051, e.g.:
7508 \layout Verse
7509
7510
7511 \family typewriter
7512 idata unsigned char test_idata;
7513 \layout Standard
7514
7515 Writing 0x01 to this variable generates the assembly code:
7516 \layout Verse
7517
7518
7519 \family typewriter
7520 78r00\SpecialChar ~
7521 \SpecialChar ~
7522 \SpecialChar ~
7523 \SpecialChar ~
7524 \SpecialChar ~
7525 \SpecialChar ~
7526 \SpecialChar ~
7527 mov\SpecialChar ~
7528 \SpecialChar ~
7529 r0,#_test_idata
7530 \newline
7531 76\SpecialChar ~
7532 01\SpecialChar ~
7533 \SpecialChar ~
7534 \SpecialChar ~
7535 \SpecialChar ~
7536 \SpecialChar ~
7537 \SpecialChar ~
7538 \SpecialChar ~
7539 mov\SpecialChar ~
7540 \SpecialChar ~
7541 @r0,#0x01
7542 \layout Standard
7543
7544 Please note, the first 128 byte of idata physically access the same RAM
7545  as the data memory.
7546  The original 8051 had 128 byte idata memory, nowadays most devices have
7547  256 byte idata memory.
7548  The stack
7549 \begin_inset LatexCommand \index{stack}
7550
7551 \end_inset
7552
7553  is located in idata memory.
7554 \layout Subsubsection
7555
7556 pdata
7557 \begin_inset LatexCommand \index{pdata}
7558
7559 \end_inset
7560
7561
7562 \layout Standard
7563
7564 Paged xdata access is currently not as straightforward as using the other
7565  addressing modes of a 8051.
7566  The following example writes 0x01 to the address pointed to.
7567  Please note, pdata access physically accesses xdata memory.
7568  The high byte of the address is determined by port P2 (or in case of some
7569  8051 variants by a separate Special Function Register, see section
7570 \begin_inset LatexCommand \ref{sub:MCS51-variants}
7571
7572 \end_inset
7573
7574 ).
7575 \layout Verse
7576
7577
7578 \family typewriter
7579 pdata unsigned char *test_pdata_ptr;
7580 \newline
7581
7582 \newline
7583 void main()
7584 \newline
7585 {
7586 \newline
7587 \SpecialChar ~
7588 \SpecialChar ~
7589 \SpecialChar ~
7590 \SpecialChar ~
7591 test_pdata_ptr = (pdata *)0xfe;
7592 \newline
7593 \SpecialChar ~
7594 \SpecialChar ~
7595 \SpecialChar ~
7596 \SpecialChar ~
7597 *test_pdata_ptr = 1;
7598 \newline
7599 }
7600 \layout Standard
7601
7602 Generates the assembly code:
7603 \layout Verse
7604
7605
7606 \family typewriter
7607 75*01 FE\SpecialChar ~
7608 \SpecialChar ~
7609 \SpecialChar ~
7610 mov\SpecialChar ~
7611  _test_pdata_ptr,#0xFE
7612 \newline
7613 78 FE\SpecialChar ~
7614 \SpecialChar ~
7615 \SpecialChar ~
7616 \SpecialChar ~
7617 \SpecialChar ~
7618 \SpecialChar ~
7619 mov\SpecialChar ~
7620  r0,#0xFE
7621 \newline
7622 74 01\SpecialChar ~
7623 \SpecialChar ~
7624 \SpecialChar ~
7625 \SpecialChar ~
7626 \SpecialChar ~
7627 \SpecialChar ~
7628 mov\SpecialChar ~
7629  a,#0x01
7630 \newline
7631 F2\SpecialChar ~
7632 \SpecialChar ~
7633 \SpecialChar ~
7634 \SpecialChar ~
7635 \SpecialChar ~
7636 \SpecialChar ~
7637 \SpecialChar ~
7638 \SpecialChar ~
7639 \SpecialChar ~
7640 movx @r0,a
7641 \layout Standard
7642
7643 Be extremely carefull if you use pdata together with the -
7644 \begin_inset ERT
7645 status Collapsed
7646
7647 \layout Standard
7648
7649 \backslash
7650 /
7651 \end_inset
7652
7653 -xstack
7654 \begin_inset LatexCommand \index{-\/-xstack}
7655
7656 \end_inset
7657
7658  option.
7659 \layout Subsubsection
7660
7661 code
7662 \begin_inset LatexCommand \index{code}
7663
7664 \end_inset
7665
7666
7667 \layout Standard
7668
7669 'Variables' declared with this storage class will be placed in the code
7670  memory:
7671 \layout Verse
7672
7673
7674 \family typewriter
7675 code unsigned char test_code;
7676 \layout Standard
7677
7678 Read access to this variable generates the assembly code:
7679 \layout Verse
7680
7681
7682 \family typewriter
7683 90s00r6F\SpecialChar ~
7684 \SpecialChar ~
7685 \SpecialChar ~
7686 mov dptr,#_test_code
7687 \newline
7688 E4\SpecialChar ~
7689 \SpecialChar ~
7690 \SpecialChar ~
7691 \SpecialChar ~
7692 \SpecialChar ~
7693 \SpecialChar ~
7694 \SpecialChar ~
7695 \SpecialChar ~
7696 \SpecialChar ~
7697 clr a
7698 \newline
7699 93\SpecialChar ~
7700 \SpecialChar ~
7701 \SpecialChar ~
7702 \SpecialChar ~
7703 \SpecialChar ~
7704 \SpecialChar ~
7705 \SpecialChar ~
7706 \SpecialChar ~
7707 \SpecialChar ~
7708 movc a,@a+dptr
7709 \layout Standard
7710
7711
7712 \family typewriter
7713 char
7714 \family default
7715  indexed arrays of characters in code memory can be accessed efficiently:
7716 \layout Verse
7717
7718
7719 \family typewriter
7720 code char test_array[] = {'c','h','e','a','p'};
7721 \layout Standard
7722
7723 Read access to this array using an 8-bit index generates the assembly code:
7724 \layout Verse
7725
7726
7727 \family typewriter
7728 E5*00\SpecialChar ~
7729 \SpecialChar ~
7730 \SpecialChar ~
7731 \SpecialChar ~
7732 \SpecialChar ~
7733 \SpecialChar ~
7734 mov a,_index
7735 \layout Verse
7736
7737
7738 \family typewriter
7739 90s00r41\SpecialChar ~
7740 \SpecialChar ~
7741 \SpecialChar ~
7742 mov dptr,#_test_array
7743 \layout Verse
7744
7745
7746 \family typewriter
7747 93\SpecialChar ~
7748 \SpecialChar ~
7749 \SpecialChar ~
7750 \SpecialChar ~
7751 \SpecialChar ~
7752 \SpecialChar ~
7753 \SpecialChar ~
7754 \SpecialChar ~
7755 \SpecialChar ~
7756 movc a,@a+dptr
7757 \layout Subsubsection
7758
7759 bit
7760 \begin_inset LatexCommand \index{bit}
7761
7762 \end_inset
7763
7764
7765 \layout Standard
7766
7767 This is a data-type and a storage class specifier.
7768  When a variable is declared as a bit, it is allocated into the bit addressable
7769  memory of 8051, e.g.:
7770 \layout Verse
7771
7772
7773 \family typewriter
7774 bit test_bit;
7775 \layout Standard
7776
7777 Writing 1 to this variable generates the assembly code:
7778 \layout Verse
7779
7780
7781 \family typewriter
7782 D2*00\SpecialChar ~
7783 \SpecialChar ~
7784 \SpecialChar ~
7785 \SpecialChar ~
7786 \SpecialChar ~
7787 \SpecialChar ~
7788 \SpecialChar ~
7789 setb\SpecialChar ~
7790 _test_bit
7791 \layout Standard
7792
7793 The bit addressable memory consists of 128 bits which are located from 0x20
7794  to 0x2f in data memory.
7795
7796 \layout Standard
7797
7798 Apart from this 8051 specific storage class most architectures support ANSI-C
7799  bitfields
7800 \begin_inset LatexCommand \index{bitfields}
7801
7802 \end_inset
7803
7804
7805 \begin_inset Foot
7806 collapsed false
7807
7808 \layout Standard
7809
7810 Not really meant as examples, but nevertheless showing what bitfields are
7811  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
7812 \end_inset
7813
7814 .
7815 \layout Subsubsection
7816
7817 sfr
7818 \begin_inset LatexCommand \index{sfr}
7819
7820 \end_inset
7821
7822  / sbit
7823 \begin_inset LatexCommand \index{sbit}
7824
7825 \end_inset
7826
7827
7828 \layout Standard
7829
7830 Like the bit keyword,
7831 \emph on
7832 sfr / sbit
7833 \emph default
7834 signifies both a data-type and storage class, they are used to describe
7835  the
7836 \emph on
7837 s
7838 \emph default
7839 pecial
7840 \emph on
7841 f
7842 \emph default
7843 unction
7844 \emph on
7845 r
7846 \emph default
7847 egisters and
7848 \emph on
7849 s
7850 \emph default
7851 pecial
7852 \emph on
7853 bit
7854 \emph default
7855  variables of a 8051, eg:
7856 \layout Verse
7857
7858
7859 \family typewriter
7860 sfr at
7861 \begin_inset LatexCommand \index{at}
7862
7863 \end_inset
7864
7865  0x80 P0;\SpecialChar ~
7866  /* special function register P0 at location 0x80 */
7867 \newline
7868 sbit at 0xd7 CY; /* CY (Carry Flag
7869 \begin_inset LatexCommand \index{Flags}
7870
7871 \end_inset
7872
7873
7874 \begin_inset LatexCommand \index{Carry flag}
7875
7876 \end_inset
7877
7878 ) */
7879 \layout Standard
7880
7881 Special function registers which are located on an address dividable by
7882  8 are bit-addressable, an
7883 \emph on
7884  sbit
7885 \emph default
7886  addresses a specific bit within these sfr.
7887 \layout Subsubsection
7888
7889 Pointers
7890 \begin_inset LatexCommand \index{Pointers}
7891
7892 \end_inset
7893
7894  to MCS51/DS390 specific memory spaces
7895 \layout Standard
7896
7897 SDCC allows (via language extensions) pointers to explicitly point to any
7898  of the memory spaces
7899 \begin_inset LatexCommand \index{Memory model}
7900
7901 \end_inset
7902
7903  of the 8051.
7904  In addition to the explicit pointers, the compiler uses (by default) generic
7905  pointers which can be used to point to any of the memory spaces.
7906 \newline
7907
7908 \newline
7909 Pointer declaration examples:
7910 \layout Verse
7911
7912
7913 \family typewriter
7914 /* pointer physically in internal ram pointing to object in external ram
7915  */
7916 \newline
7917 xdata unsigned char * data p;
7918 \newline
7919
7920 \newline
7921 /* pointer physically in external ram pointing to object in internal ram
7922  */
7923 \newline
7924 data unsigned char * xdata p;
7925 \newline
7926
7927 \newline
7928 /* pointer physically in code rom pointing to data in xdata space */
7929 \newline
7930 xdata unsigned char * code p;
7931 \newline
7932
7933 \newline
7934 /* pointer physically in code space pointing to data in code space */
7935 \newline
7936 code unsigned char * code p;
7937 \newline
7938
7939 \newline
7940 /* the following is a generic pointer physically located in xdata space
7941  */
7942 \newline
7943 char * xdata p;
7944 \layout Standard
7945
7946 Well you get the idea.
7947
7948 \newline
7949
7950 \newline
7951 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
7952 \emph on
7953 generic
7954 \emph default
7955  pointers.
7956
7957 \size small
7958
7959 \newline
7960
7961 \newline
7962
7963 \size default
7964 The highest order byte of the
7965 \emph on
7966 generic
7967 \emph default
7968  pointers contains the data space information.
7969  Assembler support routines are called whenever data is stored or retrieved
7970  using
7971 \emph on
7972 generic
7973 \emph default
7974  pointers.
7975  These are useful for developing reusable library
7976 \begin_inset LatexCommand \index{Libraries}
7977
7978 \end_inset
7979
7980  routines.
7981  Explicitly specifying the pointer type will generate the most efficient
7982  code.
7983 \layout Subsection
7984
7985 Z80/Z180 Storage Class
7986 \begin_inset LatexCommand \index{Storage class}
7987
7988 \end_inset
7989
7990  Language Extensions
7991 \layout Subsubsection
7992
7993 sfr
7994 \begin_inset LatexCommand \index{sfr}
7995
7996 \end_inset
7997
7998  (in/out to 8-bit addresses)
7999 \layout Standard
8000
8001 The Z80
8002 \begin_inset LatexCommand \index{Z80}
8003
8004 \end_inset
8005
8006  family has separate address spaces for memory and
8007 \emph on
8008 i
8009 \emph default
8010 nput/
8011 \emph on
8012 o
8013 \emph default
8014 utput memory.
8015  I/O memory
8016 \begin_inset LatexCommand \index{I/O memory (Z80/Z180)}
8017
8018 \end_inset
8019
8020  is accessed with special instructions, e.g.:
8021 \layout Verse
8022
8023
8024 \family typewriter
8025 sfr at 0x78 IoPort;\SpecialChar ~
8026 \SpecialChar ~
8027 /* define a var in I/O space at 78h called IoPort */
8028
8029 \layout Standard
8030
8031 Writing 0x01 to this variable generates the assembly code:
8032 \layout Verse
8033
8034
8035 \family typewriter
8036 3E 01\SpecialChar ~
8037 \SpecialChar ~
8038 \SpecialChar ~
8039 \SpecialChar ~
8040 \SpecialChar ~
8041 \SpecialChar ~
8042 ld a,#0x01
8043 \newline
8044 D3 78\SpecialChar ~
8045 \SpecialChar ~
8046 \SpecialChar ~
8047 \SpecialChar ~
8048 \SpecialChar ~
8049 \SpecialChar ~
8050 out (_IoPort),a
8051 \layout Subsubsection
8052
8053 banked sfr
8054 \begin_inset LatexCommand \index{sfr}
8055
8056 \end_inset
8057
8058  (in/out to 16-bit addresses)
8059 \layout Standard
8060
8061 The keyword
8062 \emph on
8063 banked
8064 \emph default
8065  is used to support 16 bit addresses in I/O memory e.g.:
8066 \layout Verse
8067
8068
8069 \family typewriter
8070 sfr banked at 0x123 IoPort;
8071 \layout Standard
8072
8073 Writing 0x01 to this variable generates the assembly code:
8074 \layout Verse
8075
8076
8077 \family typewriter
8078 01 23 01\SpecialChar ~
8079 \SpecialChar ~
8080 \SpecialChar ~
8081 ld bc,#_IoPort
8082 \newline
8083 3E 01\SpecialChar ~
8084 \SpecialChar ~
8085 \SpecialChar ~
8086 \SpecialChar ~
8087 \SpecialChar ~
8088 \SpecialChar ~
8089 ld a,#0x01
8090 \newline
8091 ED 79\SpecialChar ~
8092 \SpecialChar ~
8093 \SpecialChar ~
8094 \SpecialChar ~
8095 \SpecialChar ~
8096 \SpecialChar ~
8097 out (c),a
8098 \layout Subsubsection
8099
8100 sfr
8101 \begin_inset LatexCommand \index{sfr}
8102
8103 \end_inset
8104
8105  (in0/out0 to 8 bit addresses on Z180
8106 \begin_inset LatexCommand \index{Z180}
8107
8108 \end_inset
8109
8110 /HD64180
8111 \begin_inset LatexCommand \index{HD64180}
8112
8113 \end_inset
8114
8115 )
8116 \layout Standard
8117
8118 The compiler option -
8119 \begin_inset ERT
8120 status Collapsed
8121
8122 \layout Standard
8123
8124 \backslash
8125 /
8126 \end_inset
8127
8128 -portmode=z180 (?) and a compiler #pragma\SpecialChar ~
8129 portmode
8130 \begin_inset LatexCommand \index{\#pragma portmode}
8131
8132 \end_inset
8133
8134 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
8135 ns
8136 \family typewriter
8137 in0/out0
8138 \family default
8139  instead of
8140 \family typewriter
8141 in/out
8142 \family default
8143 .
8144  If you include the file z180.h this will be set automatically.
8145 \layout Section
8146
8147 Absolute Addressing
8148 \begin_inset LatexCommand \index{Absolute addressing}
8149
8150 \end_inset
8151
8152
8153 \layout Standard
8154
8155 Data items can be assigned an absolute address with the
8156 \emph on
8157 at
8158 \begin_inset LatexCommand \index{at}
8159
8160 \end_inset
8161
8162  <address>
8163 \emph default
8164  keyword, in addition to a storage class, e.g.:
8165 \layout Verse
8166
8167
8168 \family typewriter
8169 xdata
8170 \begin_inset LatexCommand \index{xdata}
8171
8172 \end_inset
8173
8174  at
8175 \begin_inset LatexCommand \index{at}
8176
8177 \end_inset
8178
8179  0x7ffe unsigned int chksum;
8180 \layout Standard
8181
8182 In the above example the variable chksum will located at 0x7ffe and 0x7fff
8183  of the external ram.
8184  The compiler does
8185 \emph on
8186 not
8187 \emph default
8188  reserve any space for variables declared in this way (they are implemented
8189  with an equate in the assembler).
8190  Thus it is left to the programmer to make sure there are no overlaps with
8191  other variables that are declared without the absolute address.
8192  The assembler listing file (.lst
8193 \begin_inset LatexCommand \index{<file>.lst}
8194
8195 \end_inset
8196
8197 ) and the linker output files (.rst
8198 \begin_inset LatexCommand \index{<file>.rst}
8199
8200 \end_inset
8201
8202 ) and (.map
8203 \begin_inset LatexCommand \index{<file>.map}
8204
8205 \end_inset
8206
8207 ) are good places to look for such overlaps.
8208  Variables with an absolute address are
8209 \emph on
8210 not
8211 \emph default
8212  initialized.
8213 \layout Standard
8214
8215 In case of memory mapped I/O devices the keyword
8216 \emph on
8217 volatile
8218 \emph default
8219  should be used to tell the compiler that accesses might not be optimized
8220  away:
8221 \layout Verse
8222
8223
8224 \family typewriter
8225 volatile
8226 \begin_inset LatexCommand \index{volatile}
8227
8228 \end_inset
8229
8230  xdata
8231 \begin_inset LatexCommand \index{xdata}
8232
8233 \end_inset
8234
8235  at
8236 \begin_inset LatexCommand \index{at}
8237
8238 \end_inset
8239
8240  0x8000 unsigned char PORTA_8255;
8241 \layout Standard
8242
8243 Absolute address can be specified for variables in all storage classes,
8244  e.g.:
8245 \layout Verse
8246
8247
8248 \family typewriter
8249 bit
8250 \begin_inset LatexCommand \index{bit}
8251
8252 \end_inset
8253
8254  at
8255 \begin_inset LatexCommand \index{at}
8256
8257 \end_inset
8258
8259  0x02 bvar;
8260 \layout Standard
8261
8262 The above example will allocate the variable at offset 0x02 in the bit-addressab
8263 le space.
8264  There is no real advantage to assigning absolute addresses to variables
8265  in this manner, unless you want strict control over all the variables allocated.
8266  One possible use would be to write hardware portable code.
8267  For example, if you have a routine that uses one or more of the microcontroller
8268  I/O pins, and such pins are different for two different hardwares, you
8269  can declare the I/O pins in your routine using:
8270 \layout Verse
8271
8272
8273 \family typewriter
8274 extern volatile bit SDI;
8275 \newline
8276 extern volatile bit SCLK;
8277 \newline
8278 extern volatile bit CPOL;
8279 \newline
8280
8281 \newline
8282 void DS1306_put(unsigned char value)
8283 \newline
8284 {
8285 \newline
8286 \SpecialChar ~
8287 \SpecialChar ~
8288 \SpecialChar ~
8289 \SpecialChar ~
8290 unsigned char mask=0x80;
8291 \newline
8292
8293 \newline
8294 \SpecialChar ~
8295 \SpecialChar ~
8296 \SpecialChar ~
8297 \SpecialChar ~
8298 while(mask)
8299 \newline
8300 \SpecialChar ~
8301 \SpecialChar ~
8302 \SpecialChar ~
8303 \SpecialChar ~
8304 {
8305 \newline
8306 \SpecialChar ~
8307 \SpecialChar ~
8308 \SpecialChar ~
8309 \SpecialChar ~
8310 \SpecialChar ~
8311 \SpecialChar ~
8312 \SpecialChar ~
8313 \SpecialChar ~
8314 SDI=(value & mask)?1:0;
8315 \newline
8316 \SpecialChar ~
8317 \SpecialChar ~
8318 \SpecialChar ~
8319 \SpecialChar ~
8320 \SpecialChar ~
8321 \SpecialChar ~
8322 \SpecialChar ~
8323 \SpecialChar ~
8324 SCLK=!CPOL;
8325 \newline
8326 \SpecialChar ~
8327 \SpecialChar ~
8328 \SpecialChar ~
8329 \SpecialChar ~
8330 \SpecialChar ~
8331 \SpecialChar ~
8332 \SpecialChar ~
8333 \SpecialChar ~
8334 SCLK=CPOL;
8335 \newline
8336 \SpecialChar ~
8337 \SpecialChar ~
8338 \SpecialChar ~
8339 \SpecialChar ~
8340 \SpecialChar ~
8341 \SpecialChar ~
8342 \SpecialChar ~
8343 \SpecialChar ~
8344 mask/=2;
8345 \newline
8346 \SpecialChar ~
8347 \SpecialChar ~
8348 \SpecialChar ~
8349 \SpecialChar ~
8350 }
8351 \newline
8352 }
8353 \layout Standard
8354
8355 Then, someplace in the code for the first hardware you would use
8356 \layout Verse
8357
8358
8359 \family typewriter
8360 bit at 0x80 SDI;\SpecialChar ~
8361 \SpecialChar ~
8362 \SpecialChar ~
8363 \SpecialChar ~
8364 /* I/O port 0, bit 0 */
8365 \newline
8366 bit at 0x81 SCLK;\SpecialChar ~
8367 \SpecialChar ~
8368 \SpecialChar ~
8369 /* I/O port 0, bit 1 */
8370 \newline
8371 bit CPOL;\SpecialChar ~
8372 \SpecialChar ~
8373 \SpecialChar ~
8374 \SpecialChar ~
8375 \SpecialChar ~
8376 \SpecialChar ~
8377 \SpecialChar ~
8378 \SpecialChar ~
8379 \SpecialChar ~
8380 \SpecialChar ~
8381 \SpecialChar ~
8382 /* This is a variable, let the linker allocate this one */
8383 \layout Standard
8384
8385 Similarly, for the second hardware you would use
8386 \layout Verse
8387
8388
8389 \family typewriter
8390 bit at 0x83 SDI;\SpecialChar ~
8391 \SpecialChar ~
8392 \SpecialChar ~
8393 \SpecialChar ~
8394 /* I/O port 0, bit 3 */
8395 \newline
8396 bit at 0x91 SCLK;\SpecialChar ~
8397 \SpecialChar ~
8398 \SpecialChar ~
8399 /* I/O port 1, bit 1 */
8400 \newline
8401 bit
8402 \begin_inset LatexCommand \index{bit}
8403
8404 \end_inset
8405
8406  CPOL;\SpecialChar ~
8407 \SpecialChar ~
8408 \SpecialChar ~
8409 \SpecialChar ~
8410 \SpecialChar ~
8411 \SpecialChar ~
8412 \SpecialChar ~
8413 \SpecialChar ~
8414 \SpecialChar ~
8415 \SpecialChar ~
8416 \SpecialChar ~
8417 /* This is a variable, let the linker allocate this one */
8418 \layout Standard
8419
8420 and you can use the same hardware dependent routine without changes, as
8421  for example in a library.
8422  This is somehow similar to sbit, but only one absolute address has to be
8423  specified in the whole project.
8424 \layout Section
8425
8426 Parameters
8427 \begin_inset LatexCommand \index{Parameters}
8428
8429 \end_inset
8430
8431
8432 \begin_inset LatexCommand \index{function parameter}
8433
8434 \end_inset
8435
8436  & Local Variables
8437 \begin_inset LatexCommand \index{Local variable}
8438
8439 \end_inset
8440
8441
8442 \layout Standard
8443
8444 Automatic (local) variables and parameters to functions can either be placed
8445  on the stack or in data-space.
8446  The default action of the compiler is to place these variables in the internal
8447  RAM (for small model) or external RAM (for large model).
8448  This in fact makes them similar to
8449 \emph on
8450 static
8451 \begin_inset LatexCommand \index{static}
8452
8453 \end_inset
8454
8455
8456 \emph default
8457  so by default functions are non-reentrant
8458 \begin_inset LatexCommand \index{reentrant}
8459
8460 \end_inset
8461
8462 .
8463
8464 \newline
8465
8466 \newline
8467 They can be placed on the stack
8468 \begin_inset LatexCommand \index{stack}
8469
8470 \end_inset
8471
8472  either by using the
8473 \emph on
8474  -
8475 \begin_inset ERT
8476 status Collapsed
8477
8478 \layout Standard
8479
8480 \backslash
8481 /
8482 \end_inset
8483
8484 -stack-auto
8485 \begin_inset LatexCommand \index{-\/-stack-auto}
8486
8487 \end_inset
8488
8489
8490 \emph default
8491  option or by using the
8492 \emph on
8493 reentrant
8494 \begin_inset LatexCommand \index{reentrant}
8495
8496 \end_inset
8497
8498
8499 \emph default
8500  keyword in the function declaration, e.g.:
8501 \layout Verse
8502
8503
8504 \family typewriter
8505 unsigned char foo(char i) reentrant
8506 \newline
8507 {
8508 \newline
8509 \SpecialChar ~
8510 \SpecialChar ~
8511 \SpecialChar ~
8512 \SpecialChar ~
8513 ...
8514
8515 \newline
8516 }
8517 \layout Standard
8518
8519 Since stack space on 8051 is limited, the
8520 \emph on
8521 reentrant
8522 \emph default
8523 keyword or the
8524 \emph on
8525  -
8526 \begin_inset ERT
8527 status Collapsed
8528
8529 \layout Standard
8530
8531 \backslash
8532 /
8533 \end_inset
8534
8535 -stack-auto
8536 \emph default
8537  option should be used sparingly.
8538  Note that the reentrant keyword just means that the parameters & local
8539  variables will be allocated to the stack, it
8540 \emph on
8541 does not
8542 \emph default
8543  mean that the function is register bank independent.
8544 \newline
8545
8546 \newline
8547 Local variables can be assigned storage classes and absolute
8548 \begin_inset LatexCommand \index{Absolute addressing}
8549
8550 \end_inset
8551
8552  addresses, e.g.:
8553 \layout Verse
8554
8555
8556 \family typewriter
8557 unsigned char foo()
8558 \newline
8559 {
8560 \newline
8561 \SpecialChar ~
8562 \SpecialChar ~
8563 \SpecialChar ~
8564 \SpecialChar ~
8565 xdata unsigned char i;
8566 \newline
8567 \SpecialChar ~
8568 \SpecialChar ~
8569 \SpecialChar ~
8570 \SpecialChar ~
8571 bit bvar;
8572 \newline
8573 \SpecialChar ~
8574 \SpecialChar ~
8575 \SpecialChar ~
8576 \SpecialChar ~
8577 data at 0x31 unsigned char j;
8578 \newline
8579 \SpecialChar ~
8580 \SpecialChar ~
8581 \SpecialChar ~
8582 \SpecialChar ~
8583 ...
8584
8585 \newline
8586 }
8587 \layout Standard
8588
8589 In the above example the variable
8590 \emph on
8591 i
8592 \emph default
8593  will be allocated in the external ram,
8594 \emph on
8595 bvar
8596 \emph default
8597  in bit addressable space and
8598 \emph on
8599  j
8600 \emph default
8601  in internal ram.
8602  When compiled with
8603 \emph on
8604 -
8605 \begin_inset ERT
8606 status Collapsed
8607
8608 \layout Standard
8609
8610 \backslash
8611 /
8612 \end_inset
8613
8614 -stack-auto
8615 \emph default
8616  or when a function is declared as
8617 \emph on
8618 reentrant
8619 \emph default
8620  this should only be done for static variables.
8621 \layout Standard
8622
8623 Parameters
8624 \begin_inset LatexCommand \index{function parameter}
8625
8626 \end_inset
8627
8628  however are not allowed any storage class
8629 \begin_inset LatexCommand \index{storage class}
8630
8631 \end_inset
8632
8633 , (storage classes for parameters will be ignored), their allocation is
8634  governed by the memory model in use, and the reentrancy options.
8635 \layout Section
8636
8637 Overlaying
8638 \begin_inset LatexCommand \label{sub:Overlaying}
8639
8640 \end_inset
8641
8642
8643 \begin_inset LatexCommand \index{Overlaying}
8644
8645 \end_inset
8646
8647
8648 \layout Standard
8649
8650 For non-reentrant
8651 \begin_inset LatexCommand \index{reentrant}
8652
8653 \end_inset
8654
8655  functions SDCC will try to reduce internal ram space usage by overlaying
8656  parameters and local variables of a function (if possible).
8657  Parameters and local variables of a function will be allocated to an overlayabl
8658 e segment if the function has
8659 \emph on
8660 no other function calls and the function is non-reentrant and the memory
8661  model
8662 \begin_inset LatexCommand \index{Memory model}
8663
8664 \end_inset
8665
8666  is small.
8667
8668 \emph default
8669  If an explicit storage class
8670 \begin_inset LatexCommand \index{Storage class}
8671
8672 \end_inset
8673
8674  is specified for a local variable, it will NOT be overlayed.
8675 \layout Standard
8676
8677 Note that the compiler (not the linkage editor) makes the decision for overlayin
8678 g the data items.
8679  Functions that are called from an interrupt service routine should be preceded
8680  by a #pragma\SpecialChar ~
8681 NOOVERLAY
8682 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
8683
8684 \end_inset
8685
8686  if they are not reentrant.
8687 \layout Standard
8688
8689 Also note that the compiler does not do any processing of inline assembler
8690  code, so the compiler might incorrectly assign local variables and parameters
8691  of a function into the overlay segment if the inline assembler code calls
8692  other c-functions that might use the overlay.
8693  In that case the #pragma\SpecialChar ~
8694 NOOVERLAY should be used.
8695 \layout Standard
8696
8697 Parameters and local variables of functions that contain 16 or 32 bit multiplica
8698 tion
8699 \begin_inset LatexCommand \index{Multiplication}
8700
8701 \end_inset
8702
8703  or division
8704 \begin_inset LatexCommand \index{Division}
8705
8706 \end_inset
8707
8708  will NOT be overlayed since these are implemented using external functions,
8709  e.g.:
8710 \layout Verse
8711
8712
8713 \family typewriter
8714 #pragma SAVE
8715 \newline
8716 #pragma NOOVERLAY
8717 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
8718
8719 \end_inset
8720
8721
8722 \newline
8723 void set_error(unsigned char errcd)
8724 \newline
8725 {
8726 \newline
8727 \SpecialChar ~
8728 \SpecialChar ~
8729 \SpecialChar ~
8730 \SpecialChar ~
8731 P3 = errcd;
8732 \newline
8733 }
8734 \newline
8735 #pragma RESTORE
8736 \newline
8737
8738 \newline
8739 void some_isr () interrupt
8740 \begin_inset LatexCommand \index{interrupt}
8741
8742 \end_inset
8743
8744  2
8745 \newline
8746 {
8747 \newline
8748 \SpecialChar ~
8749 \SpecialChar ~
8750 \SpecialChar ~
8751 \SpecialChar ~
8752 ...
8753 \newline
8754 \SpecialChar ~
8755 \SpecialChar ~
8756 \SpecialChar ~
8757 \SpecialChar ~
8758 set_error(10);
8759 \newline
8760 \SpecialChar ~
8761 \SpecialChar ~
8762 \SpecialChar ~
8763 \SpecialChar ~
8764 ...
8765
8766 \newline
8767 }
8768 \layout Standard
8769
8770 In the above example the parameter
8771 \emph on
8772 errcd
8773 \emph default
8774  for the function
8775 \emph on
8776 set_error
8777 \emph default
8778  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
8779 NOOVERLAY was
8780  not present, this could cause unpredictable runtime behavior when called
8781  from an ISR.
8782  The #pragma\SpecialChar ~
8783 NOOVERLAY ensures that the parameters and local variables for
8784  the function are NOT overlayed.
8785 \layout Section
8786
8787 Interrupt Service Routines
8788 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
8789
8790 \end_inset
8791
8792
8793 \layout Standard
8794
8795 SDCC allows interrupt service routines to be coded in C, with some extended
8796  keywords.
8797 \layout Verse
8798
8799
8800 \family typewriter
8801 void timer_isr (void) interrupt 1 using 1
8802 \newline
8803 {
8804 \newline
8805 \SpecialChar ~
8806 \SpecialChar ~
8807 \SpecialChar ~
8808 \SpecialChar ~
8809 ...
8810
8811 \newline
8812 }
8813 \layout Standard
8814
8815 The optional number following the
8816 \emph on
8817 interrupt
8818 \begin_inset LatexCommand \index{interrupt}
8819
8820 \end_inset
8821
8822
8823 \emph default
8824  keyword is the interrupt number this routine will service.
8825  When present, the compiler will insert a call to this routine in the interrupt
8826  vector table for the interrupt number specified.
8827  The
8828 \emph on
8829 using
8830 \emph default
8831  keyword can be used to tell the compiler to use the specified register
8832  bank (8051 specific) when generating code for this function.
8833
8834 \newline
8835
8836 \layout Standard
8837
8838 If you have multiple source files in your project, interrupt service routines
8839  can be present in any of them, but a prototype of the isr MUST be present
8840  or included in the file that contains the function
8841 \emph on
8842 main
8843 \emph default
8844 .
8845 \layout Standard
8846
8847 Interrupt numbers and the corresponding address & descriptions for the Standard
8848  8051/8052 are listed below.
8849  SDCC will automatically adjust the interrupt vector table to the maximum
8850  interrupt number specified.
8851 \newline
8852
8853 \layout Standard
8854 \align center
8855
8856 \begin_inset  Tabular
8857 <lyxtabular version="3" rows="7" columns="3">
8858 <features>
8859 <column alignment="center" valignment="top" leftline="true" width="0in">
8860 <column alignment="center" valignment="top" leftline="true" width="0in">
8861 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
8862 <row topline="true" bottomline="true">
8863 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8864 \begin_inset Text
8865
8866 \layout Standard
8867
8868 Interrupt #
8869 \end_inset
8870 </cell>
8871 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8872 \begin_inset Text
8873
8874 \layout Standard
8875
8876 Description
8877 \end_inset
8878 </cell>
8879 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8880 \begin_inset Text
8881
8882 \layout Standard
8883
8884 Vector Address
8885 \end_inset
8886 </cell>
8887 </row>
8888 <row topline="true">
8889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8890 \begin_inset Text
8891
8892 \layout Standard
8893
8894 0
8895 \end_inset
8896 </cell>
8897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8898 \begin_inset Text
8899
8900 \layout Standard
8901
8902 External 0
8903 \end_inset
8904 </cell>
8905 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8906 \begin_inset Text
8907
8908 \layout Standard
8909
8910 0x0003
8911 \end_inset
8912 </cell>
8913 </row>
8914 <row topline="true">
8915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8916 \begin_inset Text
8917
8918 \layout Standard
8919
8920 1
8921 \end_inset
8922 </cell>
8923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8924 \begin_inset Text
8925
8926 \layout Standard
8927
8928 Timer 0
8929 \end_inset
8930 </cell>
8931 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8932 \begin_inset Text
8933
8934 \layout Standard
8935
8936 0x000B
8937 \end_inset
8938 </cell>
8939 </row>
8940 <row topline="true">
8941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8942 \begin_inset Text
8943
8944 \layout Standard
8945
8946 2
8947 \end_inset
8948 </cell>
8949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8950 \begin_inset Text
8951
8952 \layout Standard
8953
8954 External 1
8955 \end_inset
8956 </cell>
8957 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8958 \begin_inset Text
8959
8960 \layout Standard
8961
8962 0x0013
8963 \end_inset
8964 </cell>
8965 </row>
8966 <row topline="true">
8967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8968 \begin_inset Text
8969
8970 \layout Standard
8971
8972 3
8973 \end_inset
8974 </cell>
8975 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8976 \begin_inset Text
8977
8978 \layout Standard
8979
8980 Timer 1
8981 \end_inset
8982 </cell>
8983 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8984 \begin_inset Text
8985
8986 \layout Standard
8987
8988 0x001B
8989 \end_inset
8990 </cell>
8991 </row>
8992 <row topline="true">
8993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8994 \begin_inset Text
8995
8996 \layout Standard
8997
8998 4
8999 \end_inset
9000 </cell>
9001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9002 \begin_inset Text
9003
9004 \layout Standard
9005
9006 Serial
9007 \end_inset
9008 </cell>
9009 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9010 \begin_inset Text
9011
9012 \layout Standard
9013
9014 0x0023
9015 \end_inset
9016 </cell>
9017 </row>
9018 <row topline="true" bottomline="true">
9019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9020 \begin_inset Text
9021
9022 \layout Standard
9023
9024 5
9025 \end_inset
9026 </cell>
9027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9028 \begin_inset Text
9029
9030 \layout Standard
9031
9032 Timer 2 (8052)
9033 \end_inset
9034 </cell>
9035 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9036 \begin_inset Text
9037
9038 \layout Standard
9039
9040 0x002B
9041 \end_inset
9042 </cell>
9043 </row>
9044 </lyxtabular>
9045
9046 \end_inset
9047
9048
9049 \newline
9050
9051 \layout Standard
9052
9053 If the interrupt service routine is defined without
9054 \emph on
9055 using
9056 \begin_inset LatexCommand \index{using}
9057
9058 \end_inset
9059
9060
9061 \emph default
9062  a register bank or with register bank 0 (using 0), the compiler will save
9063  the registers used by itself on the stack upon entry and restore them at
9064  exit, however if such an interrupt service routine calls another function
9065  then the entire register bank will be saved on the stack.
9066  This scheme may be advantageous for small interrupt service routines which
9067  have low register usage.
9068 \layout Standard
9069
9070 If the interrupt service routine is defined to be using a specific register
9071  bank then only
9072 \emph on
9073 a, b & dptr
9074 \emph default
9075  are save and restored, if such an interrupt service routine calls another
9076  function (using another register bank) then the entire register bank of
9077  the called function will be saved on the stack.
9078  This scheme is recommended for larger interrupt service routines.
9079 \layout Standard
9080
9081 Using interrupts opens the door for some very interesting bugs:
9082 \layout Standard
9083
9084 If the interrupt service routines changes variables which are accessed by
9085  other functions these variables should be declared
9086 \emph on
9087 volatile
9088 \emph default
9089
9090 \begin_inset LatexCommand \index{volatile}
9091
9092 \end_inset
9093
9094 .
9095  If the access to these variables is not
9096 \emph on
9097 atomic
9098 \begin_inset LatexCommand \index{atomic access}
9099
9100 \end_inset
9101
9102
9103 \emph default
9104  (i.e.
9105  the processor needs more than one instruction for the access and could
9106  be interrupted while accessing the variable) the interrupt must disabled
9107  during the access to avoid inconsistent data.
9108  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
9109  and should be protected by disabling interrupts.
9110  You're not automatically on the safe side if you use 8 bit variables though.
9111  We need an example here: f.e.
9112  on the 8051 the harmless looking
9113 \begin_inset Quotes srd
9114 \end_inset
9115
9116
9117 \family typewriter
9118 flags\SpecialChar ~
9119 |=\SpecialChar ~
9120 0x80;
9121 \family default
9122
9123 \begin_inset Quotes sld
9124 \end_inset
9125
9126  is not atomic if
9127 \family typewriter
9128 flags
9129 \family default
9130  resides in xdata.
9131  Setting
9132 \begin_inset Quotes srd
9133 \end_inset
9134
9135
9136 \family typewriter
9137 flags\SpecialChar ~
9138 |=\SpecialChar ~
9139 0x40;
9140 \family default
9141
9142 \begin_inset Quotes sld
9143 \end_inset
9144
9145  from within an interrupt routine might get lost if the interrupt occurs
9146  at the wrong time.
9147
9148 \begin_inset Quotes sld
9149 \end_inset
9150
9151
9152 \family typewriter
9153 counter\SpecialChar ~
9154 +=\SpecialChar ~
9155 8;
9156 \family default
9157
9158 \begin_inset Quotes srd
9159 \end_inset
9160
9161  is not atomic on the 8051 even if
9162 \family typewriter
9163 counter
9164 \family default
9165  is located in data memory.
9166  Bugs like these are hard to reproduce and can cause a lot of trouble.
9167
9168 \layout Standard
9169
9170 A special note here, int (16 bit) and long (32 bit) integer division
9171 \begin_inset LatexCommand \index{Division}
9172
9173 \end_inset
9174
9175 , multiplication
9176 \begin_inset LatexCommand \index{Multiplication}
9177
9178 \end_inset
9179
9180  & modulus
9181 \begin_inset LatexCommand \index{Modulus}
9182
9183 \end_inset
9184
9185  and floating-point
9186 \begin_inset LatexCommand \index{Floating point support}
9187
9188 \end_inset
9189
9190  operations are implemented using external support routines developed in
9191  ANSI-C.
9192  If an interrupt service routine needs to do any of these operations then
9193  the support routines (as mentioned in a following section) will have to
9194  be recompiled using the
9195 \emph on
9196  -
9197 \begin_inset ERT
9198 status Collapsed
9199
9200 \layout Standard
9201
9202 \backslash
9203 /
9204 \end_inset
9205
9206 -stack-auto
9207 \begin_inset LatexCommand \index{-\/-stack-auto}
9208
9209 \end_inset
9210
9211
9212 \emph default
9213  option and the source file will need to be compiled using the
9214 \emph on
9215 -
9216 \begin_inset ERT
9217 status Collapsed
9218
9219 \layout Standard
9220
9221 \backslash
9222 /
9223 \end_inset
9224
9225 -int-long-reent
9226 \emph default
9227
9228 \begin_inset LatexCommand \index{-\/-int-long-reent}
9229
9230 \end_inset
9231
9232  compiler option.
9233 \layout Standard
9234
9235 Calling other functions from an interrupt service routine is not recommended,
9236  avoid it if possible.
9237  Note that when some function is called from an interrupt service routine
9238  it should be preceded by a #pragma\SpecialChar ~
9239 NOOVERLAY
9240 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
9241
9242 \end_inset
9243
9244  if it is not reentrant.
9245  Furthermore nonreentrant functions should not be called from the main program
9246  while the interrupt service routine might be active.
9247
9248 \newline
9249
9250 \newline
9251 Also see section
9252 \begin_inset LatexCommand \ref{sub:Overlaying}
9253
9254 \end_inset
9255
9256 \SpecialChar ~
9257 about Overlaying and section
9258 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
9259
9260 \end_inset
9261
9262 \SpecialChar ~
9263 about Functions using private banks.
9264 \layout Section
9265
9266 Enabling and Disabling Interrupts
9267 \layout Subsection
9268
9269 Critical Functions and Critical Statements
9270 \layout Standard
9271
9272 A special keyword may be associated with a function declaring it as
9273 \emph on
9274 critical
9275 \emph default
9276 .
9277  SDCC will generate code to disable all interrupts
9278 \begin_inset LatexCommand \index{interrupt}
9279
9280 \end_inset
9281
9282  upon entry to a critical function and restore the interrupt enable to the
9283  previous state before returning.
9284  Nesting critical functions will need one additional byte on the stack
9285 \begin_inset LatexCommand \index{stack}
9286
9287 \end_inset
9288
9289  for each call.
9290 \layout Verse
9291
9292
9293 \family typewriter
9294 int foo () critical
9295 \begin_inset LatexCommand \index{critical}
9296
9297 \end_inset
9298
9299
9300 \newline
9301 {
9302 \newline
9303 \SpecialChar ~
9304 \SpecialChar ~
9305 \SpecialChar ~
9306 \SpecialChar ~
9307 ...
9308
9309 \newline
9310 \SpecialChar ~
9311 \SpecialChar ~
9312 \SpecialChar ~
9313 \SpecialChar ~
9314 ...
9315
9316 \newline
9317 }
9318 \layout Standard
9319
9320 The critical attribute maybe used with other attributes like
9321 \emph on
9322 reentrant.
9323 \emph default
9324
9325 \newline
9326 The keyword
9327 \emph on
9328 critical
9329 \emph default
9330  may also be used to disable interrupts more locally:
9331 \layout Verse
9332
9333
9334 \family typewriter
9335 critical{ i++; }
9336 \layout Standard
9337
9338 More than one statement could have been included in the block.
9339 \layout Subsection
9340
9341 Enabling and Disabling Interrupts directly
9342 \layout Standard
9343
9344 Interrupts
9345 \begin_inset LatexCommand \index{interrupt}
9346
9347 \end_inset
9348
9349  can also be disabled and enabled directly (8051):
9350 \layout Verse
9351
9352
9353 \family typewriter
9354 EA = 0;
9355 \layout Verse
9356
9357
9358 \family typewriter
9359 ...
9360 \layout Verse
9361
9362
9363 \family typewriter
9364 EA = 1;
9365 \layout Standard
9366
9367 On other architectures which have seperate opcodes for enabling and disabling
9368  interrupts you might want to make use of defines with inline assembly
9369 \begin_inset LatexCommand \index{Assembler routines}
9370
9371 \end_inset
9372
9373  (HC08):
9374 \layout Verse
9375
9376
9377 \family typewriter
9378 #define CLI _asm
9379 \begin_inset LatexCommand \index{\_asm}
9380
9381 \end_inset
9382
9383 \SpecialChar ~
9384 \SpecialChar ~
9385 cli\SpecialChar ~
9386 \SpecialChar ~
9387 _endasm
9388 \begin_inset LatexCommand \index{\_endasm}
9389
9390 \end_inset
9391
9392 ;
9393 \layout Verse
9394
9395
9396 \family typewriter
9397 #define SEI _asm\SpecialChar ~
9398 \SpecialChar ~
9399 sei\SpecialChar ~
9400 \SpecialChar ~
9401 _endasm;
9402 \layout Verse
9403
9404
9405 \family typewriter
9406 ...
9407 \layout Standard
9408
9409 Note: it is sometimes sufficient to disable only a specific interrupt source
9410  like f.e.
9411  a timer or serial interrupt by manipulating an
9412 \emph on
9413 interrupt mask
9414 \begin_inset LatexCommand \index{interrupt mask}
9415
9416 \end_inset
9417
9418
9419 \emph default
9420  register.
9421  Usually the time during which interrupts are disabled should be kept as
9422  short as possible.
9423  This minimizes both
9424 \emph on
9425 interrupt latency
9426 \emph default
9427
9428 \begin_inset LatexCommand \index{interrupt latency}
9429
9430 \end_inset
9431
9432  (the time between the occurrence of the interrupt and the execution of
9433  the first code in the interrupt routine) and
9434 \emph on
9435 interrupt jitter
9436 \emph default
9437
9438 \begin_inset LatexCommand \index{interrupt jitter}
9439
9440 \end_inset
9441
9442  (the difference between the shortest and the longest interrupt latency).
9443  These really are something different, f.e.
9444  a serial interrupt has to be served before its buffer overruns so it cares
9445  for the maximum interrupt latency, whereas it does not care about jitter.
9446  On a loudspeaker driven via a digital to analog converter which is fed
9447  by an interrupt a latency of a few milliseconds might be tolerable, whereas
9448  a much smaller jitter will be very audible.
9449 \layout Standard
9450
9451 You can reenable interrupts within an interrupt routine and on some architecture
9452 s you can make use of two (or more) levels of
9453 \emph on
9454 interrupt priorities
9455 \emph default
9456
9457 \begin_inset LatexCommand \index{interrupt priority}
9458
9459 \end_inset
9460
9461 .
9462  On architectures which don't support interrupt priorities these can be
9463  implemented by manipulating the interrupt mask and reenabling interrupts
9464  within the interrupt routine.
9465  Don't add complexity unless you have to.
9466
9467 \layout Section
9468
9469 Functions using private banks
9470 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
9471
9472 \end_inset
9473
9474
9475 \begin_inset LatexCommand \index{bank}
9476
9477 \end_inset
9478
9479
9480 \layout Standard
9481
9482 The
9483 \emph on
9484 using
9485 \begin_inset LatexCommand \index{using}
9486
9487 \end_inset
9488
9489
9490 \emph default
9491  attribute (which tells the compiler to use a register bank other than the
9492  default bank zero) should only be applied to
9493 \emph on
9494 interrupt
9495 \begin_inset LatexCommand \index{interrupt}
9496
9497 \end_inset
9498
9499
9500 \emph default
9501  functions (see note 1 below).
9502  This will in most circumstances make the generated ISR code more efficient
9503  since it will not have to save registers on the stack.
9504 \layout Standard
9505
9506 The
9507 \emph on
9508 using
9509 \emph default
9510  attribute will have no effect on the generated code for a
9511 \emph on
9512 non-interrupt
9513 \emph default
9514  function (but may occasionally be useful anyway
9515 \begin_inset Foot
9516 collapsed false
9517
9518 \layout Standard
9519
9520 possible exception: if a function is called ONLY from 'interrupt' functions
9521  using a particular bank, it can be declared with the same 'using' attribute
9522  as the calling 'interrupt' functions.
9523  For instance, if you have several ISRs using bank one, and all of them
9524  call memcpy(), it might make sense to create a specialized version of memcpy()
9525  'using 1', since this would prevent the ISR from having to save bank zero
9526  to the stack on entry and switch to bank zero before calling the function
9527 \end_inset
9528
9529 ).
9530 \newline
9531
9532 \emph on
9533 (pending: I don't think this has been done yet)
9534 \layout Standard
9535
9536 An
9537 \emph on
9538 interrupt
9539 \emph default
9540  function using a non-zero bank will assume that it can trash that register
9541  bank, and will not save it.
9542  Since high-priority interrupts
9543 \begin_inset LatexCommand \index{interrupt priority}
9544
9545 \end_inset
9546
9547  can interrupt low-priority ones on the 8051 and friends, this means that
9548  if a high-priority ISR
9549 \emph on
9550 using
9551 \emph default
9552  a particular bank occurs while processing a low-priority ISR
9553 \emph on
9554 using
9555 \emph default
9556  the same bank, terrible and bad things can happen.
9557  To prevent this, no single register bank should be
9558 \emph on
9559 used
9560 \emph default
9561  by both a high priority and a low priority ISR.
9562  This is probably most easily done by having all high priority ISRs use
9563  one bank and all low priority ISRs use another.
9564  If you have an ISR which can change priority at runtime, you're on your
9565  own: I suggest using the default bank zero and taking the small performance
9566  hit.
9567 \layout Standard
9568
9569 It is most efficient if your ISR calls no other functions.
9570  If your ISR must call other functions, it is most efficient if those functions
9571  use the same bank as the ISR (see note 1 below); the next best is if the
9572  called functions use bank zero.
9573  It is very inefficient to call a function using a different, non-zero bank
9574  from an ISR.
9575
9576 \layout Section
9577
9578 Startup Code
9579 \begin_inset LatexCommand \label{sub:Startup-Code}
9580
9581 \end_inset
9582
9583
9584 \begin_inset LatexCommand \index{Startup code}
9585
9586 \end_inset
9587
9588
9589 \layout Subsection
9590
9591 MCS51/DS390 Startup Code
9592 \layout Standard
9593
9594 The compiler inserts a call to the C routine
9595 \emph on
9596 _sdcc_external_startup()
9597 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
9598
9599 \end_inset
9600
9601
9602 \series bold
9603 \emph default
9604
9605 \series default
9606 at the start of the CODE area.
9607  This routine is in the runtime library
9608 \begin_inset LatexCommand \index{Runtime library}
9609
9610 \end_inset
9611
9612 .
9613  By default this routine returns 0, if this routine returns a non-zero value,
9614  the static & global variable initialization will be skipped and the function
9615  main will be invoked.
9616  Otherwise static & global variables will be initialized before the function
9617  main is invoked.
9618  You could add a
9619 \emph on
9620 _sdcc_external_startup()
9621 \emph default
9622  routine to your program to override the default if you need to setup hardware
9623  or perform some other critical operation prior to static & global variable
9624  initialization.
9625  On some mcs51 variants xdata has to be explicitly enabled before it can
9626  be accessed, this is the place to do it.
9627  See also the compiler option
9628 \emph on
9629 -
9630 \begin_inset ERT
9631 status Collapsed
9632
9633 \layout Standard
9634
9635 \backslash
9636 /
9637 \end_inset
9638
9639 -no-xinit
9640 \emph default
9641 -
9642 \emph on
9643 opt
9644 \emph default
9645
9646 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
9647
9648 \end_inset
9649
9650  and section
9651 \begin_inset LatexCommand \ref{sub:MCS51-variants}
9652
9653 \end_inset
9654
9655 \SpecialChar ~
9656 about MCS51-variants.
9657 \layout Subsection
9658
9659 HC08 Startup Code
9660 \layout Standard
9661
9662 The HC08 startup code follows the same scheme as the MCS51 startup code.
9663 \layout Subsection
9664
9665 Z80 Startup Code
9666 \layout Standard
9667
9668 On the Z80 the startup code is inserted by linking with crt0.o which is generated
9669  from sdcc/device/lib/z80/crt0.s.
9670  If you need a different startup code you can use the compiler option
9671 \emph on
9672 -
9673 \series bold
9674 \emph default
9675
9676 \begin_inset ERT
9677 status Collapsed
9678
9679 \layout Standard
9680
9681 \backslash
9682 /
9683 \end_inset
9684
9685
9686 \series default
9687 \emph on
9688 -no-std-crt0
9689 \emph default
9690
9691 \begin_inset LatexCommand \index{-\/-no-std-crt0}
9692
9693 \end_inset
9694
9695  and provide your own crt0.o.
9696
9697 \layout Section
9698
9699 Inline Assembler Code
9700 \begin_inset LatexCommand \index{Assembler routines}
9701
9702 \end_inset
9703
9704
9705 \layout Subsection
9706
9707 A Step by Step Introduction
9708 \layout Standard
9709
9710 Starting from a small snippet of c-code this example shows for the MCS51
9711  how to use inline assembly, access variables, a function parameter and
9712  an array in xdata memory.
9713  This is a buffer routine which should be optimized:
9714 \layout Verse
9715
9716
9717 \family typewriter
9718 \size footnotesize
9719 unsigned char xdata at 0x7f00 buf[0x100];
9720 \newline
9721 unsigned char head,tail;
9722 \newline
9723
9724 \newline
9725 void to_buffer( unsigned char c )
9726 \newline
9727 {
9728 \newline
9729 \SpecialChar ~
9730 \SpecialChar ~
9731 \SpecialChar ~
9732 \SpecialChar ~
9733 if( head != tail-1 )
9734 \newline
9735 \SpecialChar ~
9736 \SpecialChar ~
9737 \SpecialChar ~
9738 \SpecialChar ~
9739 \SpecialChar ~
9740 \SpecialChar ~
9741 \SpecialChar ~
9742 \SpecialChar ~
9743 buf[ head++ ] = c;
9744 \newline
9745 }
9746 \layout Standard
9747
9748 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
9749  then a corresponding buffer.asm file is generated.
9750  We define a new function
9751 \family typewriter
9752 to_buffer_asm()
9753 \family default
9754  in file buffer.c in which we cut and paste the generated code, removing
9755  unwanted comments and some ':'.
9756  Then add
9757 \begin_inset Quotes sld
9758 \end_inset
9759
9760 _asm
9761 \begin_inset Quotes srd
9762 \end_inset
9763
9764  and
9765 \begin_inset Quotes sld
9766 \end_inset
9767
9768 _endasm;
9769 \begin_inset Quotes srd
9770 \end_inset
9771
9772  to the beginning and the end of the function body:
9773 \layout Verse
9774
9775
9776 \family typewriter
9777 \size footnotesize
9778 /* With a cut and paste from the .asm file, we have something to start with.
9779 \newline
9780 \SpecialChar ~
9781 \SpecialChar ~
9782 \SpecialChar ~
9783 The function is not yet OK! (registers aren't saved) */
9784 \newline
9785 void to_buffer_asm( unsigned char c )
9786 \newline
9787 {
9788 \newline
9789 \SpecialChar ~
9790 \SpecialChar ~
9791 \SpecialChar ~
9792 \SpecialChar ~
9793 _asm
9794 \begin_inset LatexCommand \index{\_asm}
9795
9796 \end_inset
9797
9798
9799 \newline
9800 \SpecialChar ~
9801 \SpecialChar ~
9802 \SpecialChar ~
9803 \SpecialChar ~
9804 mov\SpecialChar ~
9805 \SpecialChar ~
9806 r2,dpl
9807 \newline
9808 ;buffer.c if( head != tail-1 )
9809 \newline
9810 \SpecialChar ~
9811 \SpecialChar ~
9812 \SpecialChar ~
9813 \SpecialChar ~
9814 mov\SpecialChar ~
9815 \SpecialChar ~
9816 a,_tail
9817 \newline
9818 \SpecialChar ~
9819 \SpecialChar ~
9820 \SpecialChar ~
9821 \SpecialChar ~
9822 dec\SpecialChar ~
9823 \SpecialChar ~
9824 a
9825 \newline
9826 \SpecialChar ~
9827 \SpecialChar ~
9828 \SpecialChar ~
9829 \SpecialChar ~
9830 mov\SpecialChar ~
9831 \SpecialChar ~
9832 r3,a
9833 \newline
9834 \SpecialChar ~
9835 \SpecialChar ~
9836 \SpecialChar ~
9837 \SpecialChar ~
9838 mov\SpecialChar ~
9839 \SpecialChar ~
9840 a,_head
9841 \newline
9842 \SpecialChar ~
9843 \SpecialChar ~
9844 \SpecialChar ~
9845 \SpecialChar ~
9846 cjne a,ar3,00106$
9847 \newline
9848 ret 00106$:
9849 \newline
9850 ;buffer.c buf[ head++ ] = c;
9851 \newline
9852 \SpecialChar ~
9853 \SpecialChar ~
9854 \SpecialChar ~
9855 \SpecialChar ~
9856 mov\SpecialChar ~
9857 \SpecialChar ~
9858 r3,_head
9859 \newline
9860 \SpecialChar ~
9861 \SpecialChar ~
9862 \SpecialChar ~
9863 \SpecialChar ~
9864 inc\SpecialChar ~
9865 \SpecialChar ~
9866 _head
9867 \newline
9868 \SpecialChar ~
9869 \SpecialChar ~
9870 \SpecialChar ~
9871 \SpecialChar ~
9872 mov\SpecialChar ~
9873 \SpecialChar ~
9874 a,r3
9875 \newline
9876 \SpecialChar ~
9877 \SpecialChar ~
9878 \SpecialChar ~
9879 \SpecialChar ~
9880 add\SpecialChar ~
9881 \SpecialChar ~
9882 a,#_buf
9883 \newline
9884 \SpecialChar ~
9885 \SpecialChar ~
9886 \SpecialChar ~
9887 \SpecialChar ~
9888 mov\SpecialChar ~
9889 \SpecialChar ~
9890 dpl,a
9891 \newline
9892 \SpecialChar ~
9893 \SpecialChar ~
9894 \SpecialChar ~
9895 \SpecialChar ~
9896 clr\SpecialChar ~
9897 \SpecialChar ~
9898 a
9899 \newline
9900 \SpecialChar ~
9901 \SpecialChar ~
9902 \SpecialChar ~
9903 \SpecialChar ~
9904 addc\SpecialChar ~
9905 a,#(_buf >> 8)
9906 \newline
9907 \SpecialChar ~
9908 \SpecialChar ~
9909 \SpecialChar ~
9910 \SpecialChar ~
9911 mov\SpecialChar ~
9912 \SpecialChar ~
9913 dph,a
9914 \newline
9915 \SpecialChar ~
9916 \SpecialChar ~
9917 \SpecialChar ~
9918 \SpecialChar ~
9919 mov\SpecialChar ~
9920 \SpecialChar ~
9921 a,r2
9922 \newline
9923 \SpecialChar ~
9924 \SpecialChar ~
9925 \SpecialChar ~
9926 \SpecialChar ~
9927 movx @dptr,a
9928 \newline
9929 00103$:
9930 \newline
9931 \SpecialChar ~
9932 \SpecialChar ~
9933 \SpecialChar ~
9934 \SpecialChar ~
9935 ret
9936 \newline
9937 \SpecialChar ~
9938 \SpecialChar ~
9939 \SpecialChar ~
9940 \SpecialChar ~
9941 _endasm;
9942 \newline
9943 }
9944 \layout Standard
9945
9946 The new file buffer.c should compile with only one warning about the unreferenced
9947  function argument 'c'.
9948  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
9949  and finally have:
9950 \layout Verse
9951
9952
9953 \family typewriter
9954 \size footnotesize
9955 unsigned char xdata at 0x7f00 buf[0x100];
9956 \newline
9957 unsigned char head,tail;
9958 \newline
9959 #define USE_ASSEMBLY
9960 \newline
9961
9962 \newline
9963 #ifndef USE_ASSEMBLY
9964 \newline
9965 void to_buffer( unsigned char c )
9966 \newline
9967 {
9968 \newline
9969 \SpecialChar ~
9970 \SpecialChar ~
9971 \SpecialChar ~
9972 \SpecialChar ~
9973 if( head != tail-1 )
9974 \newline
9975 \SpecialChar ~
9976 \SpecialChar ~
9977 \SpecialChar ~
9978 \SpecialChar ~
9979 \SpecialChar ~
9980 \SpecialChar ~
9981 \SpecialChar ~
9982 \SpecialChar ~
9983 buf[ head++ ] = c;
9984 \newline
9985 }
9986 \newline
9987
9988 \newline
9989 #else
9990 \newline
9991
9992 \newline
9993 void to_buffer( unsigned char c )
9994 \newline
9995 {
9996 \newline
9997 \SpecialChar ~
9998 \SpecialChar ~
9999 \SpecialChar ~
10000 \SpecialChar ~
10001 c; // to avoid warning: unreferenced function argument
10002 \newline
10003 \SpecialChar ~
10004 \SpecialChar ~
10005 \SpecialChar ~
10006 \SpecialChar ~
10007 _asm
10008 \begin_inset LatexCommand \index{\_asm}
10009
10010 \end_inset
10011
10012
10013 \newline
10014 \SpecialChar ~
10015 \SpecialChar ~
10016 \SpecialChar ~
10017 \SpecialChar ~
10018 \SpecialChar ~
10019 \SpecialChar ~
10020 \SpecialChar ~
10021 \SpecialChar ~
10022 ; save used registers here.
10023
10024 \newline
10025 \SpecialChar ~
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 \SpecialChar ~
10029 \SpecialChar ~
10030 \SpecialChar ~
10031 \SpecialChar ~
10032 \SpecialChar ~
10033 ; If we were still using r2,r3 we would have to push them here.
10034
10035 \newline
10036 ; if( head != tail-1 )
10037 \newline
10038 \SpecialChar ~
10039 \SpecialChar ~
10040 \SpecialChar ~
10041 \SpecialChar ~
10042 \SpecialChar ~
10043 \SpecialChar ~
10044 \SpecialChar ~
10045 \SpecialChar ~
10046 mov\SpecialChar ~
10047  a,_tail
10048 \newline
10049 \SpecialChar ~
10050 \SpecialChar ~
10051 \SpecialChar ~
10052 \SpecialChar ~
10053 \SpecialChar ~
10054 \SpecialChar ~
10055 \SpecialChar ~
10056 \SpecialChar ~
10057 dec\SpecialChar ~
10058  a
10059 \newline
10060 \SpecialChar ~
10061 \SpecialChar ~
10062 \SpecialChar ~
10063 \SpecialChar ~
10064 \SpecialChar ~
10065 \SpecialChar ~
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 xrl\SpecialChar ~
10069  a,_head
10070 \newline
10071 \SpecialChar ~
10072 \SpecialChar ~
10073 \SpecialChar ~
10074 \SpecialChar ~
10075 \SpecialChar ~
10076 \SpecialChar ~
10077 \SpecialChar ~
10078 \SpecialChar ~
10079 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
10080 \newline
10081 \SpecialChar ~
10082 \SpecialChar ~
10083 \SpecialChar ~
10084 \SpecialChar ~
10085 \SpecialChar ~
10086 \SpecialChar ~
10087 \SpecialChar ~
10088 \SpecialChar ~
10089 jz\SpecialChar ~
10090 \SpecialChar ~
10091  t_b_end$
10092 \newline
10093 \SpecialChar ~
10094 \SpecialChar ~
10095 \SpecialChar ~
10096 \SpecialChar ~
10097 \SpecialChar ~
10098 \SpecialChar ~
10099 \SpecialChar ~
10100 \SpecialChar ~
10101 ;
10102 \newline
10103 ; buf[ head++ ] = c;
10104 \newline
10105 \SpecialChar ~
10106 \SpecialChar ~
10107 \SpecialChar ~
10108 \SpecialChar ~
10109 \SpecialChar ~
10110 \SpecialChar ~
10111 \SpecialChar ~
10112 \SpecialChar ~
10113 mov\SpecialChar ~
10114  a,dpl \SpecialChar ~
10115 \SpecialChar ~
10116 \SpecialChar ~
10117 \SpecialChar ~
10118 \SpecialChar ~
10119 \SpecialChar ~
10120 \SpecialChar ~
10121 ; dpl holds lower byte of function argument
10122 \newline
10123 \SpecialChar ~
10124 \SpecialChar ~
10125 \SpecialChar ~
10126 \SpecialChar ~
10127 \SpecialChar ~
10128 \SpecialChar ~
10129 \SpecialChar ~
10130 \SpecialChar ~
10131 mov\SpecialChar ~
10132  dpl,_head \SpecialChar ~
10133 \SpecialChar ~
10134 \SpecialChar ~
10135 ; buf is 0x100 byte aligned so head can be used directly
10136 \newline
10137 \SpecialChar ~
10138 \SpecialChar ~
10139 \SpecialChar ~
10140 \SpecialChar ~
10141 \SpecialChar ~
10142 \SpecialChar ~
10143 \SpecialChar ~
10144 \SpecialChar ~
10145 mov\SpecialChar ~
10146  dph,#(_buf>>8)
10147 \newline
10148 \SpecialChar ~
10149 \SpecialChar ~
10150 \SpecialChar ~
10151 \SpecialChar ~
10152 \SpecialChar ~
10153 \SpecialChar ~
10154 \SpecialChar ~
10155 \SpecialChar ~
10156 movx @dptr,a
10157 \newline
10158 \SpecialChar ~
10159 \SpecialChar ~
10160 \SpecialChar ~
10161 \SpecialChar ~
10162 \SpecialChar ~
10163 \SpecialChar ~
10164 \SpecialChar ~
10165 \SpecialChar ~
10166 inc \SpecialChar ~
10167 _head
10168 \newline
10169 \SpecialChar ~
10170 \SpecialChar ~
10171 \SpecialChar ~
10172 \SpecialChar ~
10173 \SpecialChar ~
10174 \SpecialChar ~
10175 \SpecialChar ~
10176 \SpecialChar ~
10177 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
10178 \newline
10179 t_b_end$:
10180 \newline
10181 \SpecialChar ~
10182 \SpecialChar ~
10183 \SpecialChar ~
10184 \SpecialChar ~
10185 \SpecialChar ~
10186 \SpecialChar ~
10187 \SpecialChar ~
10188 \SpecialChar ~
10189 ; restore used registers here
10190 \newline
10191 \SpecialChar ~
10192 \SpecialChar ~
10193 \SpecialChar ~
10194 \SpecialChar ~
10195 _endasm;
10196 \newline
10197 }
10198 \newline
10199 #endif
10200 \layout Standard
10201
10202 The inline assembler code can contain any valid code understood by the assembler
10203 , this includes any assembler directives and comment lines
10204 \begin_inset Foot
10205 collapsed false
10206
10207 \layout Standard
10208
10209 The assembler does not like some characters like ':' or ''' in comments.
10210 \end_inset
10211
10212 .
10213  The compiler does not do any validation of the code within the
10214 \family typewriter
10215 _asm
10216 \begin_inset LatexCommand \index{\_asm}
10217
10218 \end_inset
10219
10220  ...
10221  _endasm;
10222 \family default
10223  keyword pair.
10224  Specifically it will not know which registers are used and thus register
10225  pushing/popping
10226 \begin_inset LatexCommand \index{push/pop}
10227
10228 \end_inset
10229
10230  has to be done manually.
10231
10232 \layout Standard
10233
10234 It is strongly recommended that each assembly instruction (including labels)
10235  be placed in a separate line (as the example shows).
10236  When the -
10237 \begin_inset ERT
10238 status Collapsed
10239
10240 \layout Standard
10241
10242 \backslash
10243 /
10244 \end_inset
10245
10246 -
10247 \emph on
10248 peep-asm
10249 \begin_inset LatexCommand \index{-\/-peep-asm}
10250
10251 \end_inset
10252
10253
10254 \emph default
10255  command line option is used, the inline assembler code will be passed through
10256  the peephole optimizer
10257 \begin_inset LatexCommand \index{Peephole optimizer}
10258
10259 \end_inset
10260
10261 .
10262  There are only a few (if any) cases where this option makes sense, it might
10263  cause some unexpected changes in the inline assembler code.
10264  Please go through the peephole optimizer rules defined in file
10265 \emph on
10266 SDCCpeeph.def
10267 \emph default
10268  carefully before using this option.
10269 \layout Subsection
10270
10271 Naked Functions
10272 \begin_inset LatexCommand \label{sub:Naked-Functions}
10273
10274 \end_inset
10275
10276
10277 \begin_inset LatexCommand \index{Naked functions}
10278
10279 \end_inset
10280
10281
10282 \layout Standard
10283
10284 A special keyword may be associated with a function declaring it as
10285 \emph on
10286 _naked
10287 \begin_inset LatexCommand \index{\_naked}
10288
10289 \end_inset
10290
10291 .
10292
10293 \emph default
10294 The
10295 \emph on
10296 _naked
10297 \emph default
10298  function modifier attribute prevents the compiler from generating prologue
10299 \begin_inset LatexCommand \index{function prologue}
10300
10301 \end_inset
10302
10303  and epilogue
10304 \begin_inset LatexCommand \index{function epilogue}
10305
10306 \end_inset
10307
10308  code for that function.
10309  This means that the user is entirely responsible for such things as saving
10310  any registers that may need to be preserved, selecting the proper register
10311  bank, generating the
10312 \emph on
10313 return
10314 \emph default
10315  instruction at the end, etc.
10316  Practically, this means that the contents of the function must be written
10317  in inline assembler.
10318  This is particularly useful for interrupt functions, which can have a large
10319  (and often unnecessary) prologue/epilogue.
10320  For example, compare the code generated by these two functions:
10321 \layout Verse
10322
10323
10324 \family typewriter
10325 volatile
10326 \begin_inset LatexCommand \index{volatile}
10327
10328 \end_inset
10329
10330  data unsigned char counter;
10331 \newline
10332
10333 \newline
10334 void simpleInterrupt(void) interrupt
10335 \begin_inset LatexCommand \index{interrupt}
10336
10337 \end_inset
10338
10339  1
10340 \newline
10341 {
10342 \newline
10343 \SpecialChar ~
10344 \SpecialChar ~
10345 \SpecialChar ~
10346 \SpecialChar ~
10347 counter++;
10348 \newline
10349 }
10350 \newline
10351
10352 \newline
10353 void nakedInterrupt(void) interrupt 2 _naked
10354 \newline
10355 {
10356 \newline
10357 \SpecialChar ~
10358 \SpecialChar ~
10359 \SpecialChar ~
10360 \SpecialChar ~
10361 _asm
10362 \begin_inset LatexCommand \index{\_asm}
10363
10364 \end_inset
10365
10366
10367 \newline
10368 \SpecialChar ~
10369 \SpecialChar ~
10370 \SpecialChar ~
10371 \SpecialChar ~
10372 \SpecialChar ~
10373 \SpecialChar ~
10374 inc\SpecialChar ~
10375 \SpecialChar ~
10376 \SpecialChar ~
10377 \SpecialChar ~
10378 \SpecialChar ~
10379 _counter
10380 \newline
10381 \SpecialChar ~
10382 \SpecialChar ~
10383 \SpecialChar ~
10384 \SpecialChar ~
10385 \SpecialChar ~
10386 \SpecialChar ~
10387 reti\SpecialChar ~
10388 \SpecialChar ~
10389 \SpecialChar ~
10390 \SpecialChar ~
10391 ; MUST explicitly include ret or reti in _naked function.
10392 \newline
10393 \SpecialChar ~
10394 \SpecialChar ~
10395 \SpecialChar ~
10396 \SpecialChar ~
10397 _endasm
10398 \begin_inset LatexCommand \index{\_endasm}
10399
10400 \end_inset
10401
10402 ;
10403 \newline
10404 }
10405 \layout Standard
10406
10407 For an 8051 target, the generated simpleInterrupt looks like:
10408 \layout Verse
10409
10410
10411 \family typewriter
10412 _simpleInterrupt:
10413 \newline
10414 \SpecialChar ~
10415 \SpecialChar ~
10416 \SpecialChar ~
10417 \SpecialChar ~
10418 push\SpecialChar ~
10419 \SpecialChar ~
10420 \SpecialChar ~
10421 \SpecialChar ~
10422 acc
10423 \newline
10424 \SpecialChar ~
10425 \SpecialChar ~
10426 \SpecialChar ~
10427 \SpecialChar ~
10428 push\SpecialChar ~
10429 \SpecialChar ~
10430 \SpecialChar ~
10431 \SpecialChar ~
10432 b
10433 \newline
10434 \SpecialChar ~
10435 \SpecialChar ~
10436 \SpecialChar ~
10437 \SpecialChar ~
10438 push\SpecialChar ~
10439 \SpecialChar ~
10440 \SpecialChar ~
10441 \SpecialChar ~
10442 dpl
10443 \newline
10444 \SpecialChar ~
10445 \SpecialChar ~
10446 \SpecialChar ~
10447 \SpecialChar ~
10448 push\SpecialChar ~
10449 \SpecialChar ~
10450 \SpecialChar ~
10451 \SpecialChar ~
10452 dph
10453 \newline
10454 \SpecialChar ~
10455 \SpecialChar ~
10456 \SpecialChar ~
10457 \SpecialChar ~
10458 push\SpecialChar ~
10459 \SpecialChar ~
10460 \SpecialChar ~
10461 \SpecialChar ~
10462 psw
10463 \newline
10464 \SpecialChar ~
10465 \SpecialChar ~
10466 \SpecialChar ~
10467 \SpecialChar ~
10468 mov\SpecialChar ~
10469 \SpecialChar ~
10470 \SpecialChar ~
10471 \SpecialChar ~
10472 \SpecialChar ~
10473 psw,#0x00
10474 \newline
10475 \SpecialChar ~
10476 \SpecialChar ~
10477 \SpecialChar ~
10478 \SpecialChar ~
10479 inc\SpecialChar ~
10480 \SpecialChar ~
10481 \SpecialChar ~
10482 \SpecialChar ~
10483 \SpecialChar ~
10484 _counter
10485 \newline
10486 \SpecialChar ~
10487 \SpecialChar ~
10488 \SpecialChar ~
10489 \SpecialChar ~
10490 pop\SpecialChar ~
10491 \SpecialChar ~
10492 \SpecialChar ~
10493 \SpecialChar ~
10494 \SpecialChar ~
10495 psw
10496 \newline
10497 \SpecialChar ~
10498 \SpecialChar ~
10499 \SpecialChar ~
10500 \SpecialChar ~
10501 pop\SpecialChar ~
10502 \SpecialChar ~
10503 \SpecialChar ~
10504 \SpecialChar ~
10505 \SpecialChar ~
10506 dph
10507 \newline
10508 \SpecialChar ~
10509 \SpecialChar ~
10510 \SpecialChar ~
10511 \SpecialChar ~
10512 pop\SpecialChar ~
10513 \SpecialChar ~
10514 \SpecialChar ~
10515 \SpecialChar ~
10516 \SpecialChar ~
10517 dpl
10518 \newline
10519 \SpecialChar ~
10520 \SpecialChar ~
10521 \SpecialChar ~
10522 \SpecialChar ~
10523 pop\SpecialChar ~
10524 \SpecialChar ~
10525 \SpecialChar ~
10526 \SpecialChar ~
10527 \SpecialChar ~
10528 b
10529 \newline
10530 \SpecialChar ~
10531 \SpecialChar ~
10532 \SpecialChar ~
10533 \SpecialChar ~
10534 pop\SpecialChar ~
10535 \SpecialChar ~
10536 \SpecialChar ~
10537 \SpecialChar ~
10538 \SpecialChar ~
10539 acc
10540 \newline
10541 \SpecialChar ~
10542 \SpecialChar ~
10543 \SpecialChar ~
10544 \SpecialChar ~
10545 reti
10546 \layout Standard
10547
10548 whereas nakedInterrupt looks like:
10549 \layout Verse
10550
10551
10552 \family typewriter
10553 _nakedInterrupt:
10554 \newline
10555 \SpecialChar ~
10556 \SpecialChar ~
10557 \SpecialChar ~
10558 \SpecialChar ~
10559 inc\SpecialChar ~
10560 \SpecialChar ~
10561 \SpecialChar ~
10562 \SpecialChar ~
10563 _counter
10564 \newline
10565 \SpecialChar ~
10566 \SpecialChar ~
10567 \SpecialChar ~
10568 \SpecialChar ~
10569 reti\SpecialChar ~
10570 \SpecialChar ~
10571 \SpecialChar ~
10572 ; MUST explicitly include ret or reti in _naked function.
10573 \layout Standard
10574
10575 The #pragma directive EXCLUDE
10576 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
10577
10578 \end_inset
10579
10580  allows a more fine grained control over pushing & popping
10581 \begin_inset LatexCommand \index{push/pop}
10582
10583 \end_inset
10584
10585  the registers.
10586 \layout Standard
10587
10588 While there is nothing preventing you from writing C code inside a _naked
10589  function, there are many ways to shoot yourself in the foot doing this,
10590  and it is recommended that you stick to inline assembler.
10591 \layout Subsection
10592
10593 Use of Labels within Inline Assembler
10594 \layout Standard
10595
10596 SDCC allows the use of in-line assembler with a few restriction as regards
10597  labels.
10598  In older versions of the compiler all labels defined within inline assembler
10599  code
10600 \emph on
10601 had to be
10602 \emph default
10603  of the form
10604 \emph on
10605 nnnnn$
10606 \emph default
10607  where nnnn is a number less than 100 (which implies a limit of utmost 100
10608  inline assembler labels
10609 \emph on
10610 per function
10611 \emph default
10612 \noun on
10613 )
10614 \noun default
10615 .
10616
10617 \layout Verse
10618
10619
10620 \family typewriter
10621 _asm
10622 \begin_inset LatexCommand \index{\_asm}
10623
10624 \end_inset
10625
10626
10627 \newline
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 mov\SpecialChar ~
10633 \SpecialChar ~
10634 \SpecialChar ~
10635 \SpecialChar ~
10636 \SpecialChar ~
10637 b,#10
10638 \newline
10639 00001$:
10640 \newline
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 \SpecialChar ~
10645 djnz\SpecialChar ~
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 \SpecialChar ~
10649 b,00001$
10650 \newline
10651 _endasm
10652 \begin_inset LatexCommand \index{\_endasm}
10653
10654 \end_inset
10655
10656  ;
10657 \layout Standard
10658
10659 Inline assembler code cannot reference any C-Labels, however it can reference
10660  labels
10661 \begin_inset LatexCommand \index{Labels}
10662
10663 \end_inset
10664
10665  defined by the inline assembler, e.g.:
10666 \layout Verse
10667
10668
10669 \family typewriter
10670 foo() {
10671 \newline
10672 \SpecialChar ~
10673 \SpecialChar ~
10674 \SpecialChar ~
10675 \SpecialChar ~
10676 /* some c code */
10677 \newline
10678 \SpecialChar ~
10679 \SpecialChar ~
10680 \SpecialChar ~
10681 \SpecialChar ~
10682 _asm
10683 \newline
10684 \SpecialChar ~
10685 \SpecialChar ~
10686 \SpecialChar ~
10687 \SpecialChar ~
10688 \SpecialChar ~
10689 \SpecialChar ~
10690 ; some assembler code
10691 \newline
10692 \SpecialChar ~
10693 \SpecialChar ~
10694 \SpecialChar ~
10695 \SpecialChar ~
10696 \SpecialChar ~
10697 \SpecialChar ~
10698 ljmp $0003
10699 \newline
10700 \SpecialChar ~
10701 \SpecialChar ~
10702 \SpecialChar ~
10703 \SpecialChar ~
10704 _endasm;
10705 \newline
10706 \SpecialChar ~
10707 \SpecialChar ~
10708 \SpecialChar ~
10709 \SpecialChar ~
10710 /* some more c code */
10711 \newline
10712 clabel:\SpecialChar ~
10713 \SpecialChar ~
10714 /* inline assembler cannot reference this label */
10715 \newline
10716 \SpecialChar ~
10717 \SpecialChar ~
10718 \SpecialChar ~
10719 \SpecialChar ~
10720 _asm
10721 \newline
10722 \SpecialChar ~
10723 \SpecialChar ~
10724 \SpecialChar ~
10725 \SpecialChar ~
10726 $0003: ;label (can be reference by inline assembler only)
10727 \newline
10728 \SpecialChar ~
10729 \SpecialChar ~
10730 \SpecialChar ~
10731 \SpecialChar ~
10732 _endasm ;
10733 \newline
10734 \SpecialChar ~
10735 \SpecialChar ~
10736 \SpecialChar ~
10737 \SpecialChar ~
10738 /* some more c code */
10739 \newline
10740 }
10741 \layout Standard
10742
10743 In other words inline assembly code can access labels defined in inline
10744  assembly within the scope of the function.
10745  The same goes the other way, ie.
10746  labels defines in inline assembly can not be accessed by C statements.
10747 \layout Section
10748
10749 Interfacing with Assembler Code
10750 \begin_inset LatexCommand \index{Assembler routines}
10751
10752 \end_inset
10753
10754
10755 \layout Subsection
10756
10757 Global Registers used for Parameter Passing
10758 \begin_inset LatexCommand \index{Parameter passing}
10759
10760 \end_inset
10761
10762
10763 \layout Standard
10764
10765 The compiler always uses the global registers
10766 \emph on
10767 DPL, DPH
10768 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
10769
10770 \end_inset
10771
10772
10773 \begin_inset LatexCommand \index{DPTR}
10774
10775 \end_inset
10776
10777 , B
10778 \begin_inset LatexCommand \index{B (register)}
10779
10780 \end_inset
10781
10782
10783 \emph default
10784 and
10785 \emph on
10786  ACC
10787 \begin_inset LatexCommand \index{ACC}
10788
10789 \end_inset
10790
10791
10792 \emph default
10793  to pass the first parameter to a routine.
10794  The second parameter onwards is either allocated on the stack (for reentrant
10795  routines or if -
10796 \begin_inset ERT
10797 status Collapsed
10798
10799 \layout Standard
10800
10801 \backslash
10802 /
10803 \end_inset
10804
10805 -stack-auto is used) or in data / xdata memory (depending on the memory
10806  model).
10807
10808 \layout Subsection
10809
10810 Assembler Routine(non-reentrant
10811 \begin_inset LatexCommand \index{reentrant}
10812
10813 \end_inset
10814
10815 )
10816 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
10817
10818 \end_inset
10819
10820
10821 \layout Standard
10822
10823 In the following example the function c_func calls an assembler routine
10824  asm_func, which takes two parameters
10825 \begin_inset LatexCommand \index{function parameter}
10826
10827 \end_inset
10828
10829 .
10830 \layout Verse
10831
10832
10833 \family typewriter
10834 extern int asm_func(unsigned char, unsigned char);
10835 \newline
10836
10837 \newline
10838 int c_func (unsigned char i, unsigned char j)
10839 \newline
10840 {
10841 \newline
10842 \SpecialChar ~
10843 \SpecialChar ~
10844 \SpecialChar ~
10845 \SpecialChar ~
10846 return asm_func(i,j);
10847 \newline
10848 }
10849 \newline
10850
10851 \newline
10852 int main()
10853 \newline
10854 {
10855 \newline
10856 \SpecialChar ~
10857 \SpecialChar ~
10858 \SpecialChar ~
10859 \SpecialChar ~
10860 return c_func(10,9);
10861 \newline
10862 }
10863 \layout Standard
10864
10865 The corresponding assembler function is:
10866 \layout Verse
10867
10868
10869 \family typewriter
10870 .globl _asm_func_PARM_2
10871 \newline
10872 \SpecialChar ~
10873 \SpecialChar ~
10874 \SpecialChar ~
10875 \SpecialChar ~
10876 \SpecialChar ~
10877 \SpecialChar ~
10878 \SpecialChar ~
10879 \SpecialChar ~
10880 .globl _asm_func
10881 \newline
10882 \SpecialChar ~
10883 \SpecialChar ~
10884 \SpecialChar ~
10885 \SpecialChar ~
10886 \SpecialChar ~
10887 \SpecialChar ~
10888 \SpecialChar ~
10889 \SpecialChar ~
10890 .area OSEG
10891 \newline
10892 _asm_func_PARM_2:
10893 \newline
10894 \SpecialChar ~
10895 \SpecialChar ~
10896 \SpecialChar ~
10897 \SpecialChar ~
10898 \SpecialChar ~
10899 \SpecialChar ~
10900 \SpecialChar ~
10901 \SpecialChar ~
10902 .ds    1
10903 \newline
10904 \SpecialChar ~
10905 \SpecialChar ~
10906 \SpecialChar ~
10907 \SpecialChar ~
10908 \SpecialChar ~
10909 \SpecialChar ~
10910 \SpecialChar ~
10911 \SpecialChar ~
10912 .area CSEG
10913 \newline
10914 _asm_func:
10915 \newline
10916 \SpecialChar ~
10917 \SpecialChar ~
10918 \SpecialChar ~
10919 \SpecialChar ~
10920 \SpecialChar ~
10921 \SpecialChar ~
10922 \SpecialChar ~
10923 \SpecialChar ~
10924 mov    a,dpl
10925 \newline
10926 \SpecialChar ~
10927 \SpecialChar ~
10928 \SpecialChar ~
10929 \SpecialChar ~
10930 \SpecialChar ~
10931 \SpecialChar ~
10932 \SpecialChar ~
10933 \SpecialChar ~
10934 add    a,_asm_func_PARM_2
10935 \newline
10936 \SpecialChar ~
10937 \SpecialChar ~
10938 \SpecialChar ~
10939 \SpecialChar ~
10940 \SpecialChar ~
10941 \SpecialChar ~
10942 \SpecialChar ~
10943 \SpecialChar ~
10944 mov    dpl,a
10945 \newline
10946 \SpecialChar ~
10947 \SpecialChar ~
10948 \SpecialChar ~
10949 \SpecialChar ~
10950 \SpecialChar ~
10951 \SpecialChar ~
10952 \SpecialChar ~
10953 \SpecialChar ~
10954 mov\SpecialChar ~
10955 \SpecialChar ~
10956 \SpecialChar ~
10957 \SpecialChar ~
10958 dph
10959 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
10960
10961 \end_inset
10962
10963 ,#0x00
10964 \newline
10965 \SpecialChar ~
10966 \SpecialChar ~
10967 \SpecialChar ~
10968 \SpecialChar ~
10969 \SpecialChar ~
10970 \SpecialChar ~
10971 \SpecialChar ~
10972 \SpecialChar ~
10973 ret
10974 \layout Standard
10975
10976 Note here that the return values
10977 \begin_inset LatexCommand \index{return value}
10978
10979 \end_inset
10980
10981  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
10982  two byte values.
10983  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
10984 b' & 'acc' for four byte values.
10985 \layout Standard
10986
10987 The parameter naming convention is _<function_name>_PARM_<n>, where n is
10988  the parameter number starting from 1, and counting from the left.
10989  The first parameter is passed in
10990 \begin_inset Quotes eld
10991 \end_inset
10992
10993 dpl
10994 \begin_inset Quotes erd
10995 \end_inset
10996
10997  for One bye parameter,
10998 \begin_inset Quotes eld
10999 \end_inset
11000
11001 dptr
11002 \begin_inset Quotes erd
11003 \end_inset
11004
11005  if two bytes,
11006 \begin_inset Quotes eld
11007 \end_inset
11008
11009 b,dptr
11010 \begin_inset Quotes erd
11011 \end_inset
11012
11013  for three bytes and
11014 \begin_inset Quotes eld
11015 \end_inset
11016
11017 acc,b,dptr
11018 \begin_inset Quotes erd
11019 \end_inset
11020
11021  for four bytes, the variable name for the second parameter will be _<function_n
11022 ame>_PARM_2.
11023 \newline
11024
11025 \newline
11026 Assemble the assembler routine with the following command:
11027 \newline
11028
11029 \newline
11030
11031 \family sans
11032 \series bold
11033 asx8051 -losg asmfunc.asm
11034 \newline
11035
11036 \newline
11037
11038 \family default
11039 \series default
11040 Then compile and link the assembler routine to the C source file with the
11041  following command:
11042 \newline
11043
11044 \newline
11045
11046 \family sans
11047 \series bold
11048 sdcc cfunc.c asmfunc.rel
11049 \layout Subsection
11050
11051 Assembler Routine(reentrant
11052 \begin_inset LatexCommand \index{reentrant}
11053
11054 \end_inset
11055
11056 )
11057 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
11058
11059 \end_inset
11060
11061
11062 \layout Standard
11063
11064 In this case the second parameter
11065 \begin_inset LatexCommand \index{function parameter}
11066
11067 \end_inset
11068
11069  onwards will be passed on the stack, the parameters are pushed from right
11070  to left i.e.
11071  after the call the left most parameter will be on the top of the stack.
11072  Here is an example:
11073 \layout Verse
11074
11075
11076 \family typewriter
11077 extern int asm_func(unsigned char, unsigned char);
11078 \newline
11079
11080 \newline
11081 int c_func (unsigned char i, unsigned char j) reentrant
11082 \newline
11083 {
11084 \newline
11085 \SpecialChar ~
11086 \SpecialChar ~
11087 \SpecialChar ~
11088 \SpecialChar ~
11089 return asm_func(i,j);
11090 \newline
11091 }
11092 \newline
11093
11094 \newline
11095 int main()
11096 \newline
11097 {
11098 \newline
11099 \SpecialChar ~
11100 \SpecialChar ~
11101 \SpecialChar ~
11102 \SpecialChar ~
11103 return c_func(10,9);
11104 \newline
11105 }
11106 \layout Standard
11107
11108 The corresponding assembler routine is:
11109 \layout Verse
11110
11111
11112 \family typewriter
11113 .globl _asm_func
11114 \newline
11115 _asm_func:
11116 \newline
11117 \SpecialChar ~
11118 \SpecialChar ~
11119 \SpecialChar ~
11120 \SpecialChar ~
11121 push  _bp
11122 \newline
11123 \SpecialChar ~
11124 \SpecialChar ~
11125 \SpecialChar ~
11126 \SpecialChar ~
11127 mov _bp,sp
11128 \newline
11129 \SpecialChar ~
11130 \SpecialChar ~
11131 \SpecialChar ~
11132 \SpecialChar ~
11133 mov  r2,dpl
11134 \newline
11135 \SpecialChar ~
11136 \SpecialChar ~
11137 \SpecialChar ~
11138 \SpecialChar ~
11139 mov  a,_bp
11140 \newline
11141 \SpecialChar ~
11142 \SpecialChar ~
11143 \SpecialChar ~
11144 \SpecialChar ~
11145 clr  c
11146 \newline
11147 \SpecialChar ~
11148 \SpecialChar ~
11149 \SpecialChar ~
11150 \SpecialChar ~
11151 add  a,#0xfd
11152 \newline
11153 \SpecialChar ~
11154 \SpecialChar ~
11155 \SpecialChar ~
11156 \SpecialChar ~
11157 mov  r0,a
11158 \newline
11159 \SpecialChar ~
11160 \SpecialChar ~
11161 \SpecialChar ~
11162 \SpecialChar ~
11163 add  a,#0xfc
11164 \newline
11165 \SpecialChar ~
11166 \SpecialChar ~
11167 \SpecialChar ~
11168 \SpecialChar ~
11169 mov  r1,a
11170 \newline
11171 \SpecialChar ~
11172 \SpecialChar ~
11173 \SpecialChar ~
11174 \SpecialChar ~
11175 mov  a,@r0
11176 \newline
11177 \SpecialChar ~
11178 \SpecialChar ~
11179 \SpecialChar ~
11180 \SpecialChar ~
11181 add  a,r2
11182 \newline
11183 \SpecialChar ~
11184 \SpecialChar ~
11185 \SpecialChar ~
11186 \SpecialChar ~
11187 mov  dpl,a
11188 \newline
11189 \SpecialChar ~
11190 \SpecialChar ~
11191 \SpecialChar ~
11192 \SpecialChar ~
11193 mov  dph,#0x00
11194 \newline
11195 \SpecialChar ~
11196 \SpecialChar ~
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 mov  sp,_bp
11200 \newline
11201 \SpecialChar ~
11202 \SpecialChar ~
11203 \SpecialChar ~
11204 \SpecialChar ~
11205 pop  _bp
11206 \newline
11207 \SpecialChar ~
11208 \SpecialChar ~
11209 \SpecialChar ~
11210 \SpecialChar ~
11211 ret
11212 \layout Standard
11213
11214 The compiling and linking procedure remains the same, however note the extra
11215  entry & exit linkage required for the assembler code, _bp is the stack
11216  frame pointer and is used to compute the offset into the stack for parameters
11217  and local variables.
11218 \layout Section
11219
11220 int (16 bit)
11221 \begin_inset LatexCommand \index{int (16 bit)}
11222
11223 \end_inset
11224
11225  and long (32 bit)
11226 \begin_inset LatexCommand \index{long (32 bit)}
11227
11228 \end_inset
11229
11230  Support
11231 \layout Standard
11232
11233 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
11234  multiplication and modulus operations are implemented by support routines.
11235  These support routines are all developed in ANSI-C to facilitate porting
11236  to other MCUs, although some model specific assembler optimizations are
11237  used.
11238  The following files contain the described routines, all of them can be
11239  found in <installdir>/share/sdcc/lib.
11240 \newline
11241
11242 \layout Standard
11243 \align center
11244
11245 \begin_inset  Tabular
11246 <lyxtabular version="3" rows="11" columns="2">
11247 <features>
11248 <column alignment="center" valignment="top" leftline="true" width="0">
11249 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
11250 <row topline="true" bottomline="true">
11251 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11252 \begin_inset Text
11253
11254 \layout Standard
11255
11256
11257 \series bold
11258 Function
11259 \end_inset
11260 </cell>
11261 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11262 \begin_inset Text
11263
11264 \layout Standard
11265
11266
11267 \series bold
11268 Description
11269 \end_inset
11270 </cell>
11271 </row>
11272 <row topline="true">
11273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11274 \begin_inset Text
11275
11276 \layout Standard
11277
11278 _mulint.c
11279 \end_inset
11280 </cell>
11281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11282 \begin_inset Text
11283
11284 \layout Standard
11285
11286 16 bit multiplication
11287 \end_inset
11288 </cell>
11289 </row>
11290 <row topline="true">
11291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11292 \begin_inset Text
11293
11294 \layout Standard
11295
11296 _divsint.c
11297 \end_inset
11298 </cell>
11299 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11300 \begin_inset Text
11301
11302 \layout Standard
11303
11304  signed 16 bit division (calls _divuint)
11305 \end_inset
11306 </cell>
11307 </row>
11308 <row topline="true">
11309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11310 \begin_inset Text
11311
11312 \layout Standard
11313
11314 _divuint.c
11315 \end_inset
11316 </cell>
11317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11318 \begin_inset Text
11319
11320 \layout Standard
11321
11322  unsigned 16 bit division
11323 \end_inset
11324 </cell>
11325 </row>
11326 <row topline="true">
11327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11328 \begin_inset Text
11329
11330 \layout Standard
11331
11332 _modsint.c
11333 \end_inset
11334 </cell>
11335 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11336 \begin_inset Text
11337
11338 \layout Standard
11339
11340 signed 16 bit modulus (calls _moduint)
11341 \end_inset
11342 </cell>
11343 </row>
11344 <row topline="true">
11345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11346 \begin_inset Text
11347
11348 \layout Standard
11349
11350 _moduint.c
11351 \end_inset
11352 </cell>
11353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11354 \begin_inset Text
11355
11356 \layout Standard
11357
11358 unsigned 16 bit modulus
11359 \end_inset
11360 </cell>
11361 </row>
11362 <row topline="true">
11363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11364 \begin_inset Text
11365
11366 \layout Standard
11367
11368 _mullong.c
11369 \end_inset
11370 </cell>
11371 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11372 \begin_inset Text
11373
11374 \layout Standard
11375
11376 32 bit multiplication
11377 \end_inset
11378 </cell>
11379 </row>
11380 <row topline="true">
11381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11382 \begin_inset Text
11383
11384 \layout Standard
11385
11386 _divslong.c
11387 \end_inset
11388 </cell>
11389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11390 \begin_inset Text
11391
11392 \layout Standard
11393
11394  signed 32 division (calls _divulong)
11395 \end_inset
11396 </cell>
11397 </row>
11398 <row topline="true">
11399 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11400 \begin_inset Text
11401
11402 \layout Standard
11403
11404 _divulong.c
11405 \end_inset
11406 </cell>
11407 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11408 \begin_inset Text
11409
11410 \layout Standard
11411
11412 unsigned 32 division
11413 \end_inset
11414 </cell>
11415 </row>
11416 <row topline="true">
11417 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11418 \begin_inset Text
11419
11420 \layout Standard
11421
11422 _modslong.c
11423 \end_inset
11424 </cell>
11425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11426 \begin_inset Text
11427
11428 \layout Standard
11429
11430  signed 32 bit modulus (calls _modulong)
11431 \end_inset
11432 </cell>
11433 </row>
11434 <row topline="true" bottomline="true">
11435 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11436 \begin_inset Text
11437
11438 \layout Standard
11439
11440 _modulong.c
11441 \end_inset
11442 </cell>
11443 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11444 \begin_inset Text
11445
11446 \layout Standard
11447
11448 unsigned 32 bit modulus
11449 \end_inset
11450 </cell>
11451 </row>
11452 </lyxtabular>
11453
11454 \end_inset
11455
11456
11457 \newline
11458
11459 \layout Standard
11460
11461 Since they are compiled as
11462 \emph on
11463 non-reentrant
11464 \emph default
11465
11466 \begin_inset LatexCommand \index{reentrant}
11467
11468 \end_inset
11469
11470 , interrupt
11471 \begin_inset LatexCommand \index{interrupt}
11472
11473 \end_inset
11474
11475  service routines should not do any of the above operations.
11476  If this is unavoidable then the above routines will need to be compiled
11477  with the
11478 \emph on
11479 -
11480 \begin_inset ERT
11481 status Collapsed
11482
11483 \layout Standard
11484
11485 \backslash
11486 /
11487 \end_inset
11488
11489 -stack-auto
11490 \begin_inset LatexCommand \index{-\/-stack-auto}
11491
11492 \end_inset
11493
11494
11495 \emph default
11496  option, after which the source program will have to be compiled with
11497 \emph on
11498 -
11499 \begin_inset ERT
11500 status Collapsed
11501
11502 \layout Standard
11503
11504 \backslash
11505 /
11506 \end_inset
11507
11508 -int-long-reent
11509 \begin_inset LatexCommand \index{-\/-int-long-reent}
11510
11511 \end_inset
11512
11513
11514 \emph default
11515  option.
11516  Notice that you don't have to call this routines directly.
11517  The compiler will use them automatically every time an integer operation
11518  is required.
11519 \layout Section
11520
11521 Floating Point Support
11522 \begin_inset LatexCommand \index{Floating point support}
11523
11524 \end_inset
11525
11526
11527 \layout Standard
11528
11529 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
11530  floating point support routines are derived from gcc's floatlib.c and consist
11531  of the following routines:
11532 \newline
11533
11534 \layout Standard
11535 \align center
11536
11537 \size footnotesize
11538
11539 \begin_inset  Tabular
11540 <lyxtabular version="3" rows="17" columns="2">
11541 <features>
11542 <column alignment="center" valignment="top" leftline="true" width="0">
11543 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
11544 <row topline="true" bottomline="true">
11545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11546 \begin_inset Text
11547
11548 \layout Standard
11549
11550
11551 \family roman
11552 \series medium
11553 \shape up
11554 \size normal
11555 \emph off
11556 \bar no
11557 \noun off
11558 \color none
11559 Function
11560 \end_inset
11561 </cell>
11562 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11563 \begin_inset Text
11564
11565 \layout Standard
11566
11567 Description
11568 \end_inset
11569 </cell>
11570 </row>
11571 <row topline="true">
11572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11573 \begin_inset Text
11574
11575 \layout Standard
11576
11577
11578 \family roman
11579 \series medium
11580 \shape up
11581 \size normal
11582 \emph off
11583 \bar no
11584 \noun off
11585 \color none
11586 _fsadd.c
11587 \end_inset
11588 </cell>
11589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11590 \begin_inset Text
11591
11592 \layout Standard
11593
11594
11595 \family roman
11596 \series medium
11597 \shape up
11598 \size normal
11599 \emph off
11600 \bar no
11601 \noun off
11602 \color none
11603 add floating point numbers
11604 \end_inset
11605 </cell>
11606 </row>
11607 <row topline="true">
11608 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11609 \begin_inset Text
11610
11611 \layout Standard
11612
11613
11614 \family roman
11615 \series medium
11616 \shape up
11617 \size normal
11618 \emph off
11619 \bar no
11620 \noun off
11621 \color none
11622 _fssub.c
11623 \end_inset
11624 </cell>
11625 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11626 \begin_inset Text
11627
11628 \layout Standard
11629
11630
11631 \family roman
11632 \series medium
11633 \shape up
11634 \size normal
11635 \emph off
11636 \bar no
11637 \noun off
11638 \color none
11639 subtract floating point numbers
11640 \end_inset
11641 </cell>
11642 </row>
11643 <row topline="true">
11644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11645 \begin_inset Text
11646
11647 \layout Standard
11648
11649
11650 \family roman
11651 \series medium
11652 \shape up
11653 \size normal
11654 \emph off
11655 \bar no
11656 \noun off
11657 \color none
11658 _fsdiv.c
11659 \end_inset
11660 </cell>
11661 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11662 \begin_inset Text
11663
11664 \layout Standard
11665
11666
11667 \family roman
11668 \series medium
11669 \shape up
11670 \size normal
11671 \emph off
11672 \bar no
11673 \noun off
11674 \color none
11675 divide floating point numbers
11676 \end_inset
11677 </cell>
11678 </row>
11679 <row topline="true">
11680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11681 \begin_inset Text
11682
11683 \layout Standard
11684
11685
11686 \family roman
11687 \series medium
11688 \shape up
11689 \size normal
11690 \emph off
11691 \bar no
11692 \noun off
11693 \color none
11694 _fsmul.c
11695 \end_inset
11696 </cell>
11697 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11698 \begin_inset Text
11699
11700 \layout Standard
11701
11702
11703 \family roman
11704 \series medium
11705 \shape up
11706 \size normal
11707 \emph off
11708 \bar no
11709 \noun off
11710 \color none
11711 multiply floating point numbers
11712 \end_inset
11713 </cell>
11714 </row>
11715 <row topline="true">
11716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11717 \begin_inset Text
11718
11719 \layout Standard
11720
11721
11722 \family roman
11723 \series medium
11724 \shape up
11725 \size normal
11726 \emph off
11727 \bar no
11728 \noun off
11729 \color none
11730 _fs2uchar.c
11731 \end_inset
11732 </cell>
11733 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11734 \begin_inset Text
11735
11736 \layout Standard
11737
11738
11739 \family roman
11740 \series medium
11741 \shape up
11742 \size normal
11743 \emph off
11744 \bar no
11745 \noun off
11746 \color none
11747 convert floating point to unsigned char
11748 \end_inset
11749 </cell>
11750 </row>
11751 <row topline="true">
11752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11753 \begin_inset Text
11754
11755 \layout Standard
11756
11757
11758 \family roman
11759 \series medium
11760 \shape up
11761 \size normal
11762 \emph off
11763 \bar no
11764 \noun off
11765 \color none
11766 _fs2char.c
11767 \end_inset
11768 </cell>
11769 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11770 \begin_inset Text
11771
11772 \layout Standard
11773
11774
11775 \family roman
11776 \series medium
11777 \shape up
11778 \size normal
11779 \emph off
11780 \bar no
11781 \noun off
11782 \color none
11783 convert floating point to signed char
11784 \end_inset
11785 </cell>
11786 </row>
11787 <row topline="true">
11788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11789 \begin_inset Text
11790
11791 \layout Standard
11792
11793
11794 \family roman
11795 \series medium
11796 \shape up
11797 \size normal
11798 \emph off
11799 \bar no
11800 \noun off
11801 \color none
11802 _fs2uint.c
11803 \end_inset
11804 </cell>
11805 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11806 \begin_inset Text
11807
11808 \layout Standard
11809
11810
11811 \family roman
11812 \series medium
11813 \shape up
11814 \size normal
11815 \emph off
11816 \bar no
11817 \noun off
11818 \color none
11819 convert floating point to unsigned int
11820 \end_inset
11821 </cell>
11822 </row>
11823 <row topline="true">
11824 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11825 \begin_inset Text
11826
11827 \layout Standard
11828
11829
11830 \family roman
11831 \series medium
11832 \shape up
11833 \size normal
11834 \emph off
11835 \bar no
11836 \noun off
11837 \color none
11838 _fs2int.c
11839 \end_inset
11840 </cell>
11841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11842 \begin_inset Text
11843
11844 \layout Standard
11845
11846
11847 \family roman
11848 \series medium
11849 \shape up
11850 \size normal
11851 \emph off
11852 \bar no
11853 \noun off
11854 \color none
11855 convert floating point to signed int
11856 \end_inset
11857 </cell>
11858 </row>
11859 <row topline="true">
11860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11861 \begin_inset Text
11862
11863 \layout Standard
11864
11865
11866 \family roman
11867 \series medium
11868 \shape up
11869 \size normal
11870 \emph off
11871 \bar no
11872 \noun off
11873 \color none
11874 _fs2ulong.
11875 \family default
11876 \series default
11877 \shape default
11878 \size default
11879 \emph default
11880 \bar default
11881 \noun default
11882 \color default
11883 c
11884 \end_inset
11885 </cell>
11886 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11887 \begin_inset Text
11888
11889 \layout Standard
11890
11891
11892 \family roman
11893 \series medium
11894 \shape up
11895 \size normal
11896 \emph off
11897 \bar no
11898 \noun off
11899 \color none
11900 convert floating point to unsigned long
11901 \end_inset
11902 </cell>
11903 </row>
11904 <row topline="true">
11905 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11906 \begin_inset Text
11907
11908 \layout Standard
11909
11910
11911 \family roman
11912 \series medium
11913 \shape up
11914 \size normal
11915 \emph off
11916 \bar no
11917 \noun off
11918 \color none
11919 _fs2long.c
11920 \end_inset
11921 </cell>
11922 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11923 \begin_inset Text
11924
11925 \layout Standard
11926
11927
11928 \family roman
11929 \series medium
11930 \shape up
11931 \size normal
11932 \emph off
11933 \bar no
11934 \noun off
11935 \color none
11936 convert floating point to signed long
11937 \end_inset
11938 </cell>
11939 </row>
11940 <row topline="true">
11941 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11942 \begin_inset Text
11943
11944 \layout Standard
11945
11946
11947 \family roman
11948 \series medium
11949 \shape up
11950 \size normal
11951 \emph off
11952 \bar no
11953 \noun off
11954 \color none
11955 _uchar2fs.c
11956 \end_inset
11957 </cell>
11958 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11959 \begin_inset Text
11960
11961 \layout Standard
11962
11963
11964 \family roman
11965 \series medium
11966 \shape up
11967 \size normal
11968 \emph off
11969 \bar no
11970 \noun off
11971 \color none
11972 convert unsigned char to floating point
11973 \end_inset
11974 </cell>
11975 </row>
11976 <row topline="true">
11977 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11978 \begin_inset Text
11979
11980 \layout Standard
11981
11982
11983 \family roman
11984 \series medium
11985 \shape up
11986 \size normal
11987 \emph off
11988 \bar no
11989 \noun off
11990 \color none
11991 _char2fs.c
11992 \end_inset
11993 </cell>
11994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11995 \begin_inset Text
11996
11997 \layout Standard
11998
11999
12000 \family roman
12001 \series medium
12002 \shape up
12003 \size normal
12004 \emph off
12005 \bar no
12006 \noun off
12007 \color none
12008 convert char to floating point number
12009 \end_inset
12010 </cell>
12011 </row>
12012 <row topline="true">
12013 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12014 \begin_inset Text
12015
12016 \layout Standard
12017
12018
12019 \family roman
12020 \series medium
12021 \shape up
12022 \size normal
12023 \emph off
12024 \bar no
12025 \noun off
12026 \color none
12027 _uint2fs.c
12028 \end_inset
12029 </cell>
12030 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12031 \begin_inset Text
12032
12033 \layout Standard
12034
12035
12036 \family roman
12037 \series medium
12038 \shape up
12039 \size normal
12040 \emph off
12041 \bar no
12042 \noun off
12043 \color none
12044 convert unsigned int to floating point
12045 \end_inset
12046 </cell>
12047 </row>
12048 <row topline="true">
12049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12050 \begin_inset Text
12051
12052 \layout Standard
12053
12054
12055 \family roman
12056 \series medium
12057 \shape up
12058 \size normal
12059 \emph off
12060 \bar no
12061 \noun off
12062 \color none
12063 _int2fs.c
12064 \end_inset
12065 </cell>
12066 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12067 \begin_inset Text
12068
12069 \layout Standard
12070
12071
12072 \family roman
12073 \series medium
12074 \shape up
12075 \size normal
12076 \emph off
12077 \bar no
12078 \noun off
12079 \color none
12080 convert int to floating point numbers
12081 \end_inset
12082 </cell>
12083 </row>
12084 <row topline="true">
12085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12086 \begin_inset Text
12087
12088 \layout Standard
12089
12090
12091 \family roman
12092 \series medium
12093 \shape up
12094 \size normal
12095 \emph off
12096 \bar no
12097 \noun off
12098 \color none
12099 _ulong2fs.c
12100 \end_inset
12101 </cell>
12102 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12103 \begin_inset Text
12104
12105 \layout Standard
12106
12107
12108 \family roman
12109 \series medium
12110 \shape up
12111 \size normal
12112 \emph off
12113 \bar no
12114 \noun off
12115 \color none
12116 convert unsigned long to floating point number
12117 \end_inset
12118 </cell>
12119 </row>
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 \family roman
12128 \series medium
12129 \shape up
12130 \size normal
12131 \emph off
12132 \bar no
12133 \noun off
12134 \color none
12135 _long2fs.c
12136 \end_inset
12137 </cell>
12138 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12139 \begin_inset Text
12140
12141 \layout Standard
12142
12143
12144 \family roman
12145 \series medium
12146 \shape up
12147 \size normal
12148 \emph off
12149 \bar no
12150 \noun off
12151 \color none
12152 convert long to floating point number
12153 \end_inset
12154 </cell>
12155 </row>
12156 </lyxtabular>
12157
12158 \end_inset
12159
12160
12161 \newline
12162
12163 \layout Standard
12164
12165 Note if all these routines are used simultaneously the data space might
12166  overflow.
12167  For serious floating point usage it is strongly recommended that the large
12168  model be used.
12169  Also notice that you don't have to call this routines directly.
12170  The compiler will use them automatically every time a floating point operation
12171  is required.
12172 \layout Section
12173
12174 MCS51 Memory Models
12175 \begin_inset LatexCommand \index{Memory model}
12176
12177 \end_inset
12178
12179
12180 \begin_inset LatexCommand \index{MCS51 memory}
12181
12182 \end_inset
12183
12184
12185 \layout Standard
12186
12187 SDCC allows two memory models for MCS51 code,
12188 \shape slanted
12189 small
12190 \shape default
12191  and
12192 \shape slanted
12193 large
12194 \shape default
12195 .
12196  Modules compiled with different memory models should
12197 \emph on
12198 never
12199 \emph default
12200  be combined together or the results would be unpredictable.
12201  The library routines supplied with the compiler are compiled as both small
12202  and large.
12203  The compiled library modules are contained in separate directories as small
12204  and large so that you can link to either set.
12205
12206 \layout Standard
12207
12208 When the large model is used all variables declared without a storage class
12209  will be allocated into the external ram, this includes all parameters and
12210  local variables (for non-reentrant
12211 \begin_inset LatexCommand \index{reentrant}
12212
12213 \end_inset
12214
12215  functions).
12216  When the small model is used variables without storage class are allocated
12217  in the internal ram.
12218 \layout Standard
12219
12220 Judicious usage of the processor specific storage classes
12221 \begin_inset LatexCommand \index{Storage class}
12222
12223 \end_inset
12224
12225  and the 'reentrant' function type will yield much more efficient code,
12226  than using the large model.
12227  Several optimizations are disabled when the program is compiled using the
12228  large model, it is therefore strongly recommended that the small model
12229  be used unless absolutely required.
12230 \layout Section
12231
12232 DS390 Memory Models
12233 \begin_inset LatexCommand \index{Memory model}
12234
12235 \end_inset
12236
12237
12238 \begin_inset LatexCommand \index{DS390 memory model}
12239
12240 \end_inset
12241
12242
12243 \layout Standard
12244
12245 The only model supported is Flat 24
12246 \begin_inset LatexCommand \index{Flat 24 (memory model)}
12247
12248 \end_inset
12249
12250 .
12251  This generates code for the 24 bit contiguous addressing mode of the Dallas
12252  DS80C390 part.
12253  In this mode, up to four meg of external RAM or code space can be directly
12254  addressed.
12255  See the data sheets at www.dalsemi.com for further information on this part.
12256 \newline
12257
12258 \newline
12259 Note that the compiler does not generate any code to place the processor
12260  into 24 bitmode (although
12261 \emph on
12262 tinibios
12263 \emph default
12264  in the ds390 libraries will do that for you).
12265  If you don't use
12266 \emph on
12267 tinibios
12268 \emph default
12269
12270 \begin_inset LatexCommand \index{Tinibios (DS390)}
12271
12272 \end_inset
12273
12274 , the boot loader or similar code must ensure that the processor is in 24
12275  bit contiguous addressing mode before calling the SDCC startup code.
12276 \newline
12277
12278 \newline
12279 Like the
12280 \emph on
12281 -
12282 \begin_inset ERT
12283 status Collapsed
12284
12285 \layout Standard
12286
12287 \backslash
12288 /
12289 \end_inset
12290
12291 -model-large
12292 \emph default
12293  option, variables will by default be placed into the XDATA segment.
12294
12295 \newline
12296
12297 \newline
12298 Segments may be placed anywhere in the 4 meg address space using the usual
12299  -
12300 \begin_inset ERT
12301 status Collapsed
12302
12303 \layout Standard
12304
12305 \backslash
12306 /
12307 \end_inset
12308
12309 -*-loc options.
12310  Note that if any segments are located above 64K, the -r flag must be passed
12311  to the linker to generate the proper segment relocations, and the Intel
12312  HEX output format must be used.
12313  The -r flag can be passed to the linker by using the option
12314 \emph on
12315 -Wl-r
12316 \emph default
12317  on the SDCC command line.
12318  However, currently the linker can not handle code segments > 64k.
12319 \layout Section
12320
12321 Pragmas
12322 \begin_inset LatexCommand \index{Pragmas}
12323
12324 \end_inset
12325
12326
12327 \layout Standard
12328
12329 SDCC supports the following #pragma directives.
12330 \layout Itemize
12331
12332 SAVE
12333 \begin_inset LatexCommand \index{\#pragma SAVE}
12334
12335 \end_inset
12336
12337  - this will save all current options to the SAVE/RESTORE stack.
12338  See RESTORE.
12339 \layout Itemize
12340
12341 RESTORE
12342 \begin_inset LatexCommand \index{\#pragma RESTORE}
12343
12344 \end_inset
12345
12346  - will restore saved options from the last save.
12347  SAVEs & RESTOREs can be nested.
12348  SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
12349  RESTORE pulls current options from the stack.
12350  See SAVE.
12351 \layout Itemize
12352
12353 NOGCSE
12354 \begin_inset LatexCommand \index{\#pragma NOGCSE}
12355
12356 \end_inset
12357
12358  - will stop global common subexpression elimination.
12359 \layout Itemize
12360
12361 NOINDUCTION
12362 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
12363
12364 \end_inset
12365
12366  - will stop loop induction optimizations.
12367 \layout Itemize
12368
12369 NOJTBOUND
12370 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
12371
12372 \end_inset
12373
12374  - will not generate code for boundary value checking, when switch statements
12375  are turned into jump-tables (dangerous).
12376  For more details see section
12377 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
12378
12379 \end_inset
12380
12381 .
12382 \layout Itemize
12383
12384 NOOVERLAY
12385 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
12386
12387 \end_inset
12388
12389  - the compiler will not overlay the parameters and local variables of a
12390  function.
12391 \layout Itemize
12392
12393 LESS_PEDANTIC
12394 \begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
12395
12396 \end_inset
12397
12398  - the compiler will not warn you anymore for obvious mistakes, you'r on
12399  your own now ;-(
12400 \layout Itemize
12401
12402 NOLOOPREVERSE
12403 \begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
12404
12405 \end_inset
12406
12407  - Will not do loop reversal optimization
12408 \layout Itemize
12409
12410 EXCLUDE
12411 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
12412
12413 \end_inset
12414
12415  NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
12416  pair of push/pop
12417 \begin_inset LatexCommand \index{push/pop}
12418
12419 \end_inset
12420
12421  instruction in ISR function (using interrupt
12422 \begin_inset LatexCommand \index{interrupt}
12423
12424 \end_inset
12425
12426  keyword).
12427  The directive should be placed immediately before the ISR function definition
12428  and it affects ALL ISR functions following it.
12429  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
12430 EXCLUDE\SpecialChar ~
12431 none
12432 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
12433
12434 \end_inset
12435
12436 .
12437 \layout Itemize
12438
12439 NOIV
12440 \begin_inset LatexCommand \index{\#pragma NOIV}
12441
12442 \end_inset
12443
12444  - Do not generate interrupt vector table entries for all ISR functions
12445  defined after the pragma.
12446  This is useful in cases where the interrupt vector table must be defined
12447  manually, or when there is a secondary, manually defined interrupt vector
12448  table (e.g.
12449  for the autovector feature of the Cypress EZ-USB FX2).
12450  More elegantly this can be achieved by obmitting the optional interrupt
12451  number after the interrupt keyword, see section
12452 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
12453
12454 \end_inset
12455
12456 \SpecialChar ~
12457 about interrupts.
12458 \layout Itemize
12459
12460 CALLEE-SAVES
12461 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
12462
12463 \end_inset
12464
12465
12466 \begin_inset LatexCommand \index{function prologue}
12467
12468 \end_inset
12469
12470  function1[,function2[,function3...]] - The compiler by default uses a caller
12471  saves convention for register saving across function calls, however this
12472  can cause unnecessary register pushing & popping when calling small functions
12473  from larger functions.
12474  This option can be used to switch off the register saving convention for
12475  the function names specified.
12476  The compiler will not save registers when calling these functions, extra
12477  code need to be manually inserted at the entry & exit for these functions
12478  to save & restore the registers used by these functions, this can SUBSTANTIALLY
12479  reduce code & improve run time performance of the generated code.
12480  In the future the compiler (with inter procedural analysis) may be able
12481  to determine the appropriate scheme to use for each function call.
12482  If -
12483 \begin_inset ERT
12484 status Collapsed
12485
12486 \layout Standard
12487
12488 \backslash
12489 /
12490 \end_inset
12491
12492 -callee-saves command line option is used, the function names specified
12493  in #pragma\SpecialChar ~
12494 CALLEE-SAVES
12495 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
12496
12497 \end_inset
12498
12499  is appended to the list of functions specified in the command line.
12500 \layout Itemize
12501
12502 preproc_asm
12503 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
12504
12505 \end_inset
12506
12507  (+ | -) - switch _asm _endasm block preprocessing on / off.
12508  Default is on.
12509 \layout Standard
12510
12511 The pragma's are intended to be used to turn-on or off certain optimizations
12512  which might cause the compiler to generate extra stack / data space to
12513  store compiler generated temporary variables.
12514  This usually happens in large functions.
12515  Pragma directives should be used as shown in the following example, they
12516  are used to control options & optimizations for a given function; pragmas
12517  should be placed before and/or after a function, placing pragma's inside
12518  a function body could have unpredictable results.
12519 \layout Verse
12520
12521
12522 \family typewriter
12523 #pragma SAVE
12524 \begin_inset LatexCommand \index{\#pragma SAVE}
12525
12526 \end_inset
12527
12528  \SpecialChar ~
12529 \SpecialChar ~
12530 \SpecialChar ~
12531 \SpecialChar ~
12532 \SpecialChar ~
12533 \SpecialChar ~
12534 \SpecialChar ~
12535 /* save the current settings */
12536 \newline
12537 #pragma NOGCSE
12538 \begin_inset LatexCommand \index{\#pragma NOGCSE}
12539
12540 \end_inset
12541
12542  \SpecialChar ~
12543 \SpecialChar ~
12544 \SpecialChar ~
12545 \SpecialChar ~
12546 \SpecialChar ~
12547 /* turnoff global subexpression elimination */
12548 \newline
12549 #pragma NOINDUCTION
12550 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
12551
12552 \end_inset
12553
12554  /* turn off induction optimizations */
12555 \newline
12556 int foo ()
12557 \newline
12558 {
12559 \newline
12560 \SpecialChar ~
12561  \SpecialChar ~
12562  ...
12563
12564 \newline
12565 \SpecialChar ~
12566  \SpecialChar ~
12567  /* large code */
12568 \newline
12569 \SpecialChar ~
12570  \SpecialChar ~
12571  ...
12572
12573 \newline
12574 }
12575 \newline
12576 #pragma RESTORE
12577 \begin_inset LatexCommand \index{\#pragma RESTORE}
12578
12579 \end_inset
12580
12581  /* turn the optimizations back on */
12582 \layout Standard
12583
12584 The compiler will generate a warning message when extra space is allocated.
12585  It is strongly recommended that the SAVE and RESTORE pragma's be used when
12586  changing options for a function.
12587 \layout Section
12588
12589 Defines Created by the Compiler
12590 \begin_inset LatexCommand \index{Defines created by the compiler}
12591
12592 \end_inset
12593
12594
12595 \layout Standard
12596
12597 The compiler creates the following #defines
12598 \begin_inset LatexCommand \index{\#defines}
12599
12600 \end_inset
12601
12602 :
12603 \newline
12604
12605 \layout Standard
12606
12607
12608 \begin_inset  Tabular
12609 <lyxtabular version="3" rows="10" columns="2">
12610 <features>
12611 <column alignment="center" valignment="top" leftline="true" width="0">
12612 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12613 <row topline="true" bottomline="true">
12614 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12615 \begin_inset Text
12616
12617 \layout Standard
12618
12619
12620 \series bold
12621 #define
12622 \end_inset
12623 </cell>
12624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12625 \begin_inset Text
12626
12627 \layout Standard
12628
12629
12630 \series bold
12631 Description
12632 \end_inset
12633 </cell>
12634 </row>
12635 <row topline="true">
12636 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12637 \begin_inset Text
12638
12639 \layout Standard
12640
12641 SDCC
12642 \begin_inset LatexCommand \index{SDCC}
12643
12644 \end_inset
12645
12646
12647 \end_inset
12648 </cell>
12649 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12650 \begin_inset Text
12651
12652 \layout Standard
12653
12654 this Symbol is always defined
12655 \end_inset
12656 </cell>
12657 </row>
12658 <row topline="true">
12659 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12660 \begin_inset Text
12661
12662 \layout Standard
12663
12664 SDCC_mcs51
12665 \begin_inset LatexCommand \index{SDCC\_mcs51}
12666
12667 \end_inset
12668
12669  or SDCC_ds390
12670 \begin_inset LatexCommand \index{SDCC\_ds390}
12671
12672 \end_inset
12673
12674  or SDCC_z80
12675 \begin_inset LatexCommand \index{SDCC\_z80}
12676
12677 \end_inset
12678
12679 , etc
12680 \end_inset
12681 </cell>
12682 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12683 \begin_inset Text
12684
12685 \layout Standard
12686
12687 depending on the model used (e.g.: -mds390
12688 \end_inset
12689 </cell>
12690 </row>
12691 <row topline="true">
12692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12693 \begin_inset Text
12694
12695 \layout Standard
12696
12697 __mcs51
12698 \begin_inset LatexCommand \index{\_\_mcs51}
12699
12700 \end_inset
12701
12702 , __ds390
12703 \begin_inset LatexCommand \index{\_\_ds390}
12704
12705 \end_inset
12706
12707 , __hc08
12708 \begin_inset LatexCommand \index{\_\_hc08}
12709
12710 \end_inset
12711
12712 , __z80
12713 \begin_inset LatexCommand \index{\_\_z80}
12714
12715 \end_inset
12716
12717 , etc
12718 \end_inset
12719 </cell>
12720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12721 \begin_inset Text
12722
12723 \layout Standard
12724
12725 depending on the model used (e.g.
12726  -mz80)
12727 \end_inset
12728 </cell>
12729 </row>
12730 <row topline="true">
12731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12732 \begin_inset Text
12733
12734 \layout Standard
12735
12736 SDCC_STACK_AUTO
12737 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
12738
12739 \end_inset
12740
12741
12742 \end_inset
12743 </cell>
12744 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12745 \begin_inset Text
12746
12747 \layout Standard
12748
12749 when
12750 \emph on
12751 -
12752 \begin_inset ERT
12753 status Collapsed
12754
12755 \layout Standard
12756
12757 \backslash
12758 /
12759 \end_inset
12760
12761 -stack-auto
12762 \emph default
12763  option is used
12764 \end_inset
12765 </cell>
12766 </row>
12767 <row topline="true">
12768 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12769 \begin_inset Text
12770
12771 \layout Standard
12772
12773 SDCC_MODEL_SMALL
12774 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
12775
12776 \end_inset
12777
12778
12779 \end_inset
12780 </cell>
12781 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12782 \begin_inset Text
12783
12784 \layout Standard
12785
12786 when
12787 \emph on
12788 -
12789 \begin_inset ERT
12790 status Collapsed
12791
12792 \layout Standard
12793
12794 \backslash
12795 /
12796 \end_inset
12797
12798 -model-small
12799 \emph default
12800  is used
12801 \end_inset
12802 </cell>
12803 </row>
12804 <row topline="true">
12805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12806 \begin_inset Text
12807
12808 \layout Standard
12809
12810 SDCC_MODEL_LARGE
12811 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
12812
12813 \end_inset
12814
12815
12816 \end_inset
12817 </cell>
12818 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12819 \begin_inset Text
12820
12821 \layout Standard
12822
12823 when
12824 \emph on
12825 -
12826 \begin_inset ERT
12827 status Collapsed
12828
12829 \layout Standard
12830
12831 \backslash
12832 /
12833 \end_inset
12834
12835 -model-large
12836 \emph default
12837  is used
12838 \end_inset
12839 </cell>
12840 </row>
12841 <row topline="true">
12842 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12843 \begin_inset Text
12844
12845 \layout Standard
12846
12847 SDCC_USE_XSTACK
12848 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
12849
12850 \end_inset
12851
12852
12853 \end_inset
12854 </cell>
12855 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12856 \begin_inset Text
12857
12858 \layout Standard
12859
12860 when
12861 \emph on
12862 -
12863 \begin_inset ERT
12864 status Collapsed
12865
12866 \layout Standard
12867
12868 \backslash
12869 /
12870 \end_inset
12871
12872 -xstack
12873 \emph default
12874  option is used
12875 \end_inset
12876 </cell>
12877 </row>
12878 <row topline="true">
12879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12880 \begin_inset Text
12881
12882 \layout Standard
12883
12884 SDCC_STACK_TENBIT
12885 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
12886
12887 \end_inset
12888
12889
12890 \end_inset
12891 </cell>
12892 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12893 \begin_inset Text
12894
12895 \layout Standard
12896
12897 when
12898 \emph on
12899 -mds390
12900 \emph default
12901  is used
12902 \end_inset
12903 </cell>
12904 </row>
12905 <row topline="true" bottomline="true">
12906 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12907 \begin_inset Text
12908
12909 \layout Standard
12910
12911 SDCC_MODEL_FLAT24
12912 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
12913
12914 \end_inset
12915
12916
12917 \end_inset
12918 </cell>
12919 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12920 \begin_inset Text
12921
12922 \layout Standard
12923
12924 when
12925 \emph on
12926 -mds390
12927 \emph default
12928  is used
12929 \end_inset
12930 </cell>
12931 </row>
12932 </lyxtabular>
12933
12934 \end_inset
12935
12936
12937 \newline
12938
12939 \layout Chapter
12940
12941 Debugging with SDCDB
12942 \begin_inset LatexCommand \index{sdcdb}
12943
12944 \end_inset
12945
12946
12947 \layout Standard
12948
12949 SDCC is distributed with a source level debugger
12950 \begin_inset LatexCommand \index{Debugger}
12951
12952 \end_inset
12953
12954 .
12955  The debugger uses a command line interface, the command repertoire of the
12956  debugger has been kept as close to gdb
12957 \begin_inset LatexCommand \index{gdb}
12958
12959 \end_inset
12960
12961  (the GNU debugger) as possible.
12962  The configuration and build process is part of the standard compiler installati
12963 on, which also builds and installs the debugger in the target directory
12964  specified during configuration.
12965  The debugger allows you debug BOTH at the C source and at the ASM source
12966  level.
12967  Sdcdb is available on Unix platforms only.
12968 \layout Section
12969
12970 Compiling for Debugging
12971 \layout Standard
12972
12973 The \SpecialChar \-
12974 \SpecialChar \-
12975 debug option must be specified for all files for which debug information
12976  is to be generated.
12977  The complier generates a .adb file for each of these files.
12978  The linker creates the .cdb file from the .adb files and the address information.
12979  This .cdb is used by the debugger.
12980 \layout Section
12981
12982 How the Debugger Works
12983 \layout Standard
12984
12985 When the -
12986 \begin_inset ERT
12987 status Collapsed
12988
12989 \layout Standard
12990
12991 \backslash
12992 /
12993 \end_inset
12994
12995 -debug option is specified the compiler generates extra symbol information
12996  some of which are put into the assembler source and some are put into the
12997  .adb file.
12998   Then the linker creates the .cdb file from the individual .adb files with
12999  the address information for the symbols.
13000  The debugger reads the symbolic information generated by the compiler &
13001  the address information generated by the linker.
13002  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
13003  execution is controlled by the debugger.
13004  When a command is issued for the debugger, it translates it into appropriate
13005  commands for the simulator.
13006 \layout Section
13007
13008 Starting the Debugger
13009 \layout Standard
13010
13011 The debugger can be started using the following command line.
13012  (Assume the file you are debugging has the file name foo).
13013 \newline
13014
13015 \newline
13016
13017 \family sans
13018 \series bold
13019 sdcdb foo
13020 \newline
13021
13022 \family default
13023 \series default
13024
13025 \newline
13026 The debugger will look for the following files.
13027 \layout Itemize
13028
13029 foo.c - the source file.
13030 \layout Itemize
13031
13032 foo.cdb - the debugger symbol information file.
13033 \layout Itemize
13034
13035 foo.ihx - the Intel hex format
13036 \begin_inset LatexCommand \index{Intel hex format}
13037
13038 \end_inset
13039
13040  object file.
13041 \layout Section
13042
13043 Command Line Options.
13044 \layout Itemize
13045
13046 -
13047 \begin_inset ERT
13048 status Collapsed
13049
13050 \layout Standard
13051
13052 \backslash
13053 /
13054 \end_inset
13055
13056 -directory=<source file directory> this option can used to specify the directory
13057  search list.
13058  The debugger will look into the directory list specified for source, cdb
13059  & ihx files.
13060  The items in the directory list must be separated by ':', e.g.
13061  if the source files can be in the directories /home/src1 and /home/src2,
13062  the -
13063 \begin_inset ERT
13064 status Collapsed
13065
13066 \layout Standard
13067
13068 \backslash
13069 /
13070 \end_inset
13071
13072 -directory option should be -
13073 \begin_inset ERT
13074 status Collapsed
13075
13076 \layout Standard
13077
13078 \backslash
13079 /
13080 \end_inset
13081
13082 -directory=/home/src1:/home/src2.
13083  Note there can be no spaces in the option.
13084
13085 \layout Itemize
13086
13087 -cd <directory> - change to the <directory>.
13088 \layout Itemize
13089
13090 -fullname - used by GUI front ends.
13091 \layout Itemize
13092
13093 -cpu <cpu-type> - this argument is passed to the simulator please see the
13094  simulator docs for details.
13095 \layout Itemize
13096
13097 -X <Clock frequency > this options is passed to the simulator please see
13098  the simulator docs for details.
13099 \layout Itemize
13100
13101 -s <serial port file> passed to simulator see the simulator docs for details.
13102 \layout Itemize
13103
13104 -S <serial in,out> passed to simulator see the simulator docs for details.
13105 \layout Section
13106
13107 Debugger Commands.
13108 \layout Standard
13109
13110 As mentioned earlier the command interface for the debugger has been deliberatel
13111 y kept as close the GNU debugger gdb, as possible.
13112  This will help the integration with existing graphical user interfaces
13113  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
13114  If you use a graphical user interface for the debugger you can skip the
13115  next sections.
13116 \layout Subsubsection*
13117
13118 break [line | file:line | function | file:function]
13119 \layout Standard
13120
13121 Set breakpoint at specified line or function:
13122 \newline
13123
13124 \newline
13125
13126 \family sans
13127 \series bold
13128 sdcdb>break 100
13129 \newline
13130 sdcdb>break foo.c:100
13131 \newline
13132 sdcdb>break funcfoo
13133 \newline
13134 sdcdb>break foo.c:funcfoo
13135 \layout Subsubsection*
13136
13137 clear [line | file:line | function | file:function ]
13138 \layout Standard
13139
13140 Clear breakpoint at specified line or function:
13141 \newline
13142
13143 \newline
13144
13145 \family sans
13146 \series bold
13147 sdcdb>clear 100
13148 \newline
13149 sdcdb>clear foo.c:100
13150 \newline
13151 sdcdb>clear funcfoo
13152 \newline
13153 sdcdb>clear foo.c:funcfoo
13154 \layout Subsubsection*
13155
13156 continue
13157 \layout Standard
13158
13159 Continue program being debugged, after breakpoint.
13160 \layout Subsubsection*
13161
13162 finish
13163 \layout Standard
13164
13165 Execute till the end of the current function.
13166 \layout Subsubsection*
13167
13168 delete [n]
13169 \layout Standard
13170
13171 Delete breakpoint number 'n'.
13172  If used without any option clear ALL user defined break points.
13173 \layout Subsubsection*
13174
13175 info [break | stack | frame | registers ]
13176 \layout Itemize
13177
13178 info break - list all breakpoints
13179 \layout Itemize
13180
13181 info stack - show the function call stack.
13182 \layout Itemize
13183
13184 info frame - show information about the current execution frame.
13185 \layout Itemize
13186
13187 info registers - show content of all registers.
13188 \layout Subsubsection*
13189
13190 step
13191 \layout Standard
13192
13193 Step program until it reaches a different source line.
13194 \layout Subsubsection*
13195
13196 next
13197 \layout Standard
13198
13199 Step program, proceeding through subroutine calls.
13200 \layout Subsubsection*
13201
13202 run
13203 \layout Standard
13204
13205 Start debugged program.
13206 \layout Subsubsection*
13207
13208 ptype variable
13209 \layout Standard
13210
13211 Print type information of the variable.
13212 \layout Subsubsection*
13213
13214 print variable
13215 \layout Standard
13216
13217 print value of variable.
13218 \layout Subsubsection*
13219
13220 file filename
13221 \layout Standard
13222
13223 load the given file name.
13224  Note this is an alternate method of loading file for debugging.
13225 \layout Subsubsection*
13226
13227 frame
13228 \layout Standard
13229
13230 print information about current frame.
13231 \layout Subsubsection*
13232
13233 set srcmode
13234 \layout Standard
13235
13236 Toggle between C source & assembly source.
13237 \layout Subsubsection*
13238
13239 ! simulator command
13240 \layout Standard
13241
13242 Send the string following '!' to the simulator, the simulator response is
13243  displayed.
13244  Note the debugger does not interpret the command being sent to the simulator,
13245  so if a command like 'go' is sent the debugger can loose its execution
13246  context and may display incorrect values.
13247 \layout Subsubsection*
13248
13249 quit.
13250 \layout Standard
13251
13252 "Watch me now.
13253  Iam going Down.
13254  My name is Bobby Brown"
13255 \layout Section
13256
13257 Interfacing with XEmacs
13258 \begin_inset LatexCommand \index{XEmacs}
13259
13260 \end_inset
13261
13262
13263 \begin_inset LatexCommand \index{Emacs}
13264
13265 \end_inset
13266
13267 .
13268 \layout Standard
13269
13270 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
13271  sdcdb.el and sdcdbsrc.el.
13272  These two files can be found in the $(prefix)/bin directory after the installat
13273 ion is complete.
13274  These files need to be loaded into XEmacs for the interface to work.
13275  This can be done at XEmacs startup time by inserting the following into
13276  your '.xemacs' file (which can be found in your HOME directory):
13277 \newline
13278
13279 \newline
13280
13281 \family typewriter
13282 (load-file sdcdbsrc.el)
13283 \family default
13284
13285 \newline
13286
13287 \newline
13288 .xemacs is a lisp file so the () around the command is REQUIRED.
13289  The files can also be loaded dynamically while XEmacs is running, set the
13290  environment variable 'EMACSLOADPATH' to the installation bin directory
13291  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
13292  To start the interface enter the following command:
13293 \newline
13294
13295 \newline
13296
13297 \family sans
13298 \series bold
13299 ESC-x sdcdbsrc
13300 \family default
13301 \series default
13302
13303 \newline
13304
13305 \newline
13306 You will prompted to enter the file name to be debugged.
13307
13308 \newline
13309
13310 \newline
13311 The command line options that are passed to the simulator directly are bound
13312  to default values in the file sdcdbsrc.el.
13313  The variables are listed below, these values maybe changed as required.
13314 \layout Itemize
13315
13316 sdcdbsrc-cpu-type '51
13317 \layout Itemize
13318
13319 sdcdbsrc-frequency '11059200
13320 \layout Itemize
13321
13322 sdcdbsrc-serial nil
13323 \layout Standard
13324
13325 The following is a list of key mapping for the debugger interface.
13326 \layout Standard
13327
13328 \SpecialChar ~
13329
13330 \family typewriter
13331
13332 \newline
13333 ;; Current Listing ::
13334 \newline
13335 ;;key\SpecialChar ~
13336 \SpecialChar ~
13337 \SpecialChar ~
13338 \SpecialChar ~
13339 \SpecialChar ~
13340 \SpecialChar ~
13341 \SpecialChar ~
13342 \SpecialChar ~
13343 \SpecialChar ~
13344 \SpecialChar ~
13345 \SpecialChar ~
13346 \SpecialChar ~
13347 \SpecialChar ~
13348 \SpecialChar ~
13349 \SpecialChar ~
13350 binding\SpecialChar ~
13351 \SpecialChar ~
13352 \SpecialChar ~
13353 \SpecialChar ~
13354 \SpecialChar ~
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 Comment
13373 \newline
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 \SpecialChar ~
13402 \SpecialChar ~
13403 \SpecialChar ~
13404 \SpecialChar ~
13405 \SpecialChar ~
13406 \SpecialChar ~
13407 \SpecialChar ~
13408 \SpecialChar ~
13409 \SpecialChar ~
13410 \SpecialChar ~
13411 --------
13412 \newline
13413 ;;
13414 \newline
13415 ;; n\SpecialChar ~
13416 \SpecialChar ~
13417 \SpecialChar ~
13418 \SpecialChar ~
13419 \SpecialChar ~
13420 \SpecialChar ~
13421 \SpecialChar ~
13422 \SpecialChar ~
13423 \SpecialChar ~
13424 \SpecialChar ~
13425 \SpecialChar ~
13426 \SpecialChar ~
13427 \SpecialChar ~
13428 \SpecialChar ~
13429  sdcdb-next-from-src\SpecialChar ~
13430 \SpecialChar ~
13431 \SpecialChar ~
13432 \SpecialChar ~
13433 \SpecialChar ~
13434 \SpecialChar ~
13435 \SpecialChar ~
13436 \SpecialChar ~
13437 \SpecialChar ~
13438 \SpecialChar ~
13439 SDCDB next command
13440 \newline
13441 ;; b\SpecialChar ~
13442 \SpecialChar ~
13443 \SpecialChar ~
13444 \SpecialChar ~
13445 \SpecialChar ~
13446 \SpecialChar ~
13447 \SpecialChar ~
13448 \SpecialChar ~
13449 \SpecialChar ~
13450 \SpecialChar ~
13451 \SpecialChar ~
13452 \SpecialChar ~
13453 \SpecialChar ~
13454 \SpecialChar ~
13455  sdcdb-back-from-src\SpecialChar ~
13456 \SpecialChar ~
13457 \SpecialChar ~
13458 \SpecialChar ~
13459 \SpecialChar ~
13460 \SpecialChar ~
13461 \SpecialChar ~
13462 \SpecialChar ~
13463 \SpecialChar ~
13464 \SpecialChar ~
13465 SDCDB back command
13466 \newline
13467 ;; c\SpecialChar ~
13468 \SpecialChar ~
13469 \SpecialChar ~
13470 \SpecialChar ~
13471 \SpecialChar ~
13472 \SpecialChar ~
13473 \SpecialChar ~
13474 \SpecialChar ~
13475 \SpecialChar ~
13476 \SpecialChar ~
13477 \SpecialChar ~
13478 \SpecialChar ~
13479 \SpecialChar ~
13480 \SpecialChar ~
13481  sdcdb-cont-from-src\SpecialChar ~
13482 \SpecialChar ~
13483 \SpecialChar ~
13484 \SpecialChar ~
13485 \SpecialChar ~
13486 \SpecialChar ~
13487 \SpecialChar ~
13488 \SpecialChar ~
13489 \SpecialChar ~
13490 \SpecialChar ~
13491 SDCDB continue command
13492 \newline
13493 ;; s\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  sdcdb-step-from-src\SpecialChar ~
13508 \SpecialChar ~
13509 \SpecialChar ~
13510 \SpecialChar ~
13511 \SpecialChar ~
13512 \SpecialChar ~
13513 \SpecialChar ~
13514 \SpecialChar ~
13515 \SpecialChar ~
13516 \SpecialChar ~
13517 SDCDB step command
13518 \newline
13519 ;; ?\SpecialChar ~
13520 \SpecialChar ~
13521 \SpecialChar ~
13522 \SpecialChar ~
13523 \SpecialChar ~
13524 \SpecialChar ~
13525 \SpecialChar ~
13526 \SpecialChar ~
13527 \SpecialChar ~
13528 \SpecialChar ~
13529 \SpecialChar ~
13530 \SpecialChar ~
13531 \SpecialChar ~
13532 \SpecialChar ~
13533  sdcdb-whatis-c-sexp\SpecialChar ~
13534 \SpecialChar ~
13535 \SpecialChar ~
13536 \SpecialChar ~
13537 \SpecialChar ~
13538 \SpecialChar ~
13539 \SpecialChar ~
13540 \SpecialChar ~
13541 \SpecialChar ~
13542 \SpecialChar ~
13543 SDCDB ptypecommand for data at
13544 \newline
13545 ;;\SpecialChar ~
13546 \SpecialChar ~
13547 \SpecialChar ~
13548 \SpecialChar ~
13549 \SpecialChar ~
13550 \SpecialChar ~
13551 \SpecialChar ~
13552 \SpecialChar ~
13553 \SpecialChar ~
13554 \SpecialChar ~
13555 \SpecialChar ~
13556 \SpecialChar ~
13557 \SpecialChar ~
13558 \SpecialChar ~
13559 \SpecialChar ~
13560 \SpecialChar ~
13561 \SpecialChar ~
13562 \SpecialChar ~
13563 \SpecialChar ~
13564 \SpecialChar ~
13565 \SpecialChar ~
13566 \SpecialChar ~
13567 \SpecialChar ~
13568 \SpecialChar ~
13569 \SpecialChar ~
13570 \SpecialChar ~
13571 \SpecialChar ~
13572 \SpecialChar ~
13573 \SpecialChar ~
13574 \SpecialChar ~
13575 \SpecialChar ~
13576 \SpecialChar ~
13577 \SpecialChar ~
13578 \SpecialChar ~
13579 \SpecialChar ~
13580 \SpecialChar ~
13581 \SpecialChar ~
13582 \SpecialChar ~
13583 \SpecialChar ~
13584 \SpecialChar ~
13585 \SpecialChar ~
13586 \SpecialChar ~
13587 \SpecialChar ~
13588 \SpecialChar ~
13589 \SpecialChar ~
13590 \SpecialChar ~
13591  buffer point
13592 \newline
13593 ;; x\SpecialChar ~
13594 \SpecialChar ~
13595 \SpecialChar ~
13596 \SpecialChar ~
13597 \SpecialChar ~
13598 \SpecialChar ~
13599 \SpecialChar ~
13600 \SpecialChar ~
13601 \SpecialChar ~
13602 \SpecialChar ~
13603 \SpecialChar ~
13604 \SpecialChar ~
13605 \SpecialChar ~
13606 \SpecialChar ~
13607  sdcdbsrc-delete\SpecialChar ~
13608 \SpecialChar ~
13609 \SpecialChar ~
13610 \SpecialChar ~
13611 \SpecialChar ~
13612 \SpecialChar ~
13613 \SpecialChar ~
13614 \SpecialChar ~
13615 \SpecialChar ~
13616 \SpecialChar ~
13617 \SpecialChar ~
13618 \SpecialChar ~
13619 \SpecialChar ~
13620 \SpecialChar ~
13621 SDCDB Delete all breakpoints if no arg
13622 \newline
13623 ;;\SpecialChar ~
13624 \SpecialChar ~
13625 \SpecialChar ~
13626 \SpecialChar ~
13627 \SpecialChar ~
13628 \SpecialChar ~
13629 \SpecialChar ~
13630 \SpecialChar ~
13631 \SpecialChar ~
13632 \SpecialChar ~
13633 \SpecialChar ~
13634 \SpecialChar ~
13635 \SpecialChar ~
13636 \SpecialChar ~
13637 \SpecialChar ~
13638 \SpecialChar ~
13639 \SpecialChar ~
13640 \SpecialChar ~
13641 \SpecialChar ~
13642 \SpecialChar ~
13643 \SpecialChar ~
13644 \SpecialChar ~
13645 \SpecialChar ~
13646 \SpecialChar ~
13647 \SpecialChar ~
13648 \SpecialChar ~
13649 \SpecialChar ~
13650 \SpecialChar ~
13651 \SpecialChar ~
13652 \SpecialChar ~
13653 \SpecialChar ~
13654 \SpecialChar ~
13655 \SpecialChar ~
13656 \SpecialChar ~
13657 \SpecialChar ~
13658 \SpecialChar ~
13659 \SpecialChar ~
13660 \SpecialChar ~
13661 \SpecialChar ~
13662 \SpecialChar ~
13663 \SpecialChar ~
13664 \SpecialChar ~
13665 \SpecialChar ~
13666 \SpecialChar ~
13667 \SpecialChar ~
13668 \SpecialChar ~
13669 given or delete arg (C-u arg x)
13670 \newline
13671 ;; m\SpecialChar ~
13672 \SpecialChar ~
13673 \SpecialChar ~
13674 \SpecialChar ~
13675 \SpecialChar ~
13676 \SpecialChar ~
13677 \SpecialChar ~
13678 \SpecialChar ~
13679 \SpecialChar ~
13680 \SpecialChar ~
13681 \SpecialChar ~
13682 \SpecialChar ~
13683 \SpecialChar ~
13684 \SpecialChar ~
13685  sdcdbsrc-frame\SpecialChar ~
13686 \SpecialChar ~
13687 \SpecialChar ~
13688 \SpecialChar ~
13689 \SpecialChar ~
13690 \SpecialChar ~
13691 \SpecialChar ~
13692 \SpecialChar ~
13693 \SpecialChar ~
13694 \SpecialChar ~
13695 \SpecialChar ~
13696 \SpecialChar ~
13697 \SpecialChar ~
13698 \SpecialChar ~
13699 \SpecialChar ~
13700 SDCDB Display current frame if no arg,
13701 \newline
13702 ;;\SpecialChar ~
13703 \SpecialChar ~
13704 \SpecialChar ~
13705 \SpecialChar ~
13706 \SpecialChar ~
13707 \SpecialChar ~
13708 \SpecialChar ~
13709 \SpecialChar ~
13710 \SpecialChar ~
13711 \SpecialChar ~
13712 \SpecialChar ~
13713 \SpecialChar ~
13714 \SpecialChar ~
13715 \SpecialChar ~
13716 \SpecialChar ~
13717 \SpecialChar ~
13718 \SpecialChar ~
13719 \SpecialChar ~
13720 \SpecialChar ~
13721 \SpecialChar ~
13722 \SpecialChar ~
13723 \SpecialChar ~
13724 \SpecialChar ~
13725 \SpecialChar ~
13726 \SpecialChar ~
13727 \SpecialChar ~
13728 \SpecialChar ~
13729 \SpecialChar ~
13730 \SpecialChar ~
13731 \SpecialChar ~
13732 \SpecialChar ~
13733 \SpecialChar ~
13734 \SpecialChar ~
13735 \SpecialChar ~
13736 \SpecialChar ~
13737 \SpecialChar ~
13738 \SpecialChar ~
13739 \SpecialChar ~
13740 \SpecialChar ~
13741 \SpecialChar ~
13742 \SpecialChar ~
13743 \SpecialChar ~
13744 \SpecialChar ~
13745 \SpecialChar ~
13746 \SpecialChar ~
13747 \SpecialChar ~
13748 \SpecialChar ~
13749 given or display frame arg
13750 \newline
13751 ;;\SpecialChar ~
13752 \SpecialChar ~
13753 \SpecialChar ~
13754 \SpecialChar ~
13755 \SpecialChar ~
13756 \SpecialChar ~
13757 \SpecialChar ~
13758 \SpecialChar ~
13759 \SpecialChar ~
13760 \SpecialChar ~
13761 \SpecialChar ~
13762 \SpecialChar ~
13763 \SpecialChar ~
13764 \SpecialChar ~
13765 \SpecialChar ~
13766 \SpecialChar ~
13767 \SpecialChar ~
13768 \SpecialChar ~
13769 \SpecialChar ~
13770 \SpecialChar ~
13771 \SpecialChar ~
13772 \SpecialChar ~
13773 \SpecialChar ~
13774 \SpecialChar ~
13775 \SpecialChar ~
13776 \SpecialChar ~
13777 \SpecialChar ~
13778 \SpecialChar ~
13779 \SpecialChar ~
13780 \SpecialChar ~
13781 \SpecialChar ~
13782 \SpecialChar ~
13783 \SpecialChar ~
13784 \SpecialChar ~
13785 \SpecialChar ~
13786 \SpecialChar ~
13787 \SpecialChar ~
13788 \SpecialChar ~
13789 \SpecialChar ~
13790 \SpecialChar ~
13791 \SpecialChar ~
13792 \SpecialChar ~
13793 \SpecialChar ~
13794 \SpecialChar ~
13795 \SpecialChar ~
13796 \SpecialChar ~
13797 \SpecialChar ~
13798 buffer point
13799 \newline
13800 ;; !\SpecialChar ~
13801 \SpecialChar ~
13802 \SpecialChar ~
13803 \SpecialChar ~
13804 \SpecialChar ~
13805 \SpecialChar ~
13806 \SpecialChar ~
13807 \SpecialChar ~
13808 \SpecialChar ~
13809 \SpecialChar ~
13810 \SpecialChar ~
13811 \SpecialChar ~
13812 \SpecialChar ~
13813 \SpecialChar ~
13814  sdcdbsrc-goto-sdcdb\SpecialChar ~
13815 \SpecialChar ~
13816 \SpecialChar ~
13817 \SpecialChar ~
13818 \SpecialChar ~
13819 \SpecialChar ~
13820 \SpecialChar ~
13821 \SpecialChar ~
13822 \SpecialChar ~
13823 \SpecialChar ~
13824 Goto the SDCDB output buffer
13825 \newline
13826 ;; p\SpecialChar ~
13827 \SpecialChar ~
13828 \SpecialChar ~
13829 \SpecialChar ~
13830 \SpecialChar ~
13831 \SpecialChar ~
13832 \SpecialChar ~
13833 \SpecialChar ~
13834 \SpecialChar ~
13835 \SpecialChar ~
13836 \SpecialChar ~
13837 \SpecialChar ~
13838 \SpecialChar ~
13839 \SpecialChar ~
13840  sdcdb-print-c-sexp\SpecialChar ~
13841 \SpecialChar ~
13842 \SpecialChar ~
13843 \SpecialChar ~
13844 \SpecialChar ~
13845 \SpecialChar ~
13846 \SpecialChar ~
13847 \SpecialChar ~
13848 \SpecialChar ~
13849 \SpecialChar ~
13850 \SpecialChar ~
13851 SDCDB print command for data at
13852 \newline
13853 ;;\SpecialChar ~
13854 \SpecialChar ~
13855 \SpecialChar ~
13856 \SpecialChar ~
13857 \SpecialChar ~
13858 \SpecialChar ~
13859 \SpecialChar ~
13860 \SpecialChar ~
13861 \SpecialChar ~
13862 \SpecialChar ~
13863 \SpecialChar ~
13864 \SpecialChar ~
13865 \SpecialChar ~
13866 \SpecialChar ~
13867 \SpecialChar ~
13868 \SpecialChar ~
13869 \SpecialChar ~
13870 \SpecialChar ~
13871 \SpecialChar ~
13872 \SpecialChar ~
13873 \SpecialChar ~
13874 \SpecialChar ~
13875 \SpecialChar ~
13876 \SpecialChar ~
13877 \SpecialChar ~
13878 \SpecialChar ~
13879 \SpecialChar ~
13880 \SpecialChar ~
13881 \SpecialChar ~
13882 \SpecialChar ~
13883 \SpecialChar ~
13884 \SpecialChar ~
13885 \SpecialChar ~
13886 \SpecialChar ~
13887 \SpecialChar ~
13888 \SpecialChar ~
13889 \SpecialChar ~
13890 \SpecialChar ~
13891 \SpecialChar ~
13892 \SpecialChar ~
13893 \SpecialChar ~
13894 \SpecialChar ~
13895 \SpecialChar ~
13896 \SpecialChar ~
13897 \SpecialChar ~
13898 \SpecialChar ~
13899  buffer point
13900 \newline
13901 ;; g\SpecialChar ~
13902 \SpecialChar ~
13903 \SpecialChar ~
13904 \SpecialChar ~
13905 \SpecialChar ~
13906 \SpecialChar ~
13907 \SpecialChar ~
13908 \SpecialChar ~
13909 \SpecialChar ~
13910 \SpecialChar ~
13911 \SpecialChar ~
13912 \SpecialChar ~
13913 \SpecialChar ~
13914 \SpecialChar ~
13915  sdcdbsrc-goto-sdcdb\SpecialChar ~
13916 \SpecialChar ~
13917 \SpecialChar ~
13918 \SpecialChar ~
13919 \SpecialChar ~
13920 \SpecialChar ~
13921 \SpecialChar ~
13922 \SpecialChar ~
13923 \SpecialChar ~
13924 \SpecialChar ~
13925 Goto the SDCDB output buffer
13926 \newline
13927 ;; t\SpecialChar ~
13928 \SpecialChar ~
13929 \SpecialChar ~
13930 \SpecialChar ~
13931 \SpecialChar ~
13932 \SpecialChar ~
13933 \SpecialChar ~
13934 \SpecialChar ~
13935 \SpecialChar ~
13936 \SpecialChar ~
13937 \SpecialChar ~
13938 \SpecialChar ~
13939 \SpecialChar ~
13940 \SpecialChar ~
13941  sdcdbsrc-mode\SpecialChar ~
13942 \SpecialChar ~
13943 \SpecialChar ~
13944 \SpecialChar ~
13945 \SpecialChar ~
13946 \SpecialChar ~
13947 \SpecialChar ~
13948 \SpecialChar ~
13949 \SpecialChar ~
13950 \SpecialChar ~
13951 \SpecialChar ~
13952 \SpecialChar ~
13953 \SpecialChar ~
13954 \SpecialChar ~
13955 \SpecialChar ~
13956 \SpecialChar ~
13957 Toggles Sdcdbsrc mode (turns it off)
13958 \newline
13959 ;;
13960 \newline
13961 ;; C-c C-f\SpecialChar ~
13962 \SpecialChar ~
13963 \SpecialChar ~
13964 \SpecialChar ~
13965 \SpecialChar ~
13966 \SpecialChar ~
13967 \SpecialChar ~
13968 \SpecialChar ~
13969  sdcdb-finish-from-src\SpecialChar ~
13970 \SpecialChar ~
13971 \SpecialChar ~
13972 \SpecialChar ~
13973 \SpecialChar ~
13974 \SpecialChar ~
13975 \SpecialChar ~
13976 \SpecialChar ~
13977 SDCDB finish command
13978 \newline
13979 ;;
13980 \newline
13981 ;; C-x SPC\SpecialChar ~
13982 \SpecialChar ~
13983 \SpecialChar ~
13984 \SpecialChar ~
13985 \SpecialChar ~
13986 \SpecialChar ~
13987 \SpecialChar ~
13988 \SpecialChar ~
13989  sdcdb-break\SpecialChar ~
13990 \SpecialChar ~
13991 \SpecialChar ~
13992 \SpecialChar ~
13993 \SpecialChar ~
13994 \SpecialChar ~
13995 \SpecialChar ~
13996 \SpecialChar ~
13997 \SpecialChar ~
13998 \SpecialChar ~
13999 \SpecialChar ~
14000 \SpecialChar ~
14001 \SpecialChar ~
14002 \SpecialChar ~
14003 \SpecialChar ~
14004 \SpecialChar ~
14005 \SpecialChar ~
14006 \SpecialChar ~
14007 Set break for line with point
14008 \newline
14009 ;; ESC t\SpecialChar ~
14010 \SpecialChar ~
14011 \SpecialChar ~
14012 \SpecialChar ~
14013 \SpecialChar ~
14014 \SpecialChar ~
14015 \SpecialChar ~
14016 \SpecialChar ~
14017 \SpecialChar ~
14018 \SpecialChar ~
14019  sdcdbsrc-mode\SpecialChar ~
14020 \SpecialChar ~
14021 \SpecialChar ~
14022 \SpecialChar ~
14023 \SpecialChar ~
14024 \SpecialChar ~
14025 \SpecialChar ~
14026 \SpecialChar ~
14027 \SpecialChar ~
14028 \SpecialChar ~
14029 \SpecialChar ~
14030 \SpecialChar ~
14031 \SpecialChar ~
14032 \SpecialChar ~
14033 \SpecialChar ~
14034 \SpecialChar ~
14035 Toggle Sdcdbsrc mode
14036 \newline
14037 ;; ESC m\SpecialChar ~
14038 \SpecialChar ~
14039 \SpecialChar ~
14040 \SpecialChar ~
14041 \SpecialChar ~
14042 \SpecialChar ~
14043 \SpecialChar ~
14044 \SpecialChar ~
14045 \SpecialChar ~
14046 \SpecialChar ~
14047  sdcdbsrc-srcmode\SpecialChar ~
14048 \SpecialChar ~
14049 \SpecialChar ~
14050 \SpecialChar ~
14051 \SpecialChar ~
14052 \SpecialChar ~
14053 \SpecialChar ~
14054 \SpecialChar ~
14055 \SpecialChar ~
14056 \SpecialChar ~
14057 \SpecialChar ~
14058 \SpecialChar ~
14059  Toggle list mode
14060 \newline
14061 ;;
14062 \newline
14063
14064 \layout Chapter
14065 \pagebreak_top
14066 TIPS
14067 \layout Standard
14068
14069 Here are a few guidelines that will help the compiler generate more efficient
14070  code, some of the tips are specific to this compiler others are generally
14071  good programming practice.
14072 \layout Itemize
14073
14074 Use the smallest data type to represent your data-value.
14075  If it is known in advance that the value is going to be less than 256 then
14076  use an 'unsigned char' instead of a 'short' or 'int'.
14077 \layout Itemize
14078
14079 Use unsigned when it is known in advance that the value is not going to
14080  be negative.
14081  This helps especially if you are doing division or multiplication.
14082 \layout Itemize
14083
14084 NEVER jump into a LOOP.
14085 \layout Itemize
14086
14087 Declare the variables to be local whenever possible, especially loop control
14088  variables (induction).
14089 \layout Itemize
14090
14091 Since the compiler does not always do implicit integral promotion, the programme
14092 r should do an explicit cast when integral promotion is required.
14093 \layout Itemize
14094
14095 Reducing the size of division, multiplication & modulus operations can reduce
14096  code size substantially.
14097  Take the following code for example.
14098 \begin_deeper
14099 \layout Verse
14100
14101
14102 \family typewriter
14103 foobar(unsigned int p1, unsigned char ch)
14104 \newline
14105 {
14106 \newline
14107 \SpecialChar ~
14108 \SpecialChar ~
14109 \SpecialChar ~
14110 \SpecialChar ~
14111 unsigned char ch1 = p1 % ch ;
14112 \newline
14113 \SpecialChar ~
14114 \SpecialChar ~
14115 \SpecialChar ~
14116 \SpecialChar ~
14117 ....
14118 \newline
14119 }
14120 \layout Standard
14121
14122 For the modulus operation the variable ch will be promoted to unsigned int
14123  first then the modulus operation will be performed (this will lead to a
14124  call to support routine _moduint()), and the result will be casted to a
14125  char.
14126  If the code is changed to
14127 \layout Verse
14128
14129
14130 \family typewriter
14131 foobar(unsigned int p1, unsigned char ch)
14132 \newline
14133 {
14134 \newline
14135 \SpecialChar ~
14136 \SpecialChar ~
14137 \SpecialChar ~
14138 \SpecialChar ~
14139 unsigned char ch1 = (unsigned char)p1 % ch ;
14140 \newline
14141 \SpecialChar ~
14142 \SpecialChar ~
14143 \SpecialChar ~
14144 \SpecialChar ~
14145 ....
14146 \newline
14147 }
14148 \layout Standard
14149
14150 It would substantially reduce the code generated (future versions of the
14151  compiler will be smart enough to detect such optimization opportunities).
14152 \end_deeper
14153 \layout Itemize
14154
14155 Have a look at the assembly listing to get a
14156 \begin_inset Quotes sld
14157 \end_inset
14158
14159 feeling
14160 \begin_inset Quotes srd
14161 \end_inset
14162
14163  for the code generation.
14164 \layout Section
14165
14166 Notes on MCS51 memory
14167 \begin_inset LatexCommand \index{MCS51 memory}
14168
14169 \end_inset
14170
14171  layout
14172 \layout Standard
14173
14174 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
14175  RAM memory which is structured as follows
14176 \newline
14177
14178 \newline
14179 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
14180
14181 \newline
14182 - Bytes 20-2F - 16 bytes to hold 128 bit
14183 \begin_inset LatexCommand \index{bit}
14184
14185 \end_inset
14186
14187  variables and,
14188 \newline
14189 - Bytes 30-7F - 80 bytes for general purpose use.
14190 \newline
14191
14192 \layout Standard
14193
14194 Additionally some members of the MCS51 family may have up to 128 bytes of
14195  additional, indirectly addressable, internal RAM memory (
14196 \emph on
14197 idata
14198 \emph default
14199
14200 \begin_inset LatexCommand \index{idata}
14201
14202 \end_inset
14203
14204 ).
14205  Furthermore, some chips may have some built in external memory (
14206 \emph on
14207 xdata
14208 \emph default
14209
14210 \begin_inset LatexCommand \index{xdata}
14211
14212 \end_inset
14213
14214 ) which should not be confused with the internal, directly addressable RAM
14215  memory (
14216 \emph on
14217 data
14218 \emph default
14219
14220 \begin_inset LatexCommand \index{data}
14221
14222 \end_inset
14223
14224 ).
14225  Sometimes this built in
14226 \emph on
14227 xdata
14228 \emph default
14229  memory has to be activated before using it (you can probably find this
14230  information on the datasheet of the microcontroller your are using, see
14231  also section
14232 \begin_inset LatexCommand \ref{sub:Startup-Code}
14233
14234 \end_inset
14235
14236 \SpecialChar ~
14237 Startup-Code).
14238 \layout Standard
14239
14240 Normally SDCC will only use the first bank
14241 \begin_inset LatexCommand \index{bank}
14242
14243 \end_inset
14244
14245  of registers (register bank 0), but it is possible to specify that other
14246  banks of registers should be used in interrupt
14247 \begin_inset LatexCommand \index{interrupt}
14248
14249 \end_inset
14250
14251  routines.
14252  By default, the compiler will place the stack after the last byte of allocated
14253  memory for variables.
14254  For example, if the first 2 banks of registers are used, and only four
14255  bytes are used for
14256 \emph on
14257 data
14258 \emph default
14259  variables, it will position the base of the internal stack at address 20
14260  (0x14).
14261  This implies that as the stack
14262 \begin_inset LatexCommand \index{stack}
14263
14264 \end_inset
14265
14266  grows, it will use up the remaining register banks, and the 16 bytes used
14267  by the 128 bit variables, and 80 bytes for general purpose use.
14268  If any bit variables are used, the data variables will be placed after
14269  the byte holding the last bit variable.
14270  For example, if register banks 0 and 1 are used, and there are 9 bit variables
14271  (two bytes used),
14272 \emph on
14273 data
14274 \emph default
14275  variables will be placed starting at address 0x22.
14276  You can also use -
14277 \begin_inset ERT
14278 status Collapsed
14279
14280 \layout Standard
14281
14282 \backslash
14283 /
14284 \end_inset
14285
14286 -data-loc
14287 \begin_inset LatexCommand \index{-\/-data-loc}
14288
14289 \end_inset
14290
14291  to specify the start address of the
14292 \emph on
14293 data
14294 \emph default
14295  and -
14296 \begin_inset ERT
14297 status Collapsed
14298
14299 \layout Standard
14300
14301 \backslash
14302 /
14303 \end_inset
14304
14305 -iram-size to specify the size of the total internal RAM (
14306 \emph on
14307 data
14308 \emph default
14309 +
14310 \emph on
14311 idata
14312 \emph default
14313 ).
14314
14315 \layout Standard
14316
14317 By default the 8051 linker will place the stack after the last byte of data
14318  variables.
14319  Option -
14320 \begin_inset ERT
14321 status Collapsed
14322
14323 \layout Standard
14324
14325 \backslash
14326 /
14327 \end_inset
14328
14329 -stack-loc
14330 \begin_inset LatexCommand \index{-\/-stack-loc}
14331
14332 \end_inset
14333
14334  allows you to specify the start of the stack, i.e.
14335  you could start it after any data in the general purpose area.
14336  If your microcontroller has additional indirectly addressable internal
14337  RAM (
14338 \emph on
14339 idata
14340 \emph default
14341 ) you can place the stack on it.
14342  You may also need to use -
14343 \begin_inset ERT
14344 status Collapsed
14345
14346 \layout Standard
14347
14348 \backslash
14349 /
14350 \end_inset
14351
14352 -xdata-loc
14353 \begin_inset LatexCommand \index{-\/-data-loc}
14354
14355 \end_inset
14356
14357  to set the start address of the external RAM (
14358 \emph on
14359 xdata
14360 \emph default
14361 ) and -
14362 \begin_inset ERT
14363 status Collapsed
14364
14365 \layout Standard
14366
14367 \backslash
14368 /
14369 \end_inset
14370
14371 -xram-size
14372 \begin_inset LatexCommand \index{-\/-data-loc}
14373
14374 \end_inset
14375
14376  to specify its size.
14377  Same goes for the code memory, using -
14378 \begin_inset ERT
14379 status Collapsed
14380
14381 \layout Standard
14382
14383 \backslash
14384 /
14385 \end_inset
14386
14387 -code-loc
14388 \begin_inset LatexCommand \index{-\/-data-loc}
14389
14390 \end_inset
14391
14392  and -
14393 \begin_inset ERT
14394 status Collapsed
14395
14396 \layout Standard
14397
14398 \backslash
14399 /
14400 \end_inset
14401
14402 -code-size
14403 \begin_inset LatexCommand \index{-\/-data-loc}
14404
14405 \end_inset
14406
14407 .
14408  If in doubt, don't specify any options and see if the resulting memory
14409  layout is appropriate, then you can adjust it.
14410 \layout Standard
14411
14412 The 8051 linker generates two files with memory allocation information.
14413  The first, with extension .map shows all the variables and segments.
14414  The second with extension .mem shows the final memory layout.
14415  The linker will complaint either if memory segments overlap, there is not
14416  enough memory, or there is not enough space for stack.
14417  If you get any linking warnings and/or errors related to stack or segments
14418  allocation, take a look at either the .map or .mem files to find out what
14419  the problem is.
14420  The .mem file may even suggest a solution to the problem.
14421 \layout Section
14422
14423 Tools
14424 \begin_inset LatexCommand \index{Tools}
14425
14426 \end_inset
14427
14428  included in the distribution
14429 \layout Standard
14430 \align center
14431
14432 \begin_inset  Tabular
14433 <lyxtabular version="3" rows="12" columns="3">
14434 <features>
14435 <column alignment="center" valignment="top" leftline="true" width="0pt">
14436 <column alignment="center" valignment="top" leftline="true" width="0pt">
14437 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
14438 <row topline="true" bottomline="true">
14439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14440 \begin_inset Text
14441
14442 \layout Standard
14443
14444 Name
14445 \end_inset
14446 </cell>
14447 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14448 \begin_inset Text
14449
14450 \layout Standard
14451
14452 Purpose
14453 \end_inset
14454 </cell>
14455 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14456 \begin_inset Text
14457
14458 \layout Standard
14459
14460 Directory
14461 \end_inset
14462 </cell>
14463 </row>
14464 <row topline="true">
14465 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14466 \begin_inset Text
14467
14468 \layout Standard
14469
14470 uCsim
14471 \end_inset
14472 </cell>
14473 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14474 \begin_inset Text
14475
14476 \layout Standard
14477
14478 Simulator for various architectures
14479 \end_inset
14480 </cell>
14481 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14482 \begin_inset Text
14483
14484 \layout Standard
14485
14486 sdcc/sim/ucsim
14487 \end_inset
14488 </cell>
14489 </row>
14490 <row topline="true">
14491 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14492 \begin_inset Text
14493
14494 \layout Standard
14495
14496 keil2sdcc.pl
14497 \end_inset
14498 </cell>
14499 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14500 \begin_inset Text
14501
14502 \layout Standard
14503
14504 header file conversion
14505 \end_inset
14506 </cell>
14507 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14508 \begin_inset Text
14509
14510 \layout Standard
14511
14512 sdcc/support/scripts
14513 \end_inset
14514 </cell>
14515 </row>
14516 <row topline="true">
14517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14518 \begin_inset Text
14519
14520 \layout Standard
14521
14522 mh2h.c
14523 \end_inset
14524 </cell>
14525 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14526 \begin_inset Text
14527
14528 \layout Standard
14529
14530 header file conversion
14531 \end_inset
14532 </cell>
14533 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14534 \begin_inset Text
14535
14536 \layout Standard
14537
14538 sdcc/support/scripts
14539 \end_inset
14540 </cell>
14541 </row>
14542 <row topline="true">
14543 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14544 \begin_inset Text
14545
14546 \layout Standard
14547
14548 as-gbz80
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 Assembler
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 \family roman
14566 \series medium
14567 \shape up
14568 \size normal
14569 \emph off
14570 \bar no
14571 \noun off
14572 \color none
14573 sdcc/bin
14574 \end_inset
14575 </cell>
14576 </row>
14577 <row topline="true">
14578 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14579 \begin_inset Text
14580
14581 \layout Standard
14582
14583 as-z80
14584 \end_inset
14585 </cell>
14586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14587 \begin_inset Text
14588
14589 \layout Standard
14590
14591 Assembler
14592 \end_inset
14593 </cell>
14594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14595 \begin_inset Text
14596
14597 \layout Standard
14598
14599
14600 \family roman
14601 \series medium
14602 \shape up
14603 \size normal
14604 \emph off
14605 \bar no
14606 \noun off
14607 \color none
14608 sdcc/bin
14609 \end_inset
14610 </cell>
14611 </row>
14612 <row topline="true">
14613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14614 \begin_inset Text
14615
14616 \layout Standard
14617
14618 asx8051
14619 \end_inset
14620 </cell>
14621 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14622 \begin_inset Text
14623
14624 \layout Standard
14625
14626 Assembler
14627 \end_inset
14628 </cell>
14629 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14630 \begin_inset Text
14631
14632 \layout Standard
14633
14634
14635 \family roman
14636 \series medium
14637 \shape up
14638 \size normal
14639 \emph off
14640 \bar no
14641 \noun off
14642 \color none
14643 sdcc/bin
14644 \end_inset
14645 </cell>
14646 </row>
14647 <row topline="true">
14648 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14649 \begin_inset Text
14650
14651 \layout Standard
14652
14653 sdcdb
14654 \end_inset
14655 </cell>
14656 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14657 \begin_inset Text
14658
14659 \layout Standard
14660
14661 Simulator
14662 \end_inset
14663 </cell>
14664 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14665 \begin_inset Text
14666
14667 \layout Standard
14668
14669
14670 \family roman
14671 \series medium
14672 \shape up
14673 \size normal
14674 \emph off
14675 \bar no
14676 \noun off
14677 \color none
14678 sdcc/bin
14679 \end_inset
14680 </cell>
14681 </row>
14682 <row topline="true">
14683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14684 \begin_inset Text
14685
14686 \layout Standard
14687
14688 aslink
14689 \end_inset
14690 </cell>
14691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14692 \begin_inset Text
14693
14694 \layout Standard
14695
14696 Linker
14697 \end_inset
14698 </cell>
14699 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14700 \begin_inset Text
14701
14702 \layout Standard
14703
14704
14705 \family roman
14706 \series medium
14707 \shape up
14708 \size normal
14709 \emph off
14710 \bar no
14711 \noun off
14712 \color none
14713 sdcc/bin
14714 \end_inset
14715 </cell>
14716 </row>
14717 <row topline="true">
14718 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14719 \begin_inset Text
14720
14721 \layout Standard
14722
14723 link-z80
14724 \end_inset
14725 </cell>
14726 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14727 \begin_inset Text
14728
14729 \layout Standard
14730
14731 Linker
14732 \end_inset
14733 </cell>
14734 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14735 \begin_inset Text
14736
14737 \layout Standard
14738
14739
14740 \family roman
14741 \series medium
14742 \shape up
14743 \size normal
14744 \emph off
14745 \bar no
14746 \noun off
14747 \color none
14748 sdcc/bin
14749 \end_inset
14750 </cell>
14751 </row>
14752 <row topline="true">
14753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14754 \begin_inset Text
14755
14756 \layout Standard
14757
14758 link-gbz80
14759 \end_inset
14760 </cell>
14761 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14762 \begin_inset Text
14763
14764 \layout Standard
14765
14766 Linker
14767 \end_inset
14768 </cell>
14769 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14770 \begin_inset Text
14771
14772 \layout Standard
14773
14774
14775 \family roman
14776 \series medium
14777 \shape up
14778 \size normal
14779 \emph off
14780 \bar no
14781 \noun off
14782 \color none
14783 sdcc/bin
14784 \end_inset
14785 </cell>
14786 </row>
14787 <row topline="true" bottomline="true">
14788 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14789 \begin_inset Text
14790
14791 \layout Standard
14792
14793 packihx
14794 \end_inset
14795 </cell>
14796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14797 \begin_inset Text
14798
14799 \layout Standard
14800
14801 ihx packer
14802 \end_inset
14803 </cell>
14804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14805 \begin_inset Text
14806
14807 \layout Standard
14808
14809
14810 \family roman
14811 \series medium
14812 \shape up
14813 \size normal
14814 \emph off
14815 \bar no
14816 \noun off
14817 \color none
14818 sdcc/bin
14819 \end_inset
14820 </cell>
14821 </row>
14822 </lyxtabular>
14823
14824 \end_inset
14825
14826
14827 \newline
14828
14829 \layout Section
14830
14831 Related open source tools
14832 \begin_inset LatexCommand \index{Related tools}
14833
14834 \end_inset
14835
14836
14837 \layout Standard
14838 \align center
14839
14840 \begin_inset  Tabular
14841 <lyxtabular version="3" rows="9" columns="3">
14842 <features>
14843 <column alignment="center" valignment="top" leftline="true" width="0pt">
14844 <column alignment="block" valignment="top" leftline="true" width="30line%">
14845 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
14846 <row topline="true" bottomline="true">
14847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14848 \begin_inset Text
14849
14850 \layout Standard
14851
14852 Name
14853 \end_inset
14854 </cell>
14855 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14856 \begin_inset Text
14857
14858 \layout Standard
14859
14860 Purpose
14861 \end_inset
14862 </cell>
14863 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14864 \begin_inset Text
14865
14866 \layout Standard
14867
14868 Where to get
14869 \end_inset
14870 </cell>
14871 </row>
14872 <row topline="true">
14873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14874 \begin_inset Text
14875
14876 \layout Standard
14877
14878 gpsim
14879 \begin_inset LatexCommand \index{gpsim}
14880
14881 \end_inset
14882
14883
14884 \end_inset
14885 </cell>
14886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14887 \begin_inset Text
14888
14889 \layout Standard
14890
14891 PIC simulator
14892 \end_inset
14893 </cell>
14894 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14895 \begin_inset Text
14896
14897 \layout Standard
14898
14899
14900 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
14901
14902 \end_inset
14903
14904
14905 \end_inset
14906 </cell>
14907 </row>
14908 <row topline="true">
14909 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14910 \begin_inset Text
14911
14912 \layout Standard
14913
14914 flP5
14915 \end_inset
14916 </cell>
14917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14918 \begin_inset Text
14919
14920 \layout Standard
14921
14922 PIC programmer
14923 \end_inset
14924 </cell>
14925 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14926 \begin_inset Text
14927
14928 \layout Standard
14929
14930
14931 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
14932
14933 \end_inset
14934
14935
14936 \end_inset
14937 </cell>
14938 </row>
14939 <row topline="true">
14940 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14941 \begin_inset Text
14942
14943 \layout Standard
14944
14945 indent
14946 \begin_inset LatexCommand \index{indent}
14947
14948 \end_inset
14949
14950
14951 \end_inset
14952 </cell>
14953 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14954 \begin_inset Text
14955
14956 \layout Standard
14957
14958 Formats C source - Master of the white spaces
14959 \end_inset
14960 </cell>
14961 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14962 \begin_inset Text
14963
14964 \layout Standard
14965
14966
14967 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
14968
14969 \end_inset
14970
14971
14972 \end_inset
14973 </cell>
14974 </row>
14975 <row topline="true">
14976 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14977 \begin_inset Text
14978
14979 \layout Standard
14980
14981 srecord
14982 \begin_inset LatexCommand \index{srecord}
14983
14984 \end_inset
14985
14986
14987 \end_inset
14988 </cell>
14989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14990 \begin_inset Text
14991
14992 \layout Standard
14993
14994 Object file conversion, checksumming, ...
14995 \end_inset
14996 </cell>
14997 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14998 \begin_inset Text
14999
15000 \layout Standard
15001
15002
15003 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
15004
15005 \end_inset
15006
15007
15008 \end_inset
15009 </cell>
15010 </row>
15011 <row topline="true">
15012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15013 \begin_inset Text
15014
15015 \layout Standard
15016
15017 objdump
15018 \begin_inset LatexCommand \index{objdump}
15019
15020 \end_inset
15021
15022
15023 \end_inset
15024 </cell>
15025 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15026 \begin_inset Text
15027
15028 \layout Standard
15029
15030 Object file conversion, ...
15031 \end_inset
15032 </cell>
15033 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15034 \begin_inset Text
15035
15036 \layout Standard
15037
15038 Part of binutils (should be there anyway)
15039 \end_inset
15040 </cell>
15041 </row>
15042 <row topline="true">
15043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15044 \begin_inset Text
15045
15046 \layout Standard
15047
15048 doxygen
15049 \begin_inset LatexCommand \index{doxygen}
15050
15051 \end_inset
15052
15053
15054 \end_inset
15055 </cell>
15056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15057 \begin_inset Text
15058
15059 \layout Standard
15060
15061 Source code documentation system
15062 \end_inset
15063 </cell>
15064 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15065 \begin_inset Text
15066
15067 \layout Standard
15068
15069
15070 \begin_inset LatexCommand \url{http://www.doxygen.org}
15071
15072 \end_inset
15073
15074
15075 \end_inset
15076 </cell>
15077 </row>
15078 <row topline="true">
15079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15080 \begin_inset Text
15081
15082 \layout Standard
15083
15084 splint
15085 \begin_inset LatexCommand \index{splint}
15086
15087 \end_inset
15088
15089
15090 \end_inset
15091 </cell>
15092 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15093 \begin_inset Text
15094
15095 \layout Standard
15096
15097 Statically checks c sources
15098 \end_inset
15099 </cell>
15100 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15101 \begin_inset Text
15102
15103 \layout Standard
15104
15105
15106 \begin_inset LatexCommand \url{http://www.splint.org}
15107
15108 \end_inset
15109
15110
15111 \end_inset
15112 </cell>
15113 </row>
15114 <row topline="true" bottomline="true">
15115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15116 \begin_inset Text
15117
15118 \layout Standard
15119
15120 ddd
15121 \begin_inset LatexCommand \index{ddd}
15122
15123 \end_inset
15124
15125
15126 \end_inset
15127 </cell>
15128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15129 \begin_inset Text
15130
15131 \layout Standard
15132
15133 Debugger, serves nicely as GUI to sdcdb
15134 \begin_inset LatexCommand \index{sdcdb}
15135
15136 \end_inset
15137
15138  (Unix only)
15139 \end_inset
15140 </cell>
15141 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15142 \begin_inset Text
15143
15144 \layout Standard
15145
15146
15147 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
15148
15149 \end_inset
15150
15151
15152 \end_inset
15153 </cell>
15154 </row>
15155 </lyxtabular>
15156
15157 \end_inset
15158
15159
15160 \newline
15161
15162 \layout Section
15163
15164 Related documentation / recommended reading
15165 \layout Standard
15166 \align center
15167
15168 \begin_inset  Tabular
15169 <lyxtabular version="3" rows="5" columns="3">
15170 <features>
15171 <column alignment="center" valignment="top" leftline="true" width="0pt">
15172 <column alignment="block" valignment="top" leftline="true" width="30line%">
15173 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
15174 <row topline="true" bottomline="true">
15175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15176 \begin_inset Text
15177
15178 \layout Standard
15179
15180 Name
15181 \end_inset
15182 </cell>
15183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15184 \begin_inset Text
15185
15186 \layout Standard
15187
15188 Subject / Title
15189 \end_inset
15190 </cell>
15191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15192 \begin_inset Text
15193
15194 \layout Standard
15195
15196 Where to get
15197 \end_inset
15198 </cell>
15199 </row>
15200 <row topline="true">
15201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15202 \begin_inset Text
15203
15204 \layout Standard
15205
15206
15207 \family roman
15208 \series medium
15209 \shape up
15210 \size normal
15211 \emph off
15212 \bar no
15213 \noun off
15214 \color none
15215 c-refcard.pdf
15216 \end_inset
15217 </cell>
15218 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15219 \begin_inset Text
15220
15221 \layout Standard
15222
15223 C Reference Card
15224 \begin_inset LatexCommand \index{C Reference card}
15225
15226 \end_inset
15227
15228 , 2 pages
15229 \end_inset
15230 </cell>
15231 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15232 \begin_inset Text
15233
15234 \layout Standard
15235
15236
15237 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
15238
15239 \end_inset
15240
15241
15242 \end_inset
15243 </cell>
15244 </row>
15245 <row topline="true">
15246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15247 \begin_inset Text
15248
15249 \layout Standard
15250
15251 S.
15252  S.
15253  Muchnick
15254 \end_inset
15255 </cell>
15256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15257 \begin_inset Text
15258
15259 \layout Standard
15260
15261 Advanced Compiler Design and Implementation
15262 \end_inset
15263 </cell>
15264 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15265 \begin_inset Text
15266
15267 \layout Standard
15268
15269 bookstore
15270 \end_inset
15271 </cell>
15272 </row>
15273 <row topline="true">
15274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15275 \begin_inset Text
15276
15277 \layout Standard
15278
15279 test_suite_spec.pdf
15280 \end_inset
15281 </cell>
15282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15283 \begin_inset Text
15284
15285 \layout Standard
15286
15287 sdcc regression test
15288 \begin_inset LatexCommand \index{Regression test}
15289
15290 \end_inset
15291
15292
15293 \end_inset
15294 </cell>
15295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15296 \begin_inset Text
15297
15298 \layout Standard
15299
15300 sdcc/doc
15301 \end_inset
15302 </cell>
15303 </row>
15304 <row topline="true" bottomline="true">
15305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15306 \begin_inset Text
15307
15308 \layout Standard
15309
15310
15311 \family roman
15312 \series medium
15313 \shape up
15314 \size normal
15315 \emph off
15316 \bar no
15317 \noun off
15318 \color none
15319 cdbfileformat.pd
15320 \family default
15321 \series default
15322 \shape default
15323 \size default
15324 \emph default
15325 \bar default
15326 \noun default
15327 \color default
15328 f
15329 \end_inset
15330 </cell>
15331 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15332 \begin_inset Text
15333
15334 \layout Standard
15335
15336 sdcc internal documentation
15337 \end_inset
15338 </cell>
15339 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15340 \begin_inset Text
15341
15342 \layout Standard
15343
15344 sdcc/doc
15345 \end_inset
15346 </cell>
15347 </row>
15348 </lyxtabular>
15349
15350 \end_inset
15351
15352
15353 \newline
15354
15355 \layout Chapter
15356 \pagebreak_top
15357 Support
15358 \begin_inset LatexCommand \index{Support}
15359
15360 \end_inset
15361
15362
15363 \layout Standard
15364
15365 SDCC has grown to be a large project.
15366  The compiler alone (without the preprocessor, assembler and linker) is
15367  well over 100,000 lines of code (blank stripped).
15368  The open source nature of this project is a key to its continued growth
15369  and support.
15370  You gain the benefit and support of many active software developers and
15371  end users.
15372  Is SDCC perfect? No, that's why we need your help.
15373  The developers take pride in fixing reported bugs.
15374  You can help by reporting the bugs and helping other SDCC users.
15375  There are lots of ways to contribute, and we encourage you to take part
15376  in making SDCC a great software package.
15377
15378 \layout Standard
15379
15380 The SDCC project is hosted on the SDCC sourceforge site at
15381 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
15382
15383 \end_inset
15384
15385 .
15386  You'll find the complete set of mailing lists
15387 \begin_inset LatexCommand \index{Mailing list}
15388
15389 \end_inset
15390
15391 , forums, bug reporting system, patch submission
15392 \begin_inset LatexCommand \index{Patch submission}
15393
15394 \end_inset
15395
15396  system, download
15397 \begin_inset LatexCommand \index{download}
15398
15399 \end_inset
15400
15401  area and cvs code repository
15402 \begin_inset LatexCommand \index{cvs code repository}
15403
15404 \end_inset
15405
15406  there.
15407 \layout Section
15408
15409 Reporting Bugs
15410 \begin_inset LatexCommand \index{Bug reporting}
15411
15412 \end_inset
15413
15414
15415 \begin_inset LatexCommand \index{Reporting bugs}
15416
15417 \end_inset
15418
15419
15420 \layout Standard
15421
15422 The recommended way of reporting bugs is using the infrastructure of the
15423  sourceforge site.
15424  You can follow the status of bug reports there and have an overview about
15425  the known bugs.
15426 \layout Standard
15427
15428 Bug reports are automatically forwarded to the developer mailing list and
15429  will be fixed ASAP.
15430  When reporting a bug, it is very useful to include a small test program
15431  (the smaller the better) which reproduces the problem.
15432  If you can isolate the problem by looking at the generated assembly code,
15433  this can be very helpful.
15434  Compiling your program with the -
15435 \begin_inset ERT
15436 status Collapsed
15437
15438 \layout Standard
15439
15440 \backslash
15441 /
15442 \end_inset
15443
15444 -dumpall
15445 \begin_inset LatexCommand \index{-\/-dumpall}
15446
15447 \end_inset
15448
15449  option can sometimes be useful in locating optimization problems.
15450  When reporting a bug please maker sure you:
15451 \layout Enumerate
15452
15453 Attach the code you are compiling with SDCC.
15454
15455 \layout Enumerate
15456
15457 Specify the exact command you use to run SDCC, or attach your Makefile.
15458
15459 \layout Enumerate
15460
15461 Specify the SDCC version (type "sdcc -v"), your platform, and operating
15462  system.
15463
15464 \layout Enumerate
15465
15466 Provide an exact copy of any error message or incorrect output.
15467
15468 \layout Enumerate
15469
15470 Put something meaningful in the subject of your message.
15471 \layout Standard
15472
15473 Please attempt to include these 5 important parts, as applicable, in all
15474  requests for support or when reporting any problems or bugs with SDCC.
15475  Though this will make your message lengthy, it will greatly improve your
15476  chance that SDCC users and developers will be able to help you.
15477  Some SDCC developers are frustrated by bug reports without code provided
15478  that they can use to reproduce and ultimately fix the problem, so please
15479  be sure to provide sample code if you are reporting a bug!
15480 \layout Standard
15481
15482 Please have a short check that you are using a recent version of SDCC and
15483  the bug is not yet known.
15484  This is the link for reporting bugs:
15485 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
15486
15487 \end_inset
15488
15489 .
15490 \layout Section
15491
15492 Requesting Features
15493 \begin_inset LatexCommand \label{sub:Requesting-Features}
15494
15495 \end_inset
15496
15497
15498 \begin_inset LatexCommand \index{Feature request}
15499
15500 \end_inset
15501
15502
15503 \begin_inset LatexCommand \index{Requesting features}
15504
15505 \end_inset
15506
15507
15508 \layout Standard
15509
15510 Like bug reports feature requests are forwarded to the developer mailing
15511  list.
15512  This is the link for requesting features:
15513 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
15514
15515 \end_inset
15516
15517 .
15518 \layout Section
15519
15520 Getting Help
15521 \layout Standard
15522
15523 These links should take you directly to the
15524 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
15525
15526 \end_inset
15527
15528
15529 \begin_inset Foot
15530 collapsed false
15531
15532 \layout Standard
15533
15534 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
15535  automated messages (mid 2003)
15536 \end_inset
15537
15538  and the
15539 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
15540
15541 \end_inset
15542
15543 , lists and forums are archived so if you are lucky someone already had
15544  a similar problem.
15545 \layout Section
15546
15547 ChangeLog
15548 \begin_inset LatexCommand \index{Changelog}
15549
15550 \end_inset
15551
15552
15553 \layout Standard
15554
15555 You can follow the status of the cvs version
15556 \begin_inset LatexCommand \index{version}
15557
15558 \end_inset
15559
15560  of SDCC by watching the file
15561 \begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
15562
15563 \end_inset
15564
15565  in the cvs-repository.
15566 \layout Section
15567
15568 Release policy
15569 \begin_inset LatexCommand \index{Release policy}
15570
15571 \end_inset
15572
15573
15574 \layout Standard
15575
15576 Historically there often were long delays between official releases and
15577  the sourceforge download area tends to get not updated at all.
15578  Current excuses might refer to problems with live range analysis, but if
15579  this is fixed, the next problem rising is that another excuse will have
15580  to be found.
15581  Kidding aside, we have to get better there! On the other hand there are
15582  daily snapshots available at
15583 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
15584
15585 \end_inset
15586
15587 , and you can always built the very last version (hopefully with many bugs
15588  fixed, and features added) from the source code available at
15589 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
15590
15591 \end_inset
15592
15593 .
15594 \layout Section
15595
15596 Examples
15597 \begin_inset LatexCommand \index{Examples}
15598
15599 \end_inset
15600
15601
15602 \layout Standard
15603
15604 You'll find some small examples in the directory
15605 \emph on
15606 sdcc/device/examples/.
15607
15608 \emph default
15609 More examples and libraries are available at
15610 \emph on
15611  The SDCC Open Knowledge Resource
15612 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
15613
15614 \end_inset
15615
15616
15617 \emph default
15618 web site or at
15619 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
15620
15621 \end_inset
15622
15623 .
15624 \layout Comment
15625
15626 I did insert a reference to Paul's web site here although it seems rather
15627  dedicated to a specific 8032 board (I think it's okay because it f.e.
15628  shows LCD/Harddisc interface and has a free 8051 monitor.
15629  Independent 8032 board vendors face hard competition of heavily subsidized
15630  development boards anyway).
15631 \layout Comment
15632
15633 Maybe we should include some links to real world applications.
15634  Preferably pointer to pointers (one for each architecture) so this stays
15635  manageable here?
15636 \layout Section
15637
15638 Quality control
15639 \begin_inset LatexCommand \index{Quality control}
15640
15641 \end_inset
15642
15643
15644 \layout Standard
15645
15646 The compiler is passed through nightly compile and build checks.
15647  The so called
15648 \shape italic
15649 regression tests
15650 \shape default
15651
15652 \begin_inset LatexCommand \index{Regression test}
15653
15654 \end_inset
15655
15656  check that SDCC itself compiles flawlessly on several platforms and checks
15657  the quality of the code generated by SDCC by running the code through simulator
15658 s.
15659  There is a separate document
15660 \shape italic
15661 test_suite.pdf
15662 \begin_inset LatexCommand \index{Test suite}
15663
15664 \end_inset
15665
15666
15667 \shape default
15668  about this.
15669 \layout Standard
15670
15671 You'll find the test code in the directory
15672 \shape italic
15673 sdcc/support/regression
15674 \shape default
15675 .
15676  You can run these tests manually by running
15677 \family sans
15678 make
15679 \family default
15680  in this directory (or f.e.
15681
15682 \family sans
15683 make test-mcs51
15684 \family default
15685  if you don't want to run the complete tests).
15686  The test code might also be interesting if you want to look for examples
15687 \begin_inset LatexCommand \index{Examples}
15688
15689 \end_inset
15690
15691  checking corner cases of SDCC or if you plan to submit patches
15692 \begin_inset LatexCommand \index{Patch submission}
15693
15694 \end_inset
15695
15696 .
15697 \layout Standard
15698
15699 The pic port uses a different set of regression tests, you'll find them
15700  in the directory
15701 \shape italic
15702 sdcc/src/regression
15703 \shape default
15704 .
15705 \layout Chapter
15706 \pagebreak_top
15707 SDCC Technical Data
15708 \layout Section
15709
15710 Optimizations
15711 \begin_inset LatexCommand \index{Optimizations}
15712
15713 \end_inset
15714
15715
15716 \layout Standard
15717
15718 SDCC performs a host of standard optimizations in addition to some MCU specific
15719  optimizations.
15720
15721 \layout Subsection
15722
15723 Sub-expression Elimination
15724 \begin_inset LatexCommand \index{Subexpression elimination}
15725
15726 \end_inset
15727
15728
15729 \layout Standard
15730
15731 The compiler does local and global common subexpression elimination, e.g.:
15732
15733 \layout Verse
15734
15735
15736 \family typewriter
15737 i = x + y + 1;
15738 \newline
15739 j = x + y;
15740 \layout Standard
15741
15742 will be translated to
15743 \layout Verse
15744
15745
15746 \family typewriter
15747 iTemp = x + y;
15748 \newline
15749 i = iTemp + 1;
15750 \newline
15751 j = iTemp;
15752 \layout Standard
15753
15754 Some subexpressions are not as obvious as the above example, e.g.:
15755 \layout Verse
15756
15757
15758 \family typewriter
15759 a->b[i].c = 10;
15760 \newline
15761 a->b[i].d = 11;
15762 \layout Standard
15763
15764 In this case the address arithmetic a->b[i] will be computed only once;
15765  the equivalent code in C would be.
15766 \layout Verse
15767
15768
15769 \family typewriter
15770 iTemp = a->b[i];
15771 \newline
15772 iTemp.c = 10;
15773 \newline
15774 iTemp.d = 11;
15775 \layout Standard
15776
15777 The compiler will try to keep these temporary variables in registers.
15778 \layout Subsection
15779
15780 Dead-Code Elimination
15781 \begin_inset LatexCommand \index{Dead-code elimination}
15782
15783 \end_inset
15784
15785
15786 \layout Verse
15787
15788
15789 \family typewriter
15790 int global;
15791 \newline
15792
15793 \newline
15794 void f () {
15795 \newline
15796 \SpecialChar ~
15797 \SpecialChar ~
15798 int i;
15799 \newline
15800 \SpecialChar ~
15801 \SpecialChar ~
15802 i = 1; \SpecialChar ~
15803 \SpecialChar ~
15804 \SpecialChar ~
15805 \SpecialChar ~
15806 \SpecialChar ~
15807 /* dead store */
15808 \newline
15809 \SpecialChar ~
15810 \SpecialChar ~
15811 global = 1;\SpecialChar ~
15812 /* dead store */
15813 \newline
15814 \SpecialChar ~
15815 \SpecialChar ~
15816 global = 2;
15817 \newline
15818 \SpecialChar ~
15819 \SpecialChar ~
15820 return;
15821 \newline
15822 \SpecialChar ~
15823 \SpecialChar ~
15824 global = 3;\SpecialChar ~
15825 /* unreachable */
15826 \newline
15827 }
15828 \layout Standard
15829
15830 will be changed to
15831 \layout Verse
15832
15833
15834 \family typewriter
15835 int global;
15836 \newline
15837
15838 \newline
15839 void f () {
15840 \newline
15841 \SpecialChar ~
15842 \SpecialChar ~
15843 global = 2;
15844 \newline
15845 \SpecialChar ~
15846 \SpecialChar ~
15847 return;
15848 \newline
15849 }
15850 \layout Subsection
15851
15852 Copy-Propagation
15853 \begin_inset LatexCommand \index{Copy propagation}
15854
15855 \end_inset
15856
15857
15858 \layout Verse
15859
15860
15861 \family typewriter
15862 int f() {
15863 \newline
15864 \SpecialChar ~
15865 \SpecialChar ~
15866 int i, j;
15867 \newline
15868 \SpecialChar ~
15869 \SpecialChar ~
15870 i = 10;
15871 \newline
15872 \SpecialChar ~
15873 \SpecialChar ~
15874 j = i;
15875 \newline
15876 \SpecialChar ~
15877 \SpecialChar ~
15878 return j;
15879 \newline
15880 }
15881 \layout Standard
15882
15883 will be changed to
15884 \layout Verse
15885
15886
15887 \family typewriter
15888 int f() {
15889 \newline
15890 \SpecialChar ~
15891 \SpecialChar ~
15892 int i, j;
15893 \newline
15894 \SpecialChar ~
15895 \SpecialChar ~
15896 i = 10;
15897 \newline
15898 \SpecialChar ~
15899 \SpecialChar ~
15900 j = 10;
15901 \newline
15902 \SpecialChar ~
15903 \SpecialChar ~
15904 return 10;
15905 \newline
15906 }
15907 \layout Standard
15908
15909 Note: the dead stores created by this copy propagation will be eliminated
15910  by dead-code elimination.
15911 \layout Subsection
15912
15913 Loop Optimizations
15914 \begin_inset LatexCommand \index{Loop optimization}
15915
15916 \end_inset
15917
15918
15919 \layout Standard
15920
15921 Two types of loop optimizations are done by SDCC loop invariant lifting
15922  and strength reduction of loop induction variables.
15923  In addition to the strength reduction the optimizer marks the induction
15924  variables and the register allocator tries to keep the induction variables
15925  in registers for the duration of the loop.
15926  Because of this preference of the register allocator
15927 \begin_inset LatexCommand \index{Register allocation}
15928
15929 \end_inset
15930
15931 , loop induction optimization causes an increase in register pressure, which
15932  may cause unwanted spilling of other temporary variables into the stack
15933 \begin_inset LatexCommand \index{stack}
15934
15935 \end_inset
15936
15937  / data space.
15938  The compiler will generate a warning message when it is forced to allocate
15939  extra space either on the stack or data space.
15940  If this extra space allocation is undesirable then induction optimization
15941  can be eliminated either for the entire source file (with -
15942 \begin_inset ERT
15943 status Collapsed
15944
15945 \layout Standard
15946
15947 \backslash
15948 /
15949 \end_inset
15950
15951 -noinduction option) or for a given function only using #pragma\SpecialChar ~
15952 NOINDUCTION
15953 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
15954
15955 \end_inset
15956
15957 .
15958 \newline
15959
15960 \newline
15961 Loop Invariant:
15962 \layout Verse
15963
15964
15965 \family typewriter
15966 for (i = 0 ; i < 100 ; i ++)
15967 \newline
15968 \SpecialChar ~
15969 \SpecialChar ~
15970 \SpecialChar ~
15971 \SpecialChar ~
15972 f += k + l;
15973 \layout Standard
15974
15975 changed to
15976 \layout Verse
15977
15978
15979 \family typewriter
15980 itemp = k + l;
15981 \newline
15982 for (i = 0; i < 100; i++)
15983 \newline
15984 \SpecialChar ~
15985 \SpecialChar ~
15986 \SpecialChar ~
15987 \SpecialChar ~
15988 f += itemp;
15989 \layout Standard
15990
15991 As mentioned previously some loop invariants are not as apparent, all static
15992  address computations are also moved out of the loop.
15993 \newline
15994
15995 \newline
15996 Strength Reduction
15997 \begin_inset LatexCommand \index{Strength reduction}
15998
15999 \end_inset
16000
16001 , this optimization substitutes an expression by a cheaper expression:
16002 \layout Verse
16003
16004
16005 \family typewriter
16006 for (i=0;i < 100; i++)
16007 \newline
16008 \SpecialChar ~
16009 \SpecialChar ~
16010 \SpecialChar ~
16011 \SpecialChar ~
16012 ar[i*5] = i*3;
16013 \layout Standard
16014
16015 changed to
16016 \layout Verse
16017
16018
16019 \family typewriter
16020 itemp1 = 0;
16021 \newline
16022 itemp2 = 0;
16023 \newline
16024 for (i=0;i< 100;i++) {
16025 \newline
16026 \SpecialChar ~
16027 \SpecialChar ~
16028 \SpecialChar ~
16029 \SpecialChar ~
16030 ar[itemp1] = itemp2;
16031 \newline
16032 \SpecialChar ~
16033 \SpecialChar ~
16034 \SpecialChar ~
16035 \SpecialChar ~
16036 itemp1 += 5;
16037 \newline
16038 \SpecialChar ~
16039 \SpecialChar ~
16040 \SpecialChar ~
16041 \SpecialChar ~
16042 itemp2 += 3;
16043 \newline
16044 }
16045 \layout Standard
16046
16047 The more expensive multiplication
16048 \begin_inset LatexCommand \index{Multiplication}
16049
16050 \end_inset
16051
16052  is changed to a less expensive addition.
16053 \layout Subsection
16054
16055 Loop Reversing
16056 \begin_inset LatexCommand \index{Loop reversing}
16057
16058 \end_inset
16059
16060
16061 \layout Standard
16062
16063 This optimization is done to reduce the overhead of checking loop boundaries
16064  for every iteration.
16065  Some simple loops can be reversed and implemented using a
16066 \begin_inset Quotes eld
16067 \end_inset
16068
16069 decrement and jump if not zero
16070 \begin_inset Quotes erd
16071 \end_inset
16072
16073  instruction.
16074  SDCC checks for the following criterion to determine if a loop is reversible
16075  (note: more sophisticated compilers use data-dependency analysis to make
16076  this determination, SDCC uses a more simple minded analysis).
16077 \layout Itemize
16078
16079 The 'for' loop is of the form
16080 \newline
16081
16082 \newline
16083
16084 \family typewriter
16085 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
16086  += 1])
16087 \newline
16088 \SpecialChar ~
16089 \SpecialChar ~
16090 \SpecialChar ~
16091 \SpecialChar ~
16092 <for body>
16093 \layout Itemize
16094
16095 The <for body> does not contain
16096 \begin_inset Quotes eld
16097 \end_inset
16098
16099 continue
16100 \begin_inset Quotes erd
16101 \end_inset
16102
16103  or 'break
16104 \begin_inset Quotes erd
16105 \end_inset
16106
16107 .
16108 \layout Itemize
16109
16110 All goto's are contained within the loop.
16111 \layout Itemize
16112
16113 No function calls within the loop.
16114 \layout Itemize
16115
16116 The loop control variable <sym> is not assigned any value within the loop
16117 \layout Itemize
16118
16119 The loop control variable does NOT participate in any arithmetic operation
16120  within the loop.
16121 \layout Itemize
16122
16123 There are NO switch statements in the loop.
16124 \layout Subsection
16125
16126 Algebraic Simplifications
16127 \layout Standard
16128
16129 SDCC does numerous algebraic simplifications, the following is a small sub-set
16130  of these optimizations.
16131 \layout Verse
16132
16133
16134 \family typewriter
16135 i = j + 0 ; /* changed to */ i = j;
16136 \newline
16137 i /= 2;\SpecialChar ~
16138 \SpecialChar ~
16139 \SpecialChar ~
16140 \SpecialChar ~
16141  /* changed to */ i >>= 1;
16142 \newline
16143 i = j - j ; /* changed to */ i = 0;
16144 \newline
16145 i = j / 1 ; /* changed to */ i = j;
16146 \layout Standard
16147
16148 Note the subexpressions
16149 \begin_inset LatexCommand \index{Subexpression}
16150
16151 \end_inset
16152
16153  given above are generally introduced by macro expansions or as a result
16154  of copy/constant propagation.
16155 \layout Subsection
16156
16157 'switch' Statements
16158 \begin_inset LatexCommand \label{sub:'switch'-Statements}
16159
16160 \end_inset
16161
16162
16163 \begin_inset LatexCommand \index{switch statement}
16164
16165 \end_inset
16166
16167
16168 \layout Standard
16169
16170 SDCC changes switch statements to jump tables
16171 \begin_inset LatexCommand \index{jump tables}
16172
16173 \end_inset
16174
16175  when the following conditions are true.
16176
16177 \layout Itemize
16178
16179 The case labels are in numerical sequence, the labels need not be in order,
16180  and the starting number need not be one or zero.
16181 \begin_deeper
16182 \layout Verse
16183
16184
16185 \family typewriter
16186 switch(i) {\SpecialChar ~
16187 \SpecialChar ~
16188 \SpecialChar ~
16189 \SpecialChar ~
16190 \SpecialChar ~
16191 \SpecialChar ~
16192 \SpecialChar ~
16193 \SpecialChar ~
16194 \SpecialChar ~
16195 \SpecialChar ~
16196 \SpecialChar ~
16197 \SpecialChar ~
16198 \SpecialChar ~
16199 \SpecialChar ~
16200 \SpecialChar ~
16201 \SpecialChar ~
16202 \SpecialChar ~
16203 \SpecialChar ~
16204 \SpecialChar ~
16205 \SpecialChar ~
16206 \SpecialChar ~
16207 \SpecialChar ~
16208 \SpecialChar ~
16209 \SpecialChar ~
16210 \SpecialChar ~
16211 \SpecialChar ~
16212 switch (i) {
16213 \newline
16214 \SpecialChar ~
16215 \SpecialChar ~
16216 \SpecialChar ~
16217 case 4: ...\SpecialChar ~
16218 \SpecialChar ~
16219 \SpecialChar ~
16220 \SpecialChar ~
16221 \SpecialChar ~
16222 \SpecialChar ~
16223 \SpecialChar ~
16224 \SpecialChar ~
16225 \SpecialChar ~
16226 \SpecialChar ~
16227 \SpecialChar ~
16228 \SpecialChar ~
16229 \SpecialChar ~
16230 \SpecialChar ~
16231 \SpecialChar ~
16232 \SpecialChar ~
16233 \SpecialChar ~
16234 \SpecialChar ~
16235 \SpecialChar ~
16236 \SpecialChar ~
16237 \SpecialChar ~
16238 \SpecialChar ~
16239 \SpecialChar ~
16240 \SpecialChar ~
16241 \SpecialChar ~
16242 \SpecialChar ~
16243 case 0: ...
16244
16245 \newline
16246 \SpecialChar ~
16247 \SpecialChar ~
16248 \SpecialChar ~
16249 case 5: ...\SpecialChar ~
16250 \SpecialChar ~
16251 \SpecialChar ~
16252 \SpecialChar ~
16253 \SpecialChar ~
16254 \SpecialChar ~
16255 \SpecialChar ~
16256 \SpecialChar ~
16257 \SpecialChar ~
16258 \SpecialChar ~
16259 \SpecialChar ~
16260 \SpecialChar ~
16261 \SpecialChar ~
16262 \SpecialChar ~
16263 \SpecialChar ~
16264 \SpecialChar ~
16265 \SpecialChar ~
16266 \SpecialChar ~
16267 \SpecialChar ~
16268 \SpecialChar ~
16269 \SpecialChar ~
16270 \SpecialChar ~
16271 \SpecialChar ~
16272 \SpecialChar ~
16273 \SpecialChar ~
16274 \SpecialChar ~
16275 case 1: ...
16276
16277 \newline
16278 \SpecialChar ~
16279 \SpecialChar ~
16280 \SpecialChar ~
16281 case 3: ...\SpecialChar ~
16282 \SpecialChar ~
16283 \SpecialChar ~
16284 \SpecialChar ~
16285 \SpecialChar ~
16286 \SpecialChar ~
16287 \SpecialChar ~
16288 \SpecialChar ~
16289 \SpecialChar ~
16290 \SpecialChar ~
16291 \SpecialChar ~
16292 \SpecialChar ~
16293 \SpecialChar ~
16294 \SpecialChar ~
16295 \SpecialChar ~
16296 \SpecialChar ~
16297 \SpecialChar ~
16298 \SpecialChar ~
16299 \SpecialChar ~
16300 \SpecialChar ~
16301 \SpecialChar ~
16302 \SpecialChar ~
16303 \SpecialChar ~
16304 \SpecialChar ~
16305 \SpecialChar ~
16306 \SpecialChar ~
16307 case 2: ...
16308
16309 \newline
16310 \SpecialChar ~
16311 \SpecialChar ~
16312 \SpecialChar ~
16313 case 6: ...\SpecialChar ~
16314 \SpecialChar ~
16315 \SpecialChar ~
16316 \SpecialChar ~
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 case 3: ...
16340
16341 \newline
16342 }\SpecialChar ~
16343 \SpecialChar ~
16344 \SpecialChar ~
16345 \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 \SpecialChar ~
16361 \SpecialChar ~
16362 \SpecialChar ~
16363 \SpecialChar ~
16364 \SpecialChar ~
16365 \SpecialChar ~
16366 \SpecialChar ~
16367 \SpecialChar ~
16368 \SpecialChar ~
16369 \SpecialChar ~
16370 \SpecialChar ~
16371 \SpecialChar ~
16372 \SpecialChar ~
16373 \SpecialChar ~
16374 \SpecialChar ~
16375 \SpecialChar ~
16376 \SpecialChar ~
16377 \SpecialChar ~
16378 }
16379 \layout Standard
16380
16381 Both the above switch statements will be implemented using a jump-table.
16382  The example to the right side is slightly more efficient as the check for
16383  the lower boundary of the jump-table is not needed.
16384 \end_deeper
16385 \layout Itemize
16386
16387 The number of case labels is at least three, since it takes two conditional
16388  statements to handle the boundary conditions.
16389 \layout Itemize
16390
16391 The number of case labels is less than 84, since each label takes 3 bytes
16392  and a jump-table can be utmost 256 bytes long.
16393 \layout Standard
16394
16395 Switch statements which have gaps in the numeric sequence or those that
16396  have more that 84 case labels can be split into more than one switch statement
16397  for efficient code generation, e.g.:
16398 \layout Verse
16399
16400
16401 \family typewriter
16402 switch (i) {
16403 \newline
16404 \SpecialChar ~
16405 \SpecialChar ~
16406 case 1: ...
16407
16408 \newline
16409 \SpecialChar ~
16410 \SpecialChar ~
16411 case 2: ...
16412
16413 \newline
16414 \SpecialChar ~
16415 \SpecialChar ~
16416 case 3: ...
16417
16418 \newline
16419 \SpecialChar ~
16420 \SpecialChar ~
16421 case 4: ...
16422
16423 \newline
16424 \SpecialChar ~
16425 \SpecialChar ~
16426 case 9: ...
16427
16428 \newline
16429 \SpecialChar ~
16430 \SpecialChar ~
16431 case 10: ...
16432
16433 \newline
16434 \SpecialChar ~
16435 \SpecialChar ~
16436 case 11: ...
16437
16438 \newline
16439 \SpecialChar ~
16440 \SpecialChar ~
16441 case 12: ...
16442
16443 \newline
16444 }
16445 \layout Standard
16446
16447 If the above switch statement is broken down into two switch statements
16448 \layout Verse
16449
16450
16451 \family typewriter
16452 switch (i) {
16453 \newline
16454 \SpecialChar ~
16455 \SpecialChar ~
16456 case 1: ...
16457
16458 \newline
16459 \SpecialChar ~
16460 \SpecialChar ~
16461 case 2: ...
16462
16463 \newline
16464 \SpecialChar ~
16465 \SpecialChar ~
16466 case 3: ...
16467
16468 \newline
16469 \SpecialChar ~
16470 \SpecialChar ~
16471 case 4: ...
16472
16473 \newline
16474 }
16475 \layout Standard
16476
16477 and
16478 \layout Verse
16479
16480
16481 \family typewriter
16482 switch (i) {
16483 \newline
16484 \SpecialChar ~
16485 \SpecialChar ~
16486 case 9:\SpecialChar ~
16487 \SpecialChar ~
16488 ...
16489
16490 \newline
16491 \SpecialChar ~
16492 \SpecialChar ~
16493 case 10:\SpecialChar ~
16494 ...
16495
16496 \newline
16497 \SpecialChar ~
16498 \SpecialChar ~
16499 case 11:\SpecialChar ~
16500 ...
16501
16502 \newline
16503 \SpecialChar ~
16504 \SpecialChar ~
16505 case 12:\SpecialChar ~
16506 ...
16507
16508 \newline
16509 }
16510 \layout Standard
16511
16512 then both the switch statements will be implemented using jump-tables whereas
16513  the unmodified switch statement will not be.
16514  You might also consider dummy cases 0 and 5 to 8 in this example.
16515
16516 \newline
16517 The pragma NOJTBOUND
16518 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
16519
16520 \end_inset
16521
16522  can be used to turn off checking the
16523 \emph on
16524 j
16525 \emph default
16526 ump
16527 \emph on
16528 t
16529 \emph default
16530 able
16531 \emph on
16532 bound
16533 \emph default
16534 aries.
16535  It has no effect if a default label is supplied.
16536  Use of this pragma is dangerous: if the switch argument is not matched
16537  by a case statement the processor will happily jump into Nirvana.
16538 \layout Subsection
16539
16540 Bit-shifting Operations
16541 \begin_inset LatexCommand \index{Bit shifting}
16542
16543 \end_inset
16544
16545 .
16546 \layout Standard
16547
16548 Bit shifting is one of the most frequently used operation in embedded programmin
16549 g.
16550  SDCC tries to implement bit-shift operations in the most efficient way
16551  possible, e.g.:
16552 \layout Verse
16553
16554
16555 \family typewriter
16556 unsigned char i;
16557 \newline
16558 ...
16559
16560 \newline
16561 i >>= 4;
16562 \newline
16563 ...
16564 \layout Standard
16565
16566 generates the following code:
16567 \layout Verse
16568
16569
16570 \family typewriter
16571 mov\SpecialChar ~
16572  a,_i
16573 \newline
16574 swap a
16575 \newline
16576 anl\SpecialChar ~
16577  a,#0x0f
16578 \newline
16579 mov\SpecialChar ~
16580  _i,a
16581 \layout Standard
16582
16583 In general SDCC will never setup a loop if the shift count is known.
16584  Another example:
16585 \layout Verse
16586
16587
16588 \family typewriter
16589 unsigned int i;
16590 \newline
16591 ...
16592
16593 \newline
16594 i >>= 9;
16595 \newline
16596 ...
16597 \layout Standard
16598
16599 will generate:
16600 \layout Verse
16601
16602
16603 \family typewriter
16604 mov\SpecialChar ~
16605 \SpecialChar ~
16606 a,(_i + 1)
16607 \newline
16608 mov\SpecialChar ~
16609 \SpecialChar ~
16610 (_i + 1),#0x00
16611 \newline
16612 clr\SpecialChar ~
16613 \SpecialChar ~
16614 c
16615 \newline
16616 rrc\SpecialChar ~
16617 \SpecialChar ~
16618 a
16619 \newline
16620 mov\SpecialChar ~
16621 \SpecialChar ~
16622 _i,a
16623 \layout Subsection
16624
16625 Bit-rotation
16626 \begin_inset LatexCommand \index{Bit rotation}
16627
16628 \end_inset
16629
16630
16631 \layout Standard
16632
16633 A special case of the bit-shift operation is bit rotation
16634 \begin_inset LatexCommand \index{rotating bits}
16635
16636 \end_inset
16637
16638 , SDCC recognizes the following expression to be a left bit-rotation:
16639 \layout Verse
16640
16641
16642 \family typewriter
16643 \series bold
16644 unsigned
16645 \series default
16646 \SpecialChar ~
16647 \SpecialChar ~
16648 char i;\SpecialChar ~
16649 \SpecialChar ~
16650 \SpecialChar ~
16651 \SpecialChar ~
16652 \SpecialChar ~
16653 \SpecialChar ~
16654 \SpecialChar ~
16655 \SpecialChar ~
16656 \SpecialChar ~
16657 \SpecialChar ~
16658 \SpecialChar ~
16659 /* unsigned is needed for rotation */
16660 \newline
16661 ...
16662
16663 \newline
16664 i = ((i << 1) | (i >> 7));
16665 \family default
16666
16667 \newline
16668
16669 \family typewriter
16670 ...
16671 \layout Standard
16672
16673 will generate the following code:
16674 \layout Verse
16675
16676
16677 \family typewriter
16678 mov\SpecialChar ~
16679 \SpecialChar ~
16680 a,_i
16681 \newline
16682 rl\SpecialChar ~
16683 \SpecialChar ~
16684 \SpecialChar ~
16685 a
16686 \newline
16687 mov\SpecialChar ~
16688 \SpecialChar ~
16689 _i,a
16690 \layout Standard
16691
16692 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
16693 ns of this case will also be recognized as bit-rotation, i.e.:
16694 \layout Verse
16695
16696
16697 \family typewriter
16698 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
16699 \layout Subsection
16700
16701 Nibble and Byte Swapping
16702 \layout Standard
16703
16704 Other special cases of the bit-shift operations are nibble or byte swapping
16705 \begin_inset LatexCommand \index{swapping nibbles/bytes}
16706
16707 \end_inset
16708
16709 , SDCC recognizes the following expressions:
16710 \layout Verse
16711
16712
16713 \family typewriter
16714 \series bold
16715 unsigned
16716 \series default
16717 \SpecialChar ~
16718 \SpecialChar ~
16719 char i;
16720 \newline
16721
16722 \series bold
16723 unsigned
16724 \series default
16725 \SpecialChar ~
16726 \SpecialChar ~
16727 int j;
16728 \newline
16729 ...
16730
16731 \newline
16732 i = ((i << 4) | (i >> 4));
16733 \family default
16734
16735 \newline
16736
16737 \family typewriter
16738 j = ((j << 8) | (j >> 8));
16739 \layout Standard
16740
16741 and generates a swap instruction for the nibble swapping
16742 \begin_inset LatexCommand \index{Nibble swapping}
16743
16744 \end_inset
16745
16746  or move instructions for the byte swapping
16747 \begin_inset LatexCommand \index{Byte swapping}
16748
16749 \end_inset
16750
16751 .
16752  The
16753 \begin_inset Quotes sld
16754 \end_inset
16755
16756 j
16757 \begin_inset Quotes srd
16758 \end_inset
16759
16760  example can be used to convert from little to big-endian or vice versa.
16761  If you want to change the endianness of a
16762 \emph on
16763 signed
16764 \emph default
16765  integer you have to cast to
16766 \family typewriter
16767 (unsigned int)
16768 \family default
16769  first.
16770 \layout Standard
16771
16772 Note that SDCC stores numbers in little-endian
16773 \begin_inset Foot
16774 collapsed false
16775
16776 \layout Standard
16777
16778 Usually 8-bit processors don't care much about endianness.
16779  This is not the case for the standard 8051 which only has an instruction
16780  to increment its
16781 \emph on
16782 dptr
16783 \emph default
16784
16785 \begin_inset LatexCommand \index{DPTR}
16786
16787 \end_inset
16788
16789 -datapointer
16790 \emph on
16791
16792 \emph default
16793 so little-endian is the more efficient byte order.
16794 \end_inset
16795
16796
16797 \begin_inset LatexCommand \index{little-endian}
16798
16799 \end_inset
16800
16801
16802 \begin_inset LatexCommand \index{Endianness}
16803
16804 \end_inset
16805
16806  format (i.e.
16807  lowest order first).
16808 \layout Subsection
16809
16810 Highest Order Bit
16811 \begin_inset LatexCommand \index{Highest Order Bit}
16812
16813 \end_inset
16814
16815
16816 \layout Standard
16817
16818 It is frequently required to obtain the highest order bit of an integral
16819  type (long, int, short or char types).
16820  SDCC recognizes the following expression to yield the highest order bit
16821  and generates optimized code for it, e.g.:
16822 \layout Verse
16823
16824
16825 \family typewriter
16826 unsigned int gint;
16827 \newline
16828
16829 \newline
16830 foo () {
16831 \newline
16832 \SpecialChar ~
16833 \SpecialChar ~
16834 unsigned char hob;
16835 \newline
16836 \SpecialChar ~
16837 \SpecialChar ~
16838 ...
16839
16840 \newline
16841 \SpecialChar ~
16842 \SpecialChar ~
16843 hob = (gint >> 15) & 1;
16844 \newline
16845 \SpecialChar ~
16846 \SpecialChar ~
16847 ..
16848
16849 \newline
16850 }
16851 \layout Standard
16852
16853 will generate the following code:
16854 \layout Verse
16855
16856
16857 \family typewriter
16858 \SpecialChar ~
16859 \SpecialChar ~
16860 \SpecialChar ~
16861 \SpecialChar ~
16862 \SpecialChar ~
16863 \SpecialChar ~
16864 \SpecialChar ~
16865 \SpecialChar ~
16866 \SpecialChar ~
16867 \SpecialChar ~
16868 \SpecialChar ~
16869 \SpecialChar ~
16870 \SpecialChar ~
16871 \SpecialChar ~
16872 \SpecialChar ~
16873 \SpecialChar ~
16874 \SpecialChar ~
16875 \SpecialChar ~
16876 \SpecialChar ~
16877 \SpecialChar ~
16878 \SpecialChar ~
16879 \SpecialChar ~
16880 \SpecialChar ~
16881 \SpecialChar ~
16882 \SpecialChar ~
16883  61 ;\SpecialChar ~
16884  hob.c 7
16885 \newline
16886 000A E5*01\SpecialChar ~
16887 \SpecialChar ~
16888 \SpecialChar ~
16889 \SpecialChar ~
16890 \SpecialChar ~
16891 \SpecialChar ~
16892 \SpecialChar ~
16893 \SpecialChar ~
16894 \SpecialChar ~
16895 \SpecialChar ~
16896 \SpecialChar ~
16897 \SpecialChar ~
16898 \SpecialChar ~
16899 \SpecialChar ~
16900 \SpecialChar ~
16901  62\SpecialChar ~
16902 \SpecialChar ~
16903 \SpecialChar ~
16904 \SpecialChar ~
16905 \SpecialChar ~
16906 \SpecialChar ~
16907 \SpecialChar ~
16908 \SpecialChar ~
16909  mov\SpecialChar ~
16910 \SpecialChar ~
16911  a,(_gint + 1)
16912 \newline
16913 000C 23\SpecialChar ~
16914 \SpecialChar ~
16915 \SpecialChar ~
16916 \SpecialChar ~
16917 \SpecialChar ~
16918 \SpecialChar ~
16919 \SpecialChar ~
16920 \SpecialChar ~
16921 \SpecialChar ~
16922 \SpecialChar ~
16923 \SpecialChar ~
16924 \SpecialChar ~
16925 \SpecialChar ~
16926 \SpecialChar ~
16927 \SpecialChar ~
16928 \SpecialChar ~
16929 \SpecialChar ~
16930 \SpecialChar ~
16931  63\SpecialChar ~
16932 \SpecialChar ~
16933 \SpecialChar ~
16934 \SpecialChar ~
16935 \SpecialChar ~
16936 \SpecialChar ~
16937 \SpecialChar ~
16938 \SpecialChar ~
16939  rl\SpecialChar ~
16940 \SpecialChar ~
16941 \SpecialChar ~
16942  a
16943 \newline
16944 000D 54 01\SpecialChar ~
16945 \SpecialChar ~
16946 \SpecialChar ~
16947 \SpecialChar ~
16948 \SpecialChar ~
16949 \SpecialChar ~
16950 \SpecialChar ~
16951 \SpecialChar ~
16952 \SpecialChar ~
16953 \SpecialChar ~
16954 \SpecialChar ~
16955 \SpecialChar ~
16956 \SpecialChar ~
16957 \SpecialChar ~
16958 \SpecialChar ~
16959  64\SpecialChar ~
16960 \SpecialChar ~
16961 \SpecialChar ~
16962 \SpecialChar ~
16963 \SpecialChar ~
16964 \SpecialChar ~
16965 \SpecialChar ~
16966 \SpecialChar ~
16967  anl\SpecialChar ~
16968 \SpecialChar ~
16969  a,#0x01
16970 \newline
16971 000F F5*02\SpecialChar ~
16972 \SpecialChar ~
16973 \SpecialChar ~
16974 \SpecialChar ~
16975 \SpecialChar ~
16976 \SpecialChar ~
16977 \SpecialChar ~
16978 \SpecialChar ~
16979 \SpecialChar ~
16980 \SpecialChar ~
16981 \SpecialChar ~
16982 \SpecialChar ~
16983 \SpecialChar ~
16984 \SpecialChar ~
16985 \SpecialChar ~
16986  65\SpecialChar ~
16987 \SpecialChar ~
16988 \SpecialChar ~
16989 \SpecialChar ~
16990 \SpecialChar ~
16991 \SpecialChar ~
16992 \SpecialChar ~
16993 \SpecialChar ~
16994  mov\SpecialChar ~
16995 \SpecialChar ~
16996  _foo_hob_1_1,a
16997 \layout Standard
16998
16999 Variations of this case however will
17000 \emph on
17001 not
17002 \emph default
17003  be recognized.
17004  It is a standard C expression, so I heartily recommend this be the only
17005  way to get the highest order bit, (it is portable).
17006  Of course it will be recognized even if it is embedded in other expressions,
17007  e.g.:
17008 \layout Verse
17009
17010
17011 \family typewriter
17012 xyz = gint + ((gint >> 15) & 1);
17013 \layout Standard
17014
17015 will still be recognized.
17016 \layout Subsection
17017
17018 Peephole Optimizer
17019 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
17020
17021 \end_inset
17022
17023
17024 \begin_inset LatexCommand \index{Peephole optimizer}
17025
17026 \end_inset
17027
17028
17029 \layout Standard
17030
17031 The compiler uses a rule based, pattern matching and re-writing mechanism
17032  for peep-hole optimization.
17033  It is inspired by
17034 \emph on
17035 copt
17036 \emph default
17037  a peep-hole optimizer by Christopher W.
17038  Fraser (cwfraser@microsoft.com).
17039  A default set of rules are compiled into the compiler, additional rules
17040  may be added with the
17041 \emph on
17042 -
17043 \begin_inset ERT
17044 status Collapsed
17045
17046 \layout Standard
17047
17048 \backslash
17049 /
17050 \end_inset
17051
17052 -peep-file
17053 \begin_inset LatexCommand \index{-\/-peep-file}
17054
17055 \end_inset
17056
17057  <filename>
17058 \emph default
17059  option.
17060  The rule language is best illustrated with examples.
17061 \layout Verse
17062
17063
17064 \family typewriter
17065 replace {
17066 \newline
17067 \SpecialChar ~
17068 \SpecialChar ~
17069 mov %1,a
17070 \newline
17071 \SpecialChar ~
17072 \SpecialChar ~
17073 mov a,%1
17074 \newline
17075 } by {
17076 \newline
17077 \SpecialChar ~
17078 \SpecialChar ~
17079 mov %1,a
17080 \newline
17081 }
17082 \layout Standard
17083
17084 The above rule will change the following assembly
17085 \begin_inset LatexCommand \index{Assembler routines}
17086
17087 \end_inset
17088
17089  sequence:
17090 \layout Verse
17091
17092
17093 \family typewriter
17094 mov r1,a
17095 \newline
17096 mov a,r1
17097 \layout Standard
17098
17099 to
17100 \layout Verse
17101
17102
17103 \family typewriter
17104 mov r1,a
17105 \layout Standard
17106
17107 Note: All occurrences of a
17108 \emph on
17109 %n
17110 \emph default
17111  (pattern variable) must denote the same string.
17112  With the above rule, the assembly sequence:
17113 \layout Verse
17114
17115
17116 \family typewriter
17117 mov r1,a
17118 \newline
17119 mov a,r2
17120 \layout Standard
17121
17122 will remain unmodified.
17123 \newline
17124
17125 \newline
17126 Other special case optimizations may be added by the user (via
17127 \emph on
17128 -
17129 \begin_inset ERT
17130 status Collapsed
17131
17132 \layout Standard
17133
17134 \backslash
17135 /
17136 \end_inset
17137
17138 -peep-file option
17139 \emph default
17140 ).
17141  E.g.
17142  some variants of the 8051 MCU allow only
17143 \family typewriter
17144 ajmp
17145 \family default
17146  and
17147 \family typewriter
17148 acall
17149 \family default
17150 .
17151  The following two rules will change all
17152 \family typewriter
17153 ljmp
17154 \family default
17155  and
17156 \family typewriter
17157 lcall
17158 \family default
17159  to
17160 \family typewriter
17161 ajmp
17162 \family default
17163  and
17164 \family typewriter
17165 acall
17166 \layout Verse
17167
17168
17169 \family typewriter
17170 replace { lcall %1 } by { acall %1 }
17171 \newline
17172 replace { ljmp %1 } by { ajmp %1 }
17173 \layout Standard
17174
17175 The
17176 \emph on
17177 inline-assembler code
17178 \emph default
17179  is also passed through the peep hole optimizer, thus the peephole optimizer
17180  can also be used as an assembly level macro expander.
17181  The rules themselves are MCU dependent whereas the rule language infra-structur
17182 e is MCU independent.
17183  Peephole optimization rules for other MCU can be easily programmed using
17184  the rule language.
17185 \newline
17186
17187 \newline
17188 The syntax for a rule is as follows:
17189 \layout Verse
17190
17191
17192 \family typewriter
17193 rule := replace [ restart ] '{' <assembly sequence> '
17194 \backslash
17195 n'
17196 \newline
17197 \SpecialChar ~
17198  \SpecialChar ~
17199  \SpecialChar ~
17200  \SpecialChar ~
17201  \SpecialChar ~
17202  \SpecialChar ~
17203  \SpecialChar ~
17204  \SpecialChar ~
17205  \SpecialChar ~
17206  \SpecialChar ~
17207  \SpecialChar ~
17208  \SpecialChar ~
17209  \SpecialChar ~
17210  \SpecialChar ~
17211  '}' by '{' '
17212 \backslash
17213 n'
17214 \newline
17215 \SpecialChar ~
17216  \SpecialChar ~
17217  \SpecialChar ~
17218  \SpecialChar ~
17219  \SpecialChar ~
17220  \SpecialChar ~
17221  \SpecialChar ~
17222  \SpecialChar ~
17223  \SpecialChar ~
17224  \SpecialChar ~
17225  \SpecialChar ~
17226  \SpecialChar ~
17227  \SpecialChar ~
17228  \SpecialChar ~
17229  \SpecialChar ~
17230  \SpecialChar ~
17231  <assembly sequence> '
17232 \backslash
17233 n'
17234 \newline
17235 \SpecialChar ~
17236  \SpecialChar ~
17237  \SpecialChar ~
17238  \SpecialChar ~
17239  \SpecialChar ~
17240  \SpecialChar ~
17241  \SpecialChar ~
17242  \SpecialChar ~
17243  \SpecialChar ~
17244  \SpecialChar ~
17245  \SpecialChar ~
17246  \SpecialChar ~
17247  \SpecialChar ~
17248  \SpecialChar ~
17249  '}' [if <functionName> ] '
17250 \backslash
17251 n'
17252 \layout Standard
17253
17254 <assembly sequence> := assembly instruction (each instruction including
17255  labels must be on a separate line).
17256 \newline
17257
17258 \newline
17259 The optimizer will apply to the rules one by one from the top in the sequence
17260  of their appearance, it will terminate when all rules are exhausted.
17261  If the 'restart' option is specified, then the optimizer will start matching
17262  the rules again from the top, this option for a rule is expensive (performance)
17263 , it is intended to be used in situations where a transformation will trigger
17264  the same rule again.
17265  An example of this (not a good one, it has side effects) is the following
17266  rule:
17267 \layout Verse
17268
17269
17270 \family typewriter
17271 replace restart {
17272 \newline
17273 \SpecialChar ~
17274 \SpecialChar ~
17275 pop %1
17276 \newline
17277 \SpecialChar ~
17278 \SpecialChar ~
17279 push %1 } by {
17280 \newline
17281 \SpecialChar ~
17282 \SpecialChar ~
17283 ; nop
17284 \newline
17285 }
17286 \layout Standard
17287
17288 Note that the replace pattern cannot be a blank, but can be a comment line.
17289  Without the 'restart' option only the inner most 'pop' 'push' pair would
17290  be eliminated, i.e.:
17291 \layout Verse
17292
17293
17294 \family typewriter
17295 pop ar1
17296 \newline
17297 pop ar2
17298 \newline
17299 push ar2
17300 \newline
17301 push ar1
17302 \layout Standard
17303
17304 would result in:
17305 \layout Verse
17306
17307
17308 \family typewriter
17309 pop ar1
17310 \newline
17311 ; nop
17312 \newline
17313 push ar1
17314 \layout Standard
17315
17316
17317 \emph on
17318 with
17319 \emph default
17320  the restart option the rule will be applied again to the resulting code
17321  and then all the pop-push pairs will be eliminated to yield:
17322 \layout Verse
17323
17324
17325 \family typewriter
17326 ; nop
17327 \newline
17328 ; nop
17329 \layout Standard
17330
17331 A conditional function can be attached to a rule.
17332  Attaching rules are somewhat more involved, let me illustrate this with
17333  an example.
17334 \layout Verse
17335
17336
17337 \family typewriter
17338 replace {
17339 \newline
17340 \SpecialChar ~
17341  \SpecialChar ~
17342  \SpecialChar ~
17343 ljmp %5
17344 \newline
17345 %2:
17346 \newline
17347 } by {
17348 \newline
17349 \SpecialChar ~
17350  \SpecialChar ~
17351  \SpecialChar ~
17352 sjmp %5
17353 \newline
17354 %2:
17355 \newline
17356 } if labelInRange
17357 \layout Standard
17358
17359 The optimizer does a look-up of a function name table defined in function
17360
17361 \emph on
17362 callFuncByName
17363 \emph default
17364  in the source file SDCCpeeph.c, with the name
17365 \emph on
17366 labelInRange
17367 \emph default
17368 .
17369  If it finds a corresponding entry the function is called.
17370  Note there can be no parameters specified for these functions, in this
17371  case the use of
17372 \emph on
17373 %5
17374 \emph default
17375  is crucial, since the function
17376 \emph on
17377 labelInRange
17378 \emph default
17379  expects to find the label in that particular variable (the hash table containin
17380 g the variable bindings is passed as a parameter).
17381  If you want to code more such functions, take a close look at the function
17382  labelInRange and the calling mechanism in source file SDCCpeeph.c.
17383  Currently implemented are
17384 \emph on
17385 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
17386  24bitMode, portIsDS390, 24bitModeAndPortDS390
17387 \emph default
17388 and
17389 \emph on
17390  notVolatile
17391 \emph default
17392 .
17393 \layout Standard
17394
17395 I know this whole thing is a little kludgey, but maybe some day we will
17396  have some better means.
17397  If you are looking at this file, you will see the default rules that are
17398  compiled into the compiler, you can add your own rules in the default set
17399  there if you get tired of specifying the -
17400 \begin_inset ERT
17401 status Collapsed
17402
17403 \layout Standard
17404
17405 \backslash
17406 /
17407 \end_inset
17408
17409 -peep-file option.
17410 \layout Section
17411
17412 Library Routines
17413 \emph on
17414
17415 \layout Standard
17416
17417
17418 \emph on
17419 <pending: this is messy and incomplete>
17420 \emph default
17421
17422 \layout Enumerate
17423
17424 Compiler support routines (_gptrget, _mulint etc)
17425 \layout Enumerate
17426
17427 Stdclib functions (puts, printf, strcat etc)
17428 \layout Enumerate
17429
17430 Math functions (sin, pow, sqrt etc)
17431 \layout Standard
17432
17433 Libraries
17434 \begin_inset LatexCommand \index{Libraries}
17435
17436 \end_inset
17437
17438  included in SDCC should have a license at least as liberal as the GNU Lesser
17439  General Public License
17440 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
17441
17442 \end_inset
17443
17444
17445 \emph on
17446 LGPL
17447 \emph default
17448 .
17449 \layout Comment
17450
17451 license statements for the libraries are missing.
17452  sdcc/device/lib/ser_ir.c
17453 \layout Comment
17454
17455 or _decdptr f.e.
17456  come with a GPL (as opposed to LGPL) License - this will not be liberal
17457  enough for many embedded programmers.
17458 \layout Standard
17459
17460 If you have ported some library or want to share experience about some code
17461  which f.e.
17462  falls into any of these categories Busses (I
17463 \begin_inset Formula $^{\textrm{2}}$
17464 \end_inset
17465
17466 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
17467  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
17468  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
17469 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
17470
17471 \end_inset
17472
17473 \SpecialChar ~
17474 would certainly like to hear about it.
17475  Programmers coding for embedded systems are not especially famous for being
17476  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
17477 e these references are very valuable.
17478 \layout Section
17479
17480 External Stack
17481 \begin_inset LatexCommand \label{sub:External-Stack}
17482
17483 \end_inset
17484
17485
17486 \begin_inset LatexCommand \index{stack}
17487
17488 \end_inset
17489
17490
17491 \begin_inset LatexCommand \index{External stack}
17492
17493 \end_inset
17494
17495
17496 \layout Standard
17497
17498 The external stack (-
17499 \begin_inset ERT
17500 status Collapsed
17501
17502 \layout Standard
17503
17504 \backslash
17505 /
17506 \end_inset
17507
17508 -xstack option
17509 \begin_inset LatexCommand \index{-\/-xstack}
17510
17511 \end_inset
17512
17513 ) is located at the start of the external ram segment, and is 256 bytes
17514  in size.
17515  When -
17516 \begin_inset ERT
17517 status Collapsed
17518
17519 \layout Standard
17520
17521 \backslash
17522 /
17523 \end_inset
17524
17525 -xstack option is used to compile the program, the parameters and local
17526  variables of all reentrant functions are allocated in this area.
17527  This option is provided for programs with large stack space requirements.
17528  When used with the -
17529 \begin_inset ERT
17530 status Collapsed
17531
17532 \layout Standard
17533
17534 \backslash
17535 /
17536 \end_inset
17537
17538 -stack-auto
17539 \begin_inset LatexCommand \index{-\/-stack-auto}
17540
17541 \end_inset
17542
17543  option, all parameters and local variables are allocated on the external
17544  stack (note support libraries will need to be recompiled with the same
17545  options).
17546 \layout Standard
17547
17548 The compiler outputs the higher order address byte of the external ram segment
17549  into PORT P2, therefore when using the External Stack option, this port
17550  MAY NOT be used by the application program.
17551 \layout Section
17552
17553 ANSI-Compliance
17554 \begin_inset LatexCommand \index{ANSI-compliance}
17555
17556 \end_inset
17557
17558
17559 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
17560
17561 \end_inset
17562
17563
17564 \layout Standard
17565
17566 Deviations from the compliance:
17567 \layout Itemize
17568
17569 functions are not always reentrant
17570 \begin_inset LatexCommand \index{reentrant}
17571
17572 \end_inset
17573
17574 .
17575 \layout Itemize
17576
17577 structures cannot be assigned values directly, cannot be passed as function
17578  parameters or assigned to each other and cannot be a return value from
17579  a function, e.g.:
17580 \begin_deeper
17581 \layout Verse
17582
17583
17584 \family typewriter
17585 struct s { ...
17586  };
17587 \newline
17588 struct s s1, s2;
17589 \newline
17590 foo()
17591 \newline
17592 {
17593 \newline
17594 \SpecialChar ~
17595 \SpecialChar ~
17596 \SpecialChar ~
17597 \SpecialChar ~
17598 ...
17599
17600 \newline
17601 \SpecialChar ~
17602 \SpecialChar ~
17603 \SpecialChar ~
17604 \SpecialChar ~
17605 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
17606 \newline
17607 \SpecialChar ~
17608 \SpecialChar ~
17609 \SpecialChar ~
17610 \SpecialChar ~
17611 ...
17612
17613 \newline
17614 }
17615 \newline
17616 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
17617  */
17618 \newline
17619 {
17620 \newline
17621 \SpecialChar ~
17622 \SpecialChar ~
17623 \SpecialChar ~
17624 \SpecialChar ~
17625 struct s rets;
17626 \newline
17627 \SpecialChar ~
17628 \SpecialChar ~
17629 \SpecialChar ~
17630 \SpecialChar ~
17631 ...
17632
17633 \newline
17634 \SpecialChar ~
17635 \SpecialChar ~
17636 \SpecialChar ~
17637 \SpecialChar ~
17638 return rets;/* is invalid in SDCC although allowed in ANSI */
17639 \newline
17640 }
17641 \end_deeper
17642 \layout Itemize
17643
17644 'long long
17645 \begin_inset LatexCommand \index{long long (not supported)}
17646
17647 \end_inset
17648
17649 ' (64 bit integers
17650 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
17651
17652 \end_inset
17653
17654 ) not supported.
17655 \layout Itemize
17656
17657 'double
17658 \begin_inset LatexCommand \index{double (not supported)}
17659
17660 \end_inset
17661
17662 ' precision floating point
17663 \begin_inset LatexCommand \index{Floating point support}
17664
17665 \end_inset
17666
17667 not supported.
17668 \layout Itemize
17669
17670 No support for setjmp
17671 \begin_inset LatexCommand \index{setjmp (not supported)}
17672
17673 \end_inset
17674
17675  and longjmp
17676 \begin_inset LatexCommand \index{longjmp (not supported)}
17677
17678 \end_inset
17679
17680  (for now).
17681 \layout Itemize
17682
17683 Old K&R style
17684 \begin_inset LatexCommand \index{K\&R style}
17685
17686 \end_inset
17687
17688  function declarations are NOT allowed.
17689 \begin_deeper
17690 \layout Verse
17691
17692
17693 \family typewriter
17694 foo(i,j) /* this old style of function declarations */
17695 \newline
17696 int i,j; /* are valid in ANSI but not valid in SDCC */
17697 \newline
17698 {
17699 \newline
17700 \SpecialChar ~
17701 \SpecialChar ~
17702 \SpecialChar ~
17703 \SpecialChar ~
17704 ...
17705
17706 \newline
17707 }
17708 \end_deeper
17709 \layout Itemize
17710
17711 functions declared as pointers
17712 \begin_inset LatexCommand \index{Pointers}
17713
17714 \end_inset
17715
17716
17717 \begin_inset LatexCommand \index{function pointers}
17718
17719 \end_inset
17720
17721  must be dereferenced during the call.
17722 \begin_deeper
17723 \layout Verse
17724
17725
17726 \family typewriter
17727 int (*foo)();
17728 \newline
17729 ...
17730
17731 \newline
17732 /* has to be called like this */
17733 \newline
17734 (*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
17735 \end_deeper
17736 \layout Section
17737
17738 Cyclomatic Complexity
17739 \begin_inset LatexCommand \index{Cyclomatic complexity}
17740
17741 \end_inset
17742
17743
17744 \layout Standard
17745
17746 Cyclomatic complexity of a function is defined as the number of independent
17747  paths the program can take during execution of the function.
17748  This is an important number since it defines the number test cases you
17749  have to generate to validate the function.
17750  The accepted industry standard for complexity number is 10, if the cyclomatic
17751  complexity reported by SDCC exceeds 10 you should think about simplification
17752  of the function logic.
17753  Note that the complexity level is not related to the number of lines of
17754  code in a function.
17755  Large functions can have low complexity, and small functions can have large
17756  complexity levels.
17757
17758 \newline
17759
17760 \newline
17761 SDCC uses the following formula to compute the complexity:
17762 \newline
17763
17764 \layout Standard
17765
17766 complexity = (number of edges in control flow graph) - (number of nodes
17767  in control flow graph) + 2;
17768 \newline
17769
17770 \newline
17771 Having said that the industry standard is 10, you should be aware that in
17772  some cases it be may unavoidable to have a complexity level of less than
17773  10.
17774  For example if you have switch statement with more than 10 case labels,
17775  each case label adds one to the complexity level.
17776  The complexity level is by no means an absolute measure of the algorithmic
17777  complexity of the function, it does however provide a good starting point
17778  for which functions you might look at for further optimization.
17779 \layout Section
17780
17781 Other Processors
17782 \layout Subsection
17783
17784 MCS51 variants
17785 \begin_inset LatexCommand \label{sub:MCS51-variants}
17786
17787 \end_inset
17788
17789
17790 \begin_inset LatexCommand \index{MCS51 variants}
17791
17792 \end_inset
17793
17794
17795 \layout Standard
17796
17797 MCS51 processors are available from many vendors and come in many different
17798  flavours.
17799  While they might differ considerably in respect to Special Function Registers
17800  the core MCS51 is usually not modified or is kept compatible.
17801
17802 \layout Subsubsection*
17803
17804 pdata access by SFR
17805 \begin_inset LatexCommand \index{sfr}
17806
17807 \end_inset
17808
17809
17810 \layout Standard
17811
17812 With the upcome of devices with internal xdata and flash memory devices
17813  using port P2 as dedicated I/O port is becoming more popular.
17814  Switching the high byte for pdata
17815 \begin_inset LatexCommand \index{pdata}
17816
17817 \end_inset
17818
17819  access which was formerly done by port P2 is then achieved by a Special
17820  Function Register.
17821  In well-established MCS51 tradition the address of this
17822 \emph on
17823 sfr
17824 \emph default
17825  is where the chip designers decided to put it.
17826  As pdata addressing is used in the startup code for the initialization
17827  of xdata variables a separate startup code should be used as described
17828  in section
17829 \begin_inset LatexCommand \ref{sub:Startup-Code}
17830
17831 \end_inset
17832
17833 .
17834 \layout Subsubsection*
17835
17836 Other Features available by SFR
17837 \layout Standard
17838
17839 Some MCS51 variants offer features like Double DPTR
17840 \begin_inset LatexCommand \index{DPTR}
17841
17842 \end_inset
17843
17844 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
17845  These are currently not used for the MCS51 port.
17846  If you absolutely need them you can fall back to inline assembly or submit
17847  a patch to SDCC.
17848 \layout Subsection
17849
17850 The Z80 and gbz80 port
17851 \layout Standard
17852
17853 SDCC can target both the Zilog
17854 \begin_inset LatexCommand \index{Z80}
17855
17856 \end_inset
17857
17858  and the Nintendo Gameboy's Z80-like gbz80
17859 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
17860
17861 \end_inset
17862
17863 .
17864  The Z80 port is passed through the same
17865 \emph on
17866 regressions tests
17867 \begin_inset LatexCommand \index{Regression test}
17868
17869 \end_inset
17870
17871
17872 \emph default
17873  as MCS51 and DS390 ports, so floating point support, support for long variables
17874  and bitfield support is fine.
17875  See mailing lists and forums about interrupt routines and access to I/O
17876  memory.
17877 \layout Standard
17878
17879 As always, the code is the authoritative reference - see z80/ralloc.c and
17880  z80/gen.c.
17881  The stack
17882 \begin_inset LatexCommand \index{stack}
17883
17884 \end_inset
17885
17886  frame is similar to that generated by the IAR Z80 compiler.
17887  IX is used as the base pointer, HL is used as a temporary register, and
17888  BC and DE are available for holding variables.
17889  IY is currently unused.
17890  Return values
17891 \begin_inset LatexCommand \index{return value}
17892
17893 \end_inset
17894
17895  are stored in HL.
17896  One bad side effect of using IX as the base pointer is that a functions
17897  stack frame is limited to 127 bytes - this will be fixed in a later version.
17898 \layout Subsection
17899
17900 The HC08 port
17901 \layout Standard
17902
17903 The port to the Motorola HC08
17904 \begin_inset LatexCommand \index{HC08}
17905
17906 \end_inset
17907
17908  family has been added in October 2003, thank you Erik!
17909 \layout Section
17910
17911 Retargetting for other MCUs.
17912 \layout Standard
17913
17914 The issues for retargetting the compiler are far too numerous to be covered
17915  by this document.
17916  What follows is a brief description of each of the seven phases of the
17917  compiler and its MCU dependency.
17918 \layout Itemize
17919
17920 Parsing the source and building the annotated parse tree.
17921  This phase is largely MCU independent (except for the language extensions).
17922  Syntax & semantic checks are also done in this phase, along with some initial
17923  optimizations like back patching labels and the pattern matching optimizations
17924  like bit-rotation etc.
17925 \layout Itemize
17926
17927 The second phase involves generating an intermediate code which can be easy
17928  manipulated during the later phases.
17929  This phase is entirely MCU independent.
17930  The intermediate code generation assumes the target machine has unlimited
17931  number of registers, and designates them with the name iTemp.
17932  The compiler can be made to dump a human readable form of the code generated
17933  by using the -
17934 \begin_inset ERT
17935 status Collapsed
17936
17937 \layout Standard
17938
17939 \backslash
17940 /
17941 \end_inset
17942
17943 -dumpraw option.
17944 \layout Itemize
17945
17946 This phase does the bulk of the standard optimizations and is also MCU independe
17947 nt.
17948  This phase can be broken down into several sub-phases:
17949 \newline
17950
17951 \newline
17952 Break down intermediate code (iCode) into basic blocks.
17953 \newline
17954 Do control flow & data flow analysis on the basic blocks.
17955 \newline
17956 Do local common subexpression elimination, then global subexpression elimination
17957 \newline
17958 Dead code elimination
17959 \newline
17960 Loop optimizations
17961 \newline
17962 If loop optimizations caused any changes then do 'global subexpression eliminati
17963 on' and 'dead code elimination' again.
17964 \layout Itemize
17965
17966 This phase determines the live-ranges; by live range I mean those iTemp
17967  variables defined by the compiler that still survive after all the optimization
17968 s.
17969  Live range analysis
17970 \begin_inset LatexCommand \index{Live range analysis}
17971
17972 \end_inset
17973
17974  is essential for register allocation, since these computation determines
17975  which of these iTemps will be assigned to registers, and for how long.
17976 \layout Itemize
17977
17978 Phase five is register allocation.
17979  There are two parts to this process.
17980 \newline
17981
17982 \newline
17983 The first part I call 'register packing' (for lack of a better term).
17984  In this case several MCU specific expression folding is done to reduce
17985  register pressure.
17986 \newline
17987
17988 \newline
17989 The second part is more MCU independent and deals with allocating registers
17990  to the remaining live ranges.
17991  A lot of MCU specific code does creep into this phase because of the limited
17992  number of index registers available in the 8051.
17993 \layout Itemize
17994
17995 The Code generation phase is (unhappily), entirely MCU dependent and very
17996  little (if any at all) of this code can be reused for other MCU.
17997  However the scheme for allocating a homogenized assembler operand for each
17998  iCode operand may be reused.
17999 \layout Itemize
18000
18001 As mentioned in the optimization section the peep-hole optimizer is rule
18002  based system, which can reprogrammed for other MCUs.
18003 \layout Chapter
18004
18005 Compiler internals
18006 \begin_inset LatexCommand \index{Compiler internals}
18007
18008 \end_inset
18009
18010
18011 \layout Section
18012
18013 The anatomy of the compiler
18014 \begin_inset LatexCommand \label{sub:The-anatomy-of}
18015
18016 \end_inset
18017
18018
18019 \layout Standard
18020
18021
18022 \shape italic
18023 This is an excerpt from an article published in Circuit Cellar Magazine
18024  in august 2000.
18025  It's a little outdated (the compiler is much more efficient now and user/develo
18026 per friendly), but pretty well exposes the guts of it all.
18027 \shape default
18028
18029 \newline
18030
18031 \newline
18032 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
18033  It is fairly easy to retarget for other 8-bit MCU.
18034  Here we take a look at some of the internals of the compiler.
18035
18036 \layout Paragraph*
18037
18038 Parsing
18039 \begin_inset LatexCommand \index{Parsing}
18040
18041 \end_inset
18042
18043
18044 \layout Standard
18045
18046 Parsing the input source file and creating an AST (Annotated Syntax Tree
18047 \begin_inset LatexCommand \index{Annotated syntax tree}
18048
18049 \end_inset
18050
18051 ).
18052  This phase also involves propagating types (annotating each node of the
18053  parse tree with type information) and semantic analysis.
18054  There are some MCU specific parsing rules.
18055  For example the storage classes, the extended storage classes are MCU specific
18056  while there may be a xdata storage class for 8051 there is no such storage
18057  class for z80 or Atmel AVR.
18058  SDCC allows MCU specific storage class extensions, i.e.
18059  xdata will be treated as a storage class specifier when parsing 8051 C
18060  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
18061  C code.
18062 \layout Paragraph*
18063
18064 Generating iCode
18065 \begin_inset LatexCommand \index{iCode}
18066
18067 \end_inset
18068
18069
18070 \layout Standard
18071
18072 Intermediate code generation.
18073  In this phase the AST is broken down into three-operand form (iCode).
18074  These three operand forms are represented as doubly linked lists.
18075  ICode is the term given to the intermediate form generated by the compiler.
18076  ICode example section shows some examples of iCode generated for some simple
18077  C source functions.
18078 \layout Paragraph*
18079
18080 Optimizations
18081 \begin_inset LatexCommand \index{Optimizations}
18082
18083 \end_inset
18084
18085 .
18086 \layout Standard
18087
18088 Bulk of the target independent optimizations is performed in this phase.
18089  The optimizations include constant propagation, common sub-expression eliminati
18090 on, loop invariant code movement, strength reduction of loop induction variables
18091  and dead-code elimination.
18092 \layout Paragraph*
18093
18094 Live range analysis
18095 \begin_inset LatexCommand \index{Live range analysis}
18096
18097 \end_inset
18098
18099
18100 \layout Standard
18101
18102 During intermediate code generation phase, the compiler assumes the target
18103  machine has infinite number of registers and generates a lot of temporary
18104  variables.
18105  The live range computation determines the lifetime of each of these compiler-ge
18106 nerated temporaries.
18107  A picture speaks a thousand words.
18108  ICode example sections show the live range annotations for each of the
18109  operand.
18110  It is important to note here, each iCode is assigned a number in the order
18111  of its execution in the function.
18112  The live ranges are computed in terms of these numbers.
18113  The from number is the number of the iCode which first defines the operand
18114  and the to number signifies the iCode which uses this operand last.
18115 \layout Paragraph*
18116
18117 Register Allocation
18118 \begin_inset LatexCommand \index{Register allocation}
18119
18120 \end_inset
18121
18122
18123 \layout Standard
18124
18125 The register allocation determines the type and number of registers needed
18126  by each operand.
18127  In most MCUs only a few registers can be used for indirect addressing.
18128  In case of 8051 for example the registers R0 & R1 can be used to indirectly
18129  address the internal ram and DPTR to indirectly address the external ram.
18130  The compiler will try to allocate the appropriate register to pointer variables
18131  if it can.
18132  ICode example section shows the operands annotated with the registers assigned
18133  to them.
18134  The compiler will try to keep operands in registers as much as possible;
18135  there are several schemes the compiler uses to do achieve this.
18136  When the compiler runs out of registers the compiler will check to see
18137  if there are any live operands which is not used or defined in the current
18138  basic block being processed, if there are any found then it will push that
18139  operand and use the registers in this block, the operand will then be popped
18140  at the end of the basic block.
18141
18142 \layout Standard
18143
18144 There are other MCU specific considerations in this phase.
18145  Some MCUs have an accumulator; very short-lived operands could be assigned
18146  to the accumulator instead of general-purpose register.
18147 \layout Paragraph*
18148
18149 Code generation
18150 \layout Standard
18151
18152 Figure II gives a table of iCode operations supported by the compiler.
18153  The code generation involves translating these operations into corresponding
18154  assembly code for the processor.
18155  This sounds overly simple but that is the essence of code generation.
18156  Some of the iCode operations are generated on a MCU specific manner for
18157  example, the z80 port does not use registers to pass parameters so the
18158  SEND and RECV iCode operations will not be generated, and it also does
18159  not support JUMPTABLES.
18160
18161 \newline
18162
18163 \series bold
18164 \shape italic
18165 \color red
18166 <Where is Figure II ?>
18167 \layout Paragraph*
18168
18169 ICode Example
18170 \begin_inset LatexCommand \index{iCode}
18171
18172 \end_inset
18173
18174
18175 \layout Standard
18176
18177 This section shows some details of iCode.
18178  The example C code does not do anything useful; it is used as an example
18179  to illustrate the intermediate code generated by the compiler.
18180 \layout Verse
18181
18182
18183 \family typewriter
18184 1.\SpecialChar ~
18185 xdata int * p;
18186 \newline
18187 2.\SpecialChar ~
18188 int gint;
18189 \newline
18190 3.\SpecialChar ~
18191 /* This function does nothing useful.
18192  It is used
18193 \newline
18194 4.\SpecialChar ~
18195 \SpecialChar ~
18196 \SpecialChar ~
18197 \SpecialChar ~
18198 for the purpose of explaining iCode */
18199 \newline
18200 5.\SpecialChar ~
18201 short function (data int *x)
18202 \newline
18203 6.\SpecialChar ~
18204 {
18205 \newline
18206 7.\SpecialChar ~
18207 \SpecialChar ~
18208 \SpecialChar ~
18209 short i=10; /* dead initialization eliminated */
18210 \newline
18211 8.\SpecialChar ~
18212 \SpecialChar ~
18213 \SpecialChar ~
18214 short sum=10; /* dead initialization eliminated */
18215 \newline
18216 9.\SpecialChar ~
18217 \SpecialChar ~
18218 \SpecialChar ~
18219 short mul;
18220 \newline
18221 10.\SpecialChar ~
18222 \SpecialChar ~
18223 int j ;
18224 \newline
18225 11.\SpecialChar ~
18226 \SpecialChar ~
18227 while (*x) *x++ = *p++;
18228 \newline
18229 12.\SpecialChar ~
18230 \SpecialChar ~
18231 \SpecialChar ~
18232 \SpecialChar ~
18233 sum = 0 ;
18234 \newline
18235 13.\SpecialChar ~
18236 \SpecialChar ~
18237 mul = 0;
18238 \newline
18239 14.\SpecialChar ~
18240 \SpecialChar ~
18241 /* compiler detects i,j to be induction variables */
18242 \newline
18243 15.\SpecialChar ~
18244 \SpecialChar ~
18245 for (i = 0, j = 10 ; i < 10 ; i++, j
18246 \family default
18247 -
18248 \begin_inset ERT
18249 status Collapsed
18250
18251 \layout Standard
18252
18253 \backslash
18254 /
18255 \end_inset
18256
18257 -
18258 \family typewriter
18259 ) {
18260 \newline
18261 16.\SpecialChar ~
18262 \SpecialChar ~
18263 \SpecialChar ~
18264 \SpecialChar ~
18265 sum += i;
18266 \newline
18267 17.\SpecialChar ~
18268 \SpecialChar ~
18269 \SpecialChar ~
18270 \SpecialChar ~
18271 mul += i * 3; /* this multiplication remains */
18272 \newline
18273 18.\SpecialChar ~
18274 \SpecialChar ~
18275 \SpecialChar ~
18276 \SpecialChar ~
18277 gint += j * 3;/* this multiplication changed to addition */
18278 \newline
18279 19.\SpecialChar ~
18280 \SpecialChar ~
18281 }
18282 \newline
18283 20.\SpecialChar ~
18284 \SpecialChar ~
18285 return sum+mul;
18286 \newline
18287 21.\SpecialChar ~
18288 }
18289 \layout Standard
18290
18291 In addition to the operands each iCode contains information about the filename
18292  and line it corresponds to in the source file.
18293  The first field in the listing should be interpreted as follows:
18294 \newline
18295
18296 \shape italic
18297 \size footnotesize
18298 Filename(linenumber: iCode Execution sequence number : ICode hash table
18299  key : loop depth of the iCode).
18300 \shape default
18301 \size default
18302
18303 \newline
18304 Then follows the human readable form of the ICode operation.
18305  Each operand of this triplet form can be of three basic types a) compiler
18306  generated temporary b) user defined variable c) a constant value.
18307  Note that local variables and parameters are replaced by compiler generated
18308  temporaries.
18309  Live ranges
18310 \begin_inset LatexCommand \index{Live range analysis}
18311
18312 \end_inset
18313
18314  are computed only for temporaries (i.e.
18315  live ranges are not computed for global variables).
18316  Registers
18317 \begin_inset LatexCommand \index{Register allocation}
18318
18319 \end_inset
18320
18321  are allocated for temporaries only.
18322  Operands are formatted in the following manner:
18323 \newline
18324
18325 \shape italic
18326 \size footnotesize
18327 Operand Name [lr live-from : live-to ] { type information } [ registers
18328  allocated ].
18329 \shape default
18330 \size default
18331
18332 \newline
18333 As mentioned earlier the live ranges are computed in terms of the execution
18334  sequence number of the iCodes, for example
18335 \newline
18336 the iTemp0 is live from (i.e.
18337  first defined in iCode with execution sequence number 3, and is last used
18338  in the iCode with sequence number 5).
18339  For induction variables such as iTemp21 the live range computation extends
18340  the lifetime from the start to the end of the loop.
18341 \newline
18342 The register allocator used the live range information to allocate registers,
18343  the same registers may be used for different temporaries if their live
18344  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
18345  iTemp17 since their live ranges do not overlap.
18346  In addition the allocator also takes into consideration the type and usage
18347  of a temporary, for example itemp6 is a pointer to near space and is used
18348  as to fetch data from (i.e.
18349  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
18350  Some short lived temporaries are allocated to special registers which have
18351  meaning to the code generator e.g.
18352  iTemp13 is allocated to a pseudo register CC which tells the back end that
18353  the temporary is used only for a conditional jump the code generation makes
18354  use of this information to optimize a compare and jump ICode.
18355 \newline
18356 There are several loop optimizations
18357 \begin_inset LatexCommand \index{Loop optimization}
18358
18359 \end_inset
18360
18361  performed by the compiler.
18362  It can detect induction variables iTemp21(i) and iTemp23(j).
18363  Also note the compiler does selective strength reduction
18364 \begin_inset LatexCommand \index{Strength reduction}
18365
18366 \end_inset
18367
18368 , i.e.
18369  the multiplication of an induction variable in line 18 (gint = j * 3) is
18370  changed to addition, a new temporary iTemp17 is allocated and assigned
18371  a initial value, a constant 3 is then added for each iteration of the loop.
18372  The compiler does not change the multiplication
18373 \begin_inset LatexCommand \index{Multiplication}
18374
18375 \end_inset
18376
18377  in line 17 however since the processor does support an 8 * 8 bit multiplication.
18378 \newline
18379 Note the dead code elimination
18380 \begin_inset LatexCommand \index{Dead-code elimination}
18381
18382 \end_inset
18383
18384  optimization eliminated the dead assignments in line 7 & 8 to I and sum
18385  respectively.
18386 \newline
18387
18388 \layout Standard
18389
18390
18391 \size footnotesize
18392 Sample.c (5:1:0:0) _entry($9) :
18393 \layout Standard
18394
18395
18396 \size footnotesize
18397 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
18398 \layout Standard
18399
18400
18401 \size footnotesize
18402 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
18403 \layout Standard
18404
18405
18406 \size footnotesize
18407 Sample.c(11:4:53:0) preHeaderLbl0($11) :
18408 \layout Standard
18409
18410
18411 \size footnotesize
18412 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
18413  * int}[r2]
18414 \layout Standard
18415
18416
18417 \size footnotesize
18418 Sample.c(11:6:5:1) _whilecontinue_0($1) :
18419 \layout Standard
18420
18421
18422 \size footnotesize
18423 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
18424  int}[r0]]
18425 \layout Standard
18426
18427
18428 \size footnotesize
18429 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
18430 \layout Standard
18431
18432
18433 \size footnotesize
18434 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
18435  * int}
18436 \layout Standard
18437
18438
18439 \size footnotesize
18440 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
18441  {short}
18442 \layout Standard
18443
18444
18445 \size footnotesize
18446 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
18447  * int}[DPTR]]
18448 \layout Standard
18449
18450
18451 \size footnotesize
18452 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
18453 }[r2 r3]
18454 \layout Standard
18455
18456
18457 \size footnotesize
18458 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
18459  * int}[r0] + 0x2 {short}
18460 \layout Standard
18461
18462
18463 \size footnotesize
18464 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
18465 \layout Standard
18466
18467
18468 \size footnotesize
18469 Sample.c(11:17:21:0)_whilebreak_0($3) :
18470 \layout Standard
18471
18472
18473 \size footnotesize
18474 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
18475 \layout Standard
18476
18477
18478 \size footnotesize
18479 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
18480 \layout Standard
18481
18482
18483 \size footnotesize
18484 Sample.c(15:20:54:0)preHeaderLbl1($13) :
18485 \layout Standard
18486
18487
18488 \size footnotesize
18489 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
18490 \layout Standard
18491
18492
18493 \size footnotesize
18494 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
18495 \layout Standard
18496
18497
18498 \size footnotesize
18499 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
18500 \layout Standard
18501
18502
18503 \size footnotesize
18504 Sample.c(15:24:26:1)_forcond_0($4) :
18505 \layout Standard
18506
18507
18508 \size footnotesize
18509 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
18510  < 0xa {short}
18511 \layout Standard
18512
18513
18514 \size footnotesize
18515 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
18516 \layout Standard
18517
18518
18519 \size footnotesize
18520 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
18521  + ITemp21 [lr21:38]{short}[r4]
18522 \layout Standard
18523
18524
18525 \size footnotesize
18526 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
18527  * 0x3 {short}
18528 \layout Standard
18529
18530
18531 \size footnotesize
18532 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
18533  + iTemp15 [lr29:30]{short}[r1]
18534 \layout Standard
18535
18536
18537 \size footnotesize
18538 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
18539  r0]- 0x3 {short}
18540 \layout Standard
18541
18542
18543 \size footnotesize
18544 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
18545 int}[r7 r0]
18546 \layout Standard
18547
18548
18549 \size footnotesize
18550 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
18551  + 0x1 {short}
18552 \layout Standard
18553
18554
18555 \size footnotesize
18556 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
18557  r6]- 0x1 {short}
18558 \layout Standard
18559
18560
18561 \size footnotesize
18562 Sample.c(19:38:47:1) goto _forcond_0($4)
18563 \layout Standard
18564
18565
18566 \size footnotesize
18567 Sample.c(19:39:48:0)_forbreak_0($7) :
18568 \layout Standard
18569
18570
18571 \size footnotesize
18572 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
18573  + ITemp11 [lr19:40]{short}[r3]
18574 \layout Standard
18575
18576
18577 \size footnotesize
18578 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
18579 \layout Standard
18580
18581
18582 \size footnotesize
18583 Sample.c(20:42:51:0)_return($8) :
18584 \layout Standard
18585
18586
18587 \size footnotesize
18588 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
18589 \size default
18590
18591 \newline
18592
18593 \newline
18594 Finally the code generated for this function:
18595 \newline
18596
18597 \layout Standard
18598
18599
18600 \size footnotesize
18601 .area DSEG (DATA)
18602 \layout Standard
18603
18604
18605 \size footnotesize
18606 _p::
18607 \layout Standard
18608
18609
18610 \size footnotesize
18611 \SpecialChar ~
18612 \SpecialChar ~
18613 .ds 2
18614 \layout Standard
18615
18616
18617 \size footnotesize
18618 _gint::
18619 \layout Standard
18620
18621
18622 \size footnotesize
18623 \SpecialChar ~
18624 \SpecialChar ~
18625 .ds 2
18626 \layout Standard
18627
18628
18629 \size footnotesize
18630 ; sample.c 5
18631 \layout Standard
18632
18633
18634 \size footnotesize
18635 ; ----------------------------------------------
18636 \layout Standard
18637
18638
18639 \size footnotesize
18640 ; function function
18641 \layout Standard
18642
18643
18644 \size footnotesize
18645 ; ----------------------------------------------
18646 \layout Standard
18647
18648
18649 \size footnotesize
18650 _function:
18651 \layout Standard
18652
18653
18654 \size footnotesize
18655 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
18656 \layout Standard
18657
18658
18659 \size footnotesize
18660 \SpecialChar ~
18661 \SpecialChar ~
18662 mov r2,dpl
18663 \layout Standard
18664
18665
18666 \size footnotesize
18667 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
18668 \layout Standard
18669
18670
18671 \size footnotesize
18672 \SpecialChar ~
18673 \SpecialChar ~
18674 mov ar0,r2
18675 \layout Standard
18676
18677
18678 \size footnotesize
18679 ;_whilecontinue_0($1) :
18680 \layout Standard
18681
18682
18683 \size footnotesize
18684 00101$:
18685 \layout Standard
18686
18687
18688 \size footnotesize
18689 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
18690 \layout Standard
18691
18692
18693 \size footnotesize
18694 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
18695 \layout Standard
18696
18697
18698 \size footnotesize
18699 \SpecialChar ~
18700 \SpecialChar ~
18701 mov ar2,@r0
18702 \layout Standard
18703
18704
18705 \size footnotesize
18706 \SpecialChar ~
18707 \SpecialChar ~
18708 inc r0
18709 \layout Standard
18710
18711
18712 \size footnotesize
18713 \SpecialChar ~
18714 \SpecialChar ~
18715 mov ar3,@r0
18716 \layout Standard
18717
18718
18719 \size footnotesize
18720 \SpecialChar ~
18721 \SpecialChar ~
18722 dec r0
18723 \layout Standard
18724
18725
18726 \size footnotesize
18727 \SpecialChar ~
18728 \SpecialChar ~
18729 mov a,r2
18730 \layout Standard
18731
18732
18733 \size footnotesize
18734 \SpecialChar ~
18735 \SpecialChar ~
18736 orl a,r3
18737 \layout Standard
18738
18739
18740 \size footnotesize
18741 \SpecialChar ~
18742 \SpecialChar ~
18743 jz 00103$
18744 \layout Standard
18745
18746
18747 \size footnotesize
18748 00114$:
18749 \layout Standard
18750
18751
18752 \size footnotesize
18753 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
18754 \layout Standard
18755
18756
18757 \size footnotesize
18758 \SpecialChar ~
18759 \SpecialChar ~
18760 mov dpl,_p
18761 \layout Standard
18762
18763
18764 \size footnotesize
18765 \SpecialChar ~
18766 \SpecialChar ~
18767 mov dph,(_p + 1)
18768 \layout Standard
18769
18770
18771 \size footnotesize
18772 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
18773 \layout Standard
18774
18775
18776 \size footnotesize
18777 \SpecialChar ~
18778 \SpecialChar ~
18779 mov a,#0x02
18780 \layout Standard
18781
18782
18783 \size footnotesize
18784 \SpecialChar ~
18785 \SpecialChar ~
18786 add a,_p
18787 \layout Standard
18788
18789
18790 \size footnotesize
18791 \SpecialChar ~
18792 \SpecialChar ~
18793 mov _p,a
18794 \layout Standard
18795
18796
18797 \size footnotesize
18798 \SpecialChar ~
18799 \SpecialChar ~
18800 clr a
18801 \layout Standard
18802
18803
18804 \size footnotesize
18805 \SpecialChar ~
18806 \SpecialChar ~
18807 addc a,(_p + 1)
18808 \layout Standard
18809
18810
18811 \size footnotesize
18812 \SpecialChar ~
18813 \SpecialChar ~
18814 mov (_p + 1),a
18815 \layout Standard
18816
18817
18818 \size footnotesize
18819 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
18820 \layout Standard
18821
18822
18823 \size footnotesize
18824 \SpecialChar ~
18825 \SpecialChar ~
18826 movx a,@dptr
18827 \layout Standard
18828
18829
18830 \size footnotesize
18831 \SpecialChar ~
18832 \SpecialChar ~
18833 mov r2,a
18834 \layout Standard
18835
18836
18837 \size footnotesize
18838 \SpecialChar ~
18839 \SpecialChar ~
18840 inc dptr
18841 \layout Standard
18842
18843
18844 \size footnotesize
18845 \SpecialChar ~
18846 \SpecialChar ~
18847 movx a,@dptr
18848 \layout Standard
18849
18850
18851 \size footnotesize
18852 \SpecialChar ~
18853 \SpecialChar ~
18854 mov r3,a
18855 \layout Standard
18856
18857
18858 \size footnotesize
18859 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
18860 \layout Standard
18861
18862
18863 \size footnotesize
18864 \SpecialChar ~
18865 \SpecialChar ~
18866 mov @r0,ar2
18867 \layout Standard
18868
18869
18870 \size footnotesize
18871 \SpecialChar ~
18872 \SpecialChar ~
18873 inc r0
18874 \layout Standard
18875
18876
18877 \size footnotesize
18878 \SpecialChar ~
18879 \SpecialChar ~
18880 mov @r0,ar3
18881 \layout Standard
18882
18883
18884 \size footnotesize
18885 ; iTemp6 [lr5:16]{_near * int}[r0] =
18886 \layout Standard
18887
18888
18889 \size footnotesize
18890 ; iTemp6 [lr5:16]{_near * int}[r0] +
18891 \layout Standard
18892
18893
18894 \size footnotesize
18895 ; 0x2 {short}
18896 \layout Standard
18897
18898
18899 \size footnotesize
18900 \SpecialChar ~
18901 \SpecialChar ~
18902 inc r0
18903 \layout Standard
18904
18905
18906 \size footnotesize
18907 ; goto _whilecontinue_0($1)
18908 \layout Standard
18909
18910
18911 \size footnotesize
18912 \SpecialChar ~
18913 \SpecialChar ~
18914 sjmp 00101$
18915 \layout Standard
18916
18917
18918 \size footnotesize
18919 ; _whilebreak_0($3) :
18920 \layout Standard
18921
18922
18923 \size footnotesize
18924 00103$:
18925 \layout Standard
18926
18927
18928 \size footnotesize
18929 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
18930 \layout Standard
18931
18932
18933 \size footnotesize
18934 \SpecialChar ~
18935 \SpecialChar ~
18936 mov r2,#0x00
18937 \layout Standard
18938
18939
18940 \size footnotesize
18941 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
18942 \layout Standard
18943
18944
18945 \size footnotesize
18946 \SpecialChar ~
18947 \SpecialChar ~
18948 mov r3,#0x00
18949 \layout Standard
18950
18951
18952 \size footnotesize
18953 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
18954 \layout Standard
18955
18956
18957 \size footnotesize
18958 \SpecialChar ~
18959 \SpecialChar ~
18960 mov r4,#0x00
18961 \layout Standard
18962
18963
18964 \size footnotesize
18965 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
18966 \layout Standard
18967
18968
18969 \size footnotesize
18970 \SpecialChar ~
18971 \SpecialChar ~
18972 mov r5,#0x0A
18973 \layout Standard
18974
18975
18976 \size footnotesize
18977 \SpecialChar ~
18978 \SpecialChar ~
18979 mov r6,#0x00
18980 \layout Standard
18981
18982
18983 \size footnotesize
18984 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
18985 \layout Standard
18986
18987
18988 \size footnotesize
18989 \SpecialChar ~
18990 \SpecialChar ~
18991 mov r7,#0x1E
18992 \layout Standard
18993
18994
18995 \size footnotesize
18996 \SpecialChar ~
18997 \SpecialChar ~
18998 mov r0,#0x00
18999 \layout Standard
19000
19001
19002 \size footnotesize
19003 ; _forcond_0($4) :
19004 \layout Standard
19005
19006
19007 \size footnotesize
19008 00104$:
19009 \layout Standard
19010
19011
19012 \size footnotesize
19013 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
19014 \layout Standard
19015
19016
19017 \size footnotesize
19018 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
19019 \layout Standard
19020
19021
19022 \size footnotesize
19023 \SpecialChar ~
19024 \SpecialChar ~
19025 clr c
19026 \layout Standard
19027
19028
19029 \size footnotesize
19030 \SpecialChar ~
19031 \SpecialChar ~
19032 mov a,r4
19033 \layout Standard
19034
19035
19036 \size footnotesize
19037 \SpecialChar ~
19038 \SpecialChar ~
19039 xrl a,#0x80
19040 \layout Standard
19041
19042
19043 \size footnotesize
19044 \SpecialChar ~
19045 \SpecialChar ~
19046 subb a,#0x8a
19047 \layout Standard
19048
19049
19050 \size footnotesize
19051 \SpecialChar ~
19052 \SpecialChar ~
19053 jnc 00107$
19054 \layout Standard
19055
19056
19057 \size footnotesize
19058 00115$:
19059 \layout Standard
19060
19061
19062 \size footnotesize
19063 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
19064 \layout Standard
19065
19066
19067 \size footnotesize
19068 ; iTemp21 [lr21:38]{short}[r4]
19069 \layout Standard
19070
19071
19072 \size footnotesize
19073 \SpecialChar ~
19074 \SpecialChar ~
19075 mov a,r4
19076 \layout Standard
19077
19078
19079 \size footnotesize
19080 \SpecialChar ~
19081 \SpecialChar ~
19082 add a,r2
19083 \layout Standard
19084
19085
19086 \size footnotesize
19087 \SpecialChar ~
19088 \SpecialChar ~
19089 mov r2,a
19090 \layout Standard
19091
19092
19093 \size footnotesize
19094 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
19095 \layout Standard
19096
19097
19098 \size footnotesize
19099 \SpecialChar ~
19100 \SpecialChar ~
19101 mov b,#0x03
19102 \layout Standard
19103
19104
19105 \size footnotesize
19106 \SpecialChar ~
19107 \SpecialChar ~
19108 mov a,r4
19109 \layout Standard
19110
19111
19112 \size footnotesize
19113 \SpecialChar ~
19114 \SpecialChar ~
19115 mul ab
19116 \layout Standard
19117
19118
19119 \size footnotesize
19120 \SpecialChar ~
19121 \SpecialChar ~
19122 mov r1,a
19123 \layout Standard
19124
19125
19126 \size footnotesize
19127 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
19128 \layout Standard
19129
19130
19131 \size footnotesize
19132 ; iTemp15 [lr29:30]{short}[r1]
19133 \layout Standard
19134
19135
19136 \size footnotesize
19137 \SpecialChar ~
19138 \SpecialChar ~
19139 add a,r3
19140 \layout Standard
19141
19142
19143 \size footnotesize
19144 \SpecialChar ~
19145 \SpecialChar ~
19146 mov r3,a
19147 \layout Standard
19148
19149
19150 \size footnotesize
19151 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
19152 \layout Standard
19153
19154
19155 \size footnotesize
19156 \SpecialChar ~
19157 \SpecialChar ~
19158 mov a,r7
19159 \layout Standard
19160
19161
19162 \size footnotesize
19163 \SpecialChar ~
19164 \SpecialChar ~
19165 add a,#0xfd
19166 \layout Standard
19167
19168
19169 \size footnotesize
19170 \SpecialChar ~
19171 \SpecialChar ~
19172 mov r7,a
19173 \layout Standard
19174
19175
19176 \size footnotesize
19177 \SpecialChar ~
19178 \SpecialChar ~
19179 mov a,r0
19180 \layout Standard
19181
19182
19183 \size footnotesize
19184 \SpecialChar ~
19185 \SpecialChar ~
19186 addc a,#0xff
19187 \layout Standard
19188
19189
19190 \size footnotesize
19191 \SpecialChar ~
19192 \SpecialChar ~
19193 mov r0,a
19194 \layout Standard
19195
19196
19197 \size footnotesize
19198 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
19199 \layout Standard
19200
19201
19202 \size footnotesize
19203 \SpecialChar ~
19204 \SpecialChar ~
19205 mov a,r7
19206 \layout Standard
19207
19208
19209 \size footnotesize
19210 \SpecialChar ~
19211 \SpecialChar ~
19212 add a,_gint
19213 \layout Standard
19214
19215
19216 \size footnotesize
19217 \SpecialChar ~
19218 \SpecialChar ~
19219 mov _gint,a
19220 \layout Standard
19221
19222
19223 \size footnotesize
19224 \SpecialChar ~
19225 \SpecialChar ~
19226 mov a,r0
19227 \layout Standard
19228
19229
19230 \size footnotesize
19231 \SpecialChar ~
19232 \SpecialChar ~
19233 addc a,(_gint + 1)
19234 \layout Standard
19235
19236
19237 \size footnotesize
19238 \SpecialChar ~
19239 \SpecialChar ~
19240 mov (_gint + 1),a
19241 \layout Standard
19242
19243
19244 \size footnotesize
19245 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
19246 \layout Standard
19247
19248
19249 \size footnotesize
19250 \SpecialChar ~
19251 \SpecialChar ~
19252 inc r4
19253 \layout Standard
19254
19255
19256 \size footnotesize
19257 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
19258 \layout Standard
19259
19260
19261 \size footnotesize
19262 \SpecialChar ~
19263 \SpecialChar ~
19264 dec r5
19265 \layout Standard
19266
19267
19268 \size footnotesize
19269 \SpecialChar ~
19270 \SpecialChar ~
19271 cjne r5,#0xff,00104$
19272 \layout Standard
19273
19274
19275 \size footnotesize
19276 \SpecialChar ~
19277 \SpecialChar ~
19278 dec r6
19279 \layout Standard
19280
19281
19282 \size footnotesize
19283 ; goto _forcond_0($4)
19284 \layout Standard
19285
19286
19287 \size footnotesize
19288 \SpecialChar ~
19289 \SpecialChar ~
19290 sjmp 00104$
19291 \layout Standard
19292
19293
19294 \size footnotesize
19295 ; _forbreak_0($7) :
19296 \layout Standard
19297
19298
19299 \size footnotesize
19300 00107$:
19301 \layout Standard
19302
19303
19304 \size footnotesize
19305 ; ret iTemp24 [lr40:41]{short}
19306 \layout Standard
19307
19308
19309 \size footnotesize
19310 \SpecialChar ~
19311 \SpecialChar ~
19312 mov a,r3
19313 \layout Standard
19314
19315
19316 \size footnotesize
19317 \SpecialChar ~
19318 \SpecialChar ~
19319 add a,r2
19320 \layout Standard
19321
19322
19323 \size footnotesize
19324 \SpecialChar ~
19325 \SpecialChar ~
19326 mov dpl,a
19327 \layout Standard
19328
19329
19330 \size footnotesize
19331 ; _return($8) :
19332 \layout Standard
19333
19334
19335 \size footnotesize
19336 00108$:
19337 \layout Standard
19338
19339
19340 \size footnotesize
19341 \SpecialChar ~
19342 \SpecialChar ~
19343 ret
19344 \newline
19345
19346 \layout Section
19347
19348 A few words about basic block successors, predecessors and dominators
19349 \layout Standard
19350
19351 Successors are basic blocks
19352 \begin_inset LatexCommand \index{Basic blocks}
19353
19354 \end_inset
19355
19356  that might execute after this basic block.
19357 \newline
19358 Predecessors are basic blocks that might execute before reaching this basic
19359  block.
19360 \newline
19361 Dominators are basic blocks that WILL execute before reaching this basic
19362  block.
19363 \newline
19364
19365 \layout Standard
19366
19367 [basic block 1]
19368 \layout Standard
19369
19370 if (something)
19371 \layout Standard
19372
19373 \SpecialChar ~
19374 \SpecialChar ~
19375 \SpecialChar ~
19376 \SpecialChar ~
19377 [basic block 2]
19378 \layout Standard
19379
19380 else
19381 \layout Standard
19382
19383 \SpecialChar ~
19384 \SpecialChar ~
19385 \SpecialChar ~
19386 \SpecialChar ~
19387 [basic block 3]
19388 \layout Standard
19389
19390 [basic block 4]
19391 \newline
19392
19393 \layout Standard
19394
19395 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
19396 \layout Standard
19397
19398 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
19399 \layout Standard
19400
19401 c) domVect of [BB4] = BB1 ...
19402  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
19403  was executed.
19404 \layout Chapter
19405
19406 Acknowledgments
19407 \layout Standard
19408
19409
19410 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
19411
19412 \end_inset
19413
19414
19415 \newline
19416
19417 \newline
19418
19419 \emph on
19420 Thanks to all the other volunteer developers who have helped with coding,
19421  testing, web-page creation, distribution sets, etc.
19422  You know who you are :-)
19423 \emph default
19424
19425 \newline
19426
19427 \layout Standard
19428
19429 This document was initially written by Sandeep Dutta
19430 \layout Standard
19431
19432 All product names mentioned herein may be trademarks
19433 \begin_inset LatexCommand \index{Trademarks}
19434
19435 \end_inset
19436
19437  of their respective companies.
19438
19439 \layout Section*
19440
19441 Alphabetical index
19442 \layout Standard
19443
19444 To avoid confusion, the installation and building options for SDCC itself
19445  (chapter 2) are not part of the index.
19446 \layout Standard
19447
19448
19449 \begin_inset LatexCommand \printindex{}
19450
19451 \end_inset
19452
19453
19454 \the_end