git.gag.com Git - fw/sdcc/blob - doc/sdccman.lyx

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