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 optional 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  When present, the compiler will insert a call to this routine in the
7408  interrupt vector 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 \SpecialChar ~
11299  a,(_gint + 1)
11300 \newline
11301 000C 23\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 \SpecialChar ~
11319  63\SpecialChar ~
11320 \SpecialChar ~
11321 \SpecialChar ~
11322 \SpecialChar ~
11323 \SpecialChar ~
11324 \SpecialChar ~
11325 \SpecialChar ~
11326 \SpecialChar ~
11327  rl\SpecialChar ~
11328 \SpecialChar ~
11329 \SpecialChar ~
11330  a
11331 \newline
11332 000D 54 01\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  andl\SpecialChar ~
11356  a,#0x01
11357 \newline
11358 000F F5*02\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  65\SpecialChar ~
11374 \SpecialChar ~
11375 \SpecialChar ~
11376 \SpecialChar ~
11377 \SpecialChar ~
11378 \SpecialChar ~
11379 \SpecialChar ~
11380 \SpecialChar ~
11381  mov\SpecialChar ~
11382 \SpecialChar ~
11383  _foo_hob_1_1,a
11384 \layout Standard
11385
11386 Variations of this case however will
11387 \emph on
11388 not
11389 \emph default
11390  be recognized.
11391  It is a standard C expression, so I heartily recommend this be the only
11392  way to get the highest order bit, (it is portable).
11393  Of course it will be recognized even if it is embedded in other expressions,
11394  e.g.:
11395 \layout Verse
11396
11397
11398 \family typewriter
11399 xyz = gint + ((gint >> 15) & 1);
11400 \layout Standard
11401
11402 will still be recognized.
11403 \layout Subsubsection
11404
11405 Peephole Optimizer
11406 \begin_inset LatexCommand \index{Peephole optimizer}
11407
11408 \end_inset
11409
11410
11411 \layout Standard
11412
11413 The compiler uses a rule based, pattern matching and re-writing mechanism
11414  for peep-hole optimization.
11415  It is inspired by
11416 \emph on
11417 copt
11418 \emph default
11419  a peep-hole optimizer by Christopher W.
11420  Fraser (cwfraser@microsoft.com).
11421  A default set of rules are compiled into the compiler, additional rules
11422  may be added with the
11423 \emph on
11424 -
11425 \begin_inset ERT
11426 status Collapsed
11427
11428 \layout Standard
11429
11430 \backslash
11431 /
11432 \end_inset
11433
11434 -peep-file
11435 \begin_inset LatexCommand \index{-\/-peep-file}
11436
11437 \end_inset
11438
11439  <filename>
11440 \emph default
11441  option.
11442  The rule language is best illustrated with examples.
11443 \layout Verse
11444
11445
11446 \family typewriter
11447 replace {
11448 \newline
11449 \SpecialChar ~
11450 \SpecialChar ~
11451 mov %1,a
11452 \newline
11453 \SpecialChar ~
11454 \SpecialChar ~
11455 mov a,%1
11456 \newline
11457 } by {
11458 \newline
11459 \SpecialChar ~
11460 \SpecialChar ~
11461 mov %1,a
11462 \newline
11463 }
11464 \layout Standard
11465
11466 The above rule will change the following assembly
11467 \begin_inset LatexCommand \index{Assembler routines}
11468
11469 \end_inset
11470
11471  sequence:
11472 \layout Verse
11473
11474
11475 \family typewriter
11476 mov r1,a
11477 \newline
11478 mov a,r1
11479 \layout Standard
11480
11481 to
11482 \layout Verse
11483
11484
11485 \family typewriter
11486 mov r1,a
11487 \layout Standard
11488
11489 Note: All occurrences of a
11490 \emph on
11491 %n
11492 \emph default
11493  (pattern variable) must denote the same string.
11494  With the above rule, the assembly sequence:
11495 \layout Verse
11496
11497
11498 \family typewriter
11499 mov r1,a
11500 \newline
11501 mov a,r2
11502 \layout Standard
11503
11504 will remain unmodified.
11505 \newline
11506
11507 \newline
11508 Other special case optimizations may be added by the user (via
11509 \emph on
11510 -
11511 \begin_inset ERT
11512 status Collapsed
11513
11514 \layout Standard
11515
11516 \backslash
11517 /
11518 \end_inset
11519
11520 -peep-file option
11521 \emph default
11522 ).
11523  E.g.
11524  some variants of the 8051 MCU allow only
11525 \family typewriter
11526 ajmp
11527 \family default
11528  and
11529 \family typewriter
11530 acall
11531 \family default
11532 .
11533  The following two rules will change all
11534 \family typewriter
11535 ljmp
11536 \family default
11537  and
11538 \family typewriter
11539 lcall
11540 \family default
11541  to
11542 \family typewriter
11543 ajmp
11544 \family default
11545  and
11546 \family typewriter
11547 acall
11548 \layout Verse
11549
11550
11551 \family typewriter
11552 replace { lcall %1 } by { acall %1 }
11553 \newline
11554 replace { ljmp %1 } by { ajmp %1 }
11555 \layout Standard
11556
11557 The
11558 \emph on
11559 inline-assembler code
11560 \emph default
11561  is also passed through the peep hole optimizer, thus the peephole optimizer
11562  can also be used as an assembly level macro expander.
11563  The rules themselves are MCU dependent whereas the rule language infra-structur
11564 e is MCU independent.
11565  Peephole optimization rules for other MCU can be easily programmed using
11566  the rule language.
11567 \newline
11568
11569 \newline
11570 The syntax for a rule is as follows:
11571 \layout Verse
11572
11573
11574 \family typewriter
11575 rule := replace [ restart ] '{' <assembly sequence> '
11576 \backslash
11577 n'
11578 \newline
11579 \SpecialChar ~
11580  \SpecialChar ~
11581  \SpecialChar ~
11582  \SpecialChar ~
11583  \SpecialChar ~
11584  \SpecialChar ~
11585  \SpecialChar ~
11586  \SpecialChar ~
11587  \SpecialChar ~
11588  \SpecialChar ~
11589  \SpecialChar ~
11590  \SpecialChar ~
11591  \SpecialChar ~
11592  \SpecialChar ~
11593  '}' by '{' '
11594 \backslash
11595 n'
11596 \newline
11597 \SpecialChar ~
11598  \SpecialChar ~
11599  \SpecialChar ~
11600  \SpecialChar ~
11601  \SpecialChar ~
11602  \SpecialChar ~
11603  \SpecialChar ~
11604  \SpecialChar ~
11605  \SpecialChar ~
11606  \SpecialChar ~
11607  \SpecialChar ~
11608  \SpecialChar ~
11609  \SpecialChar ~
11610  \SpecialChar ~
11611  \SpecialChar ~
11612  \SpecialChar ~
11613  <assembly sequence> '
11614 \backslash
11615 n'
11616 \newline
11617 \SpecialChar ~
11618  \SpecialChar ~
11619  \SpecialChar ~
11620  \SpecialChar ~
11621  \SpecialChar ~
11622  \SpecialChar ~
11623  \SpecialChar ~
11624  \SpecialChar ~
11625  \SpecialChar ~
11626  \SpecialChar ~
11627  \SpecialChar ~
11628  \SpecialChar ~
11629  \SpecialChar ~
11630  \SpecialChar ~
11631  '}' [if <functionName> ] '
11632 \backslash
11633 n'
11634 \layout Standard
11635
11636 <assembly sequence> := assembly instruction (each instruction including
11637  labels must be on a separate line).
11638 \newline
11639
11640 \newline
11641 The optimizer will apply to the rules one by one from the top in the sequence
11642  of their appearance, it will terminate when all rules are exhausted.
11643  If the 'restart' option is specified, then the optimizer will start matching
11644  the rules again from the top, this option for a rule is expensive (performance)
11645 , it is intended to be used in situations where a transformation will trigger
11646  the same rule again.
11647  An example of this (not a good one, it has side effects) is the following
11648  rule:
11649 \layout Verse
11650
11651
11652 \family typewriter
11653 replace restart {
11654 \newline
11655 \SpecialChar ~
11656 \SpecialChar ~
11657 pop %1
11658 \newline
11659 \SpecialChar ~
11660 \SpecialChar ~
11661 push %1 } by {
11662 \newline
11663 \SpecialChar ~
11664 \SpecialChar ~
11665 ; nop
11666 \newline
11667 }
11668 \layout Standard
11669
11670 Note that the replace pattern cannot be a blank, but can be a comment line.
11671  Without the 'restart' option only the inner most 'pop' 'push' pair would
11672  be eliminated, i.e.:
11673 \layout Verse
11674
11675
11676 \family typewriter
11677 pop ar1
11678 \newline
11679 pop ar2
11680 \newline
11681 push ar2
11682 \newline
11683 push ar1
11684 \layout Standard
11685
11686 would result in:
11687 \layout Verse
11688
11689
11690 \family typewriter
11691 pop ar1
11692 \newline
11693 ; nop
11694 \newline
11695 push ar1
11696 \layout Standard
11697
11698
11699 \emph on
11700 with
11701 \emph default
11702  the restart option the rule will be applied again to the resulting code
11703  and then all the pop-push pairs will be eliminated to yield:
11704 \layout Verse
11705
11706
11707 \family typewriter
11708 ; nop
11709 \newline
11710 ; nop
11711 \layout Standard
11712
11713 A conditional function can be attached to a rule.
11714  Attaching rules are somewhat more involved, let me illustrate this with
11715  an example.
11716 \layout Verse
11717
11718
11719 \family typewriter
11720 replace {
11721 \newline
11722 \SpecialChar ~
11723  \SpecialChar ~
11724  \SpecialChar ~
11725 ljmp %5
11726 \newline
11727 %2:
11728 \newline
11729 } by {
11730 \newline
11731 \SpecialChar ~
11732  \SpecialChar ~
11733  \SpecialChar ~
11734 sjmp %5
11735 \newline
11736 %2:
11737 \newline
11738 } if labelInRange
11739 \layout Standard
11740
11741 The optimizer does a look-up of a function name table defined in function
11742
11743 \emph on
11744 callFuncByName
11745 \emph default
11746  in the source file SDCCpeeph.c, with the name
11747 \emph on
11748 labelInRange
11749 \emph default
11750 .
11751  If it finds a corresponding entry the function is called.
11752  Note there can be no parameters specified for these functions, in this
11753  case the use of
11754 \emph on
11755 %5
11756 \emph default
11757  is crucial, since the function
11758 \emph on
11759 labelInRange
11760 \emph default
11761  expects to find the label in that particular variable (the hash table containin
11762 g the variable bindings is passed as a parameter).
11763  If you want to code more such functions, take a close look at the function
11764  labelInRange and the calling mechanism in source file SDCCpeeph.c.
11765  I know this whole thing is a little kludgey, but maybe some day we will
11766  have some better means.
11767  If you are looking at this file, you will also see the default rules that
11768  are compiled into the compiler, you can add your own rules in the default
11769  set there if you get tired of specifying the -
11770 \begin_inset ERT
11771 status Collapsed
11772
11773 \layout Standard
11774
11775 \backslash
11776 /
11777 \end_inset
11778
11779 -peep-file option.
11780 \layout Subsection
11781
11782 Pragmas
11783 \begin_inset LatexCommand \index{Pragmas}
11784
11785 \end_inset
11786
11787
11788 \layout Standard
11789
11790 SDCC supports the following #pragma directives.
11791 \layout Itemize
11792
11793 SAVE
11794 \begin_inset LatexCommand \index{\#pragma SAVE}
11795
11796 \end_inset
11797
11798  - this will save all current options to the SAVE/RESTORE stack.
11799  See RESTORE.
11800 \layout Itemize
11801
11802 RESTORE
11803 \begin_inset LatexCommand \index{\#pragma RESTORE}
11804
11805 \end_inset
11806
11807  - will restore saved options from the last save.
11808  SAVEs & RESTOREs can be nested.
11809  SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
11810  RESTORE pulls current options from the stack.
11811  See SAVE.
11812 \layout Itemize
11813
11814 NOGCSE
11815 \begin_inset LatexCommand \index{\#pragma NOGCSE}
11816
11817 \end_inset
11818
11819  - will stop global subexpression elimination.
11820 \layout Itemize
11821
11822 NOINDUCTION
11823 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
11824
11825 \end_inset
11826
11827  - will stop loop induction optimizations.
11828 \layout Itemize
11829
11830 NOJTBOUND
11831 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
11832
11833 \end_inset
11834
11835  - will not generate code for boundary value checking, when switch statements
11836  are turned into jump-tables.
11837 \layout Itemize
11838
11839 NOOVERLAY
11840 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
11841
11842 \end_inset
11843
11844  - the compiler will not overlay the parameters and local variables of a
11845  function.
11846 \layout Itemize
11847
11848 LESS_PEDANTIC
11849 \begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
11850
11851 \end_inset
11852
11853  - the compiler will not warn you anymore for obvious mistakes, you'r on
11854  your own now ;-(
11855 \layout Itemize
11856
11857 NOLOOPREVERSE
11858 \begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
11859
11860 \end_inset
11861
11862  - Will not do loop reversal optimization
11863 \layout Itemize
11864
11865 EXCLUDE
11866 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
11867
11868 \end_inset
11869
11870  NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
11871  pair of push/pop
11872 \begin_inset LatexCommand \index{push/pop}
11873
11874 \end_inset
11875
11876  instruction in ISR function (using interrupt
11877 \begin_inset LatexCommand \index{interrupt}
11878
11879 \end_inset
11880
11881  keyword).
11882  The directive should be placed immediately before the ISR function definition
11883  and it affects ALL ISR functions following it.
11884  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
11885 EXCLUDE\SpecialChar ~
11886 none
11887 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
11888
11889 \end_inset
11890
11891 .
11892 \layout Itemize
11893
11894 NOIV
11895 \begin_inset LatexCommand \index{\#pragma NOIV}
11896
11897 \end_inset
11898
11899  - Do not generate interrupt vector table entries for all ISR functions
11900  defined after the pragma.
11901  This is useful in cases where the interrupt vector table must be defined
11902  manually, or when there is a secondary, manually defined interrupt vector
11903  table (e.g.
11904  for the autovector feature of the Cypress EZ-USB FX2).
11905 \layout Itemize
11906
11907 CALLEE-SAVES
11908 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
11909
11910 \end_inset
11911
11912
11913 \begin_inset LatexCommand \index{function prologue}
11914
11915 \end_inset
11916
11917  function1[,function2[,function3...]] - The compiler by default uses a caller
11918  saves convention for register saving across function calls, however this
11919  can cause unnecessary register pushing & popping when calling small functions
11920  from larger functions.
11921  This option can be used to switch off the register saving convention for
11922  the function names specified.
11923  The compiler will not save registers when calling these functions, extra
11924  code need to be manually inserted at the entry & exit for these functions
11925  to save & restore the registers used by these functions, this can SUBSTANTIALLY
11926  reduce code & improve run time performance of the generated code.
11927  In the future the compiler (with inter procedural analysis) may be able
11928  to determine the appropriate scheme to use for each function call.
11929  If -
11930 \begin_inset ERT
11931 status Collapsed
11932
11933 \layout Standard
11934
11935 \backslash
11936 /
11937 \end_inset
11938
11939 -callee-saves command line option is used, the function names specified
11940  in #pragma\SpecialChar ~
11941 CALLEE-SAVES
11942 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
11943
11944 \end_inset
11945
11946  is appended to the list of functions specified in the command line.
11947 \layout Standard
11948
11949 The pragma's are intended to be used to turn-off certain optimizations which
11950  might cause the compiler to generate extra stack / data space to store
11951  compiler generated temporary variables.
11952  This usually happens in large functions.
11953  Pragma directives should be used as shown in the following example, they
11954  are used to control options & optimizations for a given function; pragmas
11955  should be placed before and/or after a function, placing pragma's inside
11956  a function body could have unpredictable results.
11957 \layout Verse
11958
11959
11960 \family typewriter
11961 #pragma SAVE
11962 \begin_inset LatexCommand \index{\#pragma SAVE}
11963
11964 \end_inset
11965
11966  /* save the current settings */
11967 \newline
11968 #pragma NOGCSE
11969 \begin_inset LatexCommand \index{\#pragma NOGCSE}
11970
11971 \end_inset
11972
11973  /* turnoff global subexpression elimination */
11974 \newline
11975 #pragma NOINDUCTION
11976 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
11977
11978 \end_inset
11979
11980  /* turn off induction optimizations */
11981 \newline
11982 int foo ()
11983 \newline
11984 {
11985 \newline
11986 \SpecialChar ~
11987  \SpecialChar ~
11988  ...
11989
11990 \newline
11991 \SpecialChar ~
11992  \SpecialChar ~
11993  /* large code */
11994 \newline
11995 \SpecialChar ~
11996  \SpecialChar ~
11997  ...
11998
11999 \newline
12000 }
12001 \newline
12002 #pragma RESTORE
12003 \begin_inset LatexCommand \index{\#pragma RESTORE}
12004
12005 \end_inset
12006
12007  /* turn the optimizations back on */
12008 \layout Standard
12009
12010 The compiler will generate a warning message when extra space is allocated.
12011  It is strongly recommended that the SAVE and RESTORE pragma's be used when
12012  changing options for a function.
12013 \layout Subsection
12014
12015 Library Routines
12016 \emph on
12017  <pending: this is messy and incomplete>
12018 \emph default
12019
12020 \layout Enumerate
12021
12022 Compiler support routines (_gptrget, _mulint etc)
12023 \layout Enumerate
12024
12025 Stdclib functions (puts, printf, strcat etc)
12026 \layout Enumerate
12027
12028 Math functions (sin, pow, sqrt etc)
12029 \layout Comment
12030
12031 license statements for the libraries are missing
12032 \layout Subsection
12033
12034 Interfacing with Assembly Routines
12035 \begin_inset LatexCommand \index{Assembler routines}
12036
12037 \end_inset
12038
12039
12040 \layout Subsubsection
12041
12042 Global Registers used for Parameter Passing
12043 \begin_inset LatexCommand \index{Parameter passing}
12044
12045 \end_inset
12046
12047
12048 \layout Standard
12049
12050 The compiler always uses the global registers
12051 \emph on
12052 DPL, DPH
12053 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12054
12055 \end_inset
12056
12057 , B
12058 \begin_inset LatexCommand \index{B (register)}
12059
12060 \end_inset
12061
12062
12063 \emph default
12064 and
12065 \emph on
12066  ACC
12067 \begin_inset LatexCommand \index{ACC}
12068
12069 \end_inset
12070
12071
12072 \emph default
12073  to pass the first parameter to a routine.
12074  The second parameter onwards is either allocated on the stack (for reentrant
12075  routines or if -
12076 \begin_inset ERT
12077 status Collapsed
12078
12079 \layout Standard
12080
12081 \backslash
12082 /
12083 \end_inset
12084
12085 -stack-auto is used) or in the internal / external ram (depending on the
12086  memory model).
12087
12088 \layout Subsubsection
12089
12090 Assembler Routine(non-reentrant
12091 \begin_inset LatexCommand \index{reentrant}
12092
12093 \end_inset
12094
12095 )
12096 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
12097
12098 \end_inset
12099
12100
12101 \layout Standard
12102
12103 In the following example the function c_func calls an assembler routine
12104  asm_func, which takes two parameters.
12105 \layout Verse
12106
12107
12108 \family typewriter
12109 extern int asm_func(unsigned char, unsigned char);
12110 \newline
12111
12112 \newline
12113 int c_func (unsigned char i, unsigned char j)
12114 \newline
12115 {
12116 \newline
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 \SpecialChar ~
12120 \SpecialChar ~
12121 return asm_func(i,j);
12122 \newline
12123 }
12124 \newline
12125
12126 \newline
12127 int main()
12128 \newline
12129 {
12130 \newline
12131 \SpecialChar ~
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 return c_func(10,9);
12136 \newline
12137 }
12138 \layout Standard
12139
12140 The corresponding assembler function is:
12141 \layout Verse
12142
12143
12144 \family typewriter
12145 .globl _asm_func_PARM_2
12146 \newline
12147 \SpecialChar ~
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 \SpecialChar ~
12151 \SpecialChar ~
12152 \SpecialChar ~
12153 \SpecialChar ~
12154 \SpecialChar ~
12155 .globl _asm_func
12156 \newline
12157 \SpecialChar ~
12158 \SpecialChar ~
12159 \SpecialChar ~
12160 \SpecialChar ~
12161 \SpecialChar ~
12162 \SpecialChar ~
12163 \SpecialChar ~
12164 \SpecialChar ~
12165 .area OSEG
12166 \newline
12167 _asm_func_PARM_2:
12168 \newline
12169 \SpecialChar ~
12170 \SpecialChar ~
12171 \SpecialChar ~
12172 \SpecialChar ~
12173 \SpecialChar ~
12174 \SpecialChar ~
12175 \SpecialChar ~
12176 \SpecialChar ~
12177 .ds     1
12178 \newline
12179 \SpecialChar ~
12180 \SpecialChar ~
12181 \SpecialChar ~
12182 \SpecialChar ~
12183 \SpecialChar ~
12184 \SpecialChar ~
12185 \SpecialChar ~
12186 \SpecialChar ~
12187 .area CSEG
12188 \newline
12189 _asm_func:
12190 \newline
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 \SpecialChar ~
12195 \SpecialChar ~
12196 \SpecialChar ~
12197 \SpecialChar ~
12198 \SpecialChar ~
12199 mov    a,dpl
12200 \newline
12201 \SpecialChar ~
12202 \SpecialChar ~
12203 \SpecialChar ~
12204 \SpecialChar ~
12205 \SpecialChar ~
12206 \SpecialChar ~
12207 \SpecialChar ~
12208 \SpecialChar ~
12209 add    a,_asm_func_PARM_2
12210 \newline
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 \SpecialChar ~
12214 \SpecialChar ~
12215 \SpecialChar ~
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 mov    dpl,a
12220 \newline
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 \SpecialChar ~
12224 \SpecialChar ~
12225 \SpecialChar ~
12226 \SpecialChar ~
12227 \SpecialChar ~
12228 \SpecialChar ~
12229 mov\SpecialChar ~
12230 \SpecialChar ~
12231 \SpecialChar ~
12232 \SpecialChar ~
12233 dpl
12234 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12235
12236 \end_inset
12237
12238 ,#0x00
12239 \newline
12240 \SpecialChar ~
12241 \SpecialChar ~
12242 \SpecialChar ~
12243 \SpecialChar ~
12244 \SpecialChar ~
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 ret
12249 \layout Standard
12250
12251 Note here that the return values are placed in 'dpl' - One byte return value,
12252  'dpl' LSB & 'dph' MSB for two byte values.
12253  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12254 b' & 'acc' for four byte values.
12255 \layout Standard
12256
12257 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12258  the parameter number starting from 1, and counting from the left.
12259  The first parameter is passed in
12260 \begin_inset Quotes eld
12261 \end_inset
12262
12263 dpl
12264 \begin_inset Quotes erd
12265 \end_inset
12266
12267  for One bye parameter,
12268 \begin_inset Quotes eld
12269 \end_inset
12270
12271 dptr
12272 \begin_inset Quotes erd
12273 \end_inset
12274
12275  if two bytes,
12276 \begin_inset Quotes eld
12277 \end_inset
12278
12279 b,dptr
12280 \begin_inset Quotes erd
12281 \end_inset
12282
12283  for three bytes and
12284 \begin_inset Quotes eld
12285 \end_inset
12286
12287 acc,b,dptr
12288 \begin_inset Quotes erd
12289 \end_inset
12290
12291  for four bytes, the variable name for the second parameter will be _<function_n
12292 ame>_PARM_2.
12293 \newline
12294
12295 \newline
12296 Assemble the assembler routine with the following command:
12297 \newline
12298
12299 \newline
12300
12301 \family sans
12302 \series bold
12303 asx8051 -losg asmfunc.asm
12304 \newline
12305
12306 \newline
12307
12308 \family default
12309 \series default
12310 Then compile and link the assembler routine to the C source file with the
12311  following command:
12312 \newline
12313
12314 \newline
12315
12316 \family sans
12317 \series bold
12318 sdcc cfunc.c asmfunc.rel
12319 \layout Subsubsection
12320
12321 Assembler Routine(reentrant
12322 \begin_inset LatexCommand \index{reentrant}
12323
12324 \end_inset
12325
12326 )
12327 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12328
12329 \end_inset
12330
12331
12332 \layout Standard
12333
12334 In this case the second parameter onwards will be passed on the stack, the
12335  parameters are pushed from right to left i.e.
12336  after the call the left most parameter will be on the top of the stack.
12337  Here is an example:
12338 \layout Verse
12339
12340
12341 \family typewriter
12342 extern int asm_func(unsigned char, unsigned char);
12343 \newline
12344
12345 \newline
12346 int c_func (unsigned char i, unsigned char j) reentrant
12347 \newline
12348 {
12349 \newline
12350 \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 \SpecialChar ~
12354 return asm_func(i,j);
12355 \newline
12356 }
12357 \newline
12358
12359 \newline
12360 int main()
12361 \newline
12362 {
12363 \newline
12364 \SpecialChar ~
12365 \SpecialChar ~
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 return c_func(10,9);
12369 \newline
12370 }
12371 \layout Standard
12372
12373 The corresponding assembler routine is:
12374 \layout Verse
12375
12376
12377 \family typewriter
12378 .globl _asm_func
12379 \newline
12380 _asm_func:
12381 \newline
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 \SpecialChar ~
12386 push  _bp
12387 \newline
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 mov _bp,sp
12393 \newline
12394 \SpecialChar ~
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 mov  r2,dpl
12399 \newline
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 \SpecialChar ~
12404 mov  a,_bp
12405 \newline
12406 \SpecialChar ~
12407 \SpecialChar ~
12408 \SpecialChar ~
12409 \SpecialChar ~
12410 clr  c
12411 \newline
12412 \SpecialChar ~
12413 \SpecialChar ~
12414 \SpecialChar ~
12415 \SpecialChar ~
12416 add  a,#0xfd
12417 \newline
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 \SpecialChar ~
12422 mov  r0,a
12423 \newline
12424 \SpecialChar ~
12425 \SpecialChar ~
12426 \SpecialChar ~
12427 \SpecialChar ~
12428 add  a,#0xfc
12429 \newline
12430 \SpecialChar ~
12431 \SpecialChar ~
12432 \SpecialChar ~
12433 \SpecialChar ~
12434 mov  r1,a
12435 \newline
12436 \SpecialChar ~
12437 \SpecialChar ~
12438 \SpecialChar ~
12439 \SpecialChar ~
12440 mov  a,@r0
12441 \newline
12442 \SpecialChar ~
12443 \SpecialChar ~
12444 \SpecialChar ~
12445 \SpecialChar ~
12446 add  a,r2
12447 \newline
12448 \SpecialChar ~
12449 \SpecialChar ~
12450 \SpecialChar ~
12451 \SpecialChar ~
12452 mov  dpl,a
12453 \newline
12454 \SpecialChar ~
12455 \SpecialChar ~
12456 \SpecialChar ~
12457 \SpecialChar ~
12458 mov  dph,#0x00
12459 \newline
12460 \SpecialChar ~
12461 \SpecialChar ~
12462 \SpecialChar ~
12463 \SpecialChar ~
12464 mov  sp,_bp
12465 \newline
12466 \SpecialChar ~
12467 \SpecialChar ~
12468 \SpecialChar ~
12469 \SpecialChar ~
12470 pop  _bp
12471 \newline
12472 \SpecialChar ~
12473 \SpecialChar ~
12474 \SpecialChar ~
12475 \SpecialChar ~
12476 ret
12477 \layout Standard
12478
12479 The compiling and linking procedure remains the same, however note the extra
12480  entry & exit linkage required for the assembler code, _bp is the stack
12481  frame pointer and is used to compute the offset into the stack for parameters
12482  and local variables.
12483 \layout Subsection
12484
12485 External Stack
12486 \begin_inset LatexCommand \index{stack}
12487
12488 \end_inset
12489
12490
12491 \begin_inset LatexCommand \index{External stack}
12492
12493 \end_inset
12494
12495
12496 \layout Standard
12497
12498 The external stack is located at the start of the external ram segment,
12499  and is 256 bytes in size.
12500  When -
12501 \begin_inset ERT
12502 status Collapsed
12503
12504 \layout Standard
12505
12506 \backslash
12507 /
12508 \end_inset
12509
12510 -xstack option is used to compile the program, the parameters and local
12511  variables of all reentrant functions are allocated in this area.
12512  This option is provided for programs with large stack space requirements.
12513  When used with the -
12514 \begin_inset ERT
12515 status Collapsed
12516
12517 \layout Standard
12518
12519 \backslash
12520 /
12521 \end_inset
12522
12523 -stack-auto option, all parameters and local variables are allocated on
12524  the external stack (note support libraries will need to be recompiled with
12525  the same options).
12526 \layout Standard
12527
12528 The compiler outputs the higher order address byte of the external ram segment
12529  into PORT P2, therefore when using the External Stack option, this port
12530  MAY NOT be used by the application program.
12531 \layout Subsection
12532
12533 ANSI-Compliance
12534 \begin_inset LatexCommand \index{ANSI-compliance}
12535
12536 \end_inset
12537
12538
12539 \layout Standard
12540
12541 Deviations from the compliance:
12542 \layout Itemize
12543
12544 functions are not always reentrant.
12545 \layout Itemize
12546
12547 structures cannot be assigned values directly, cannot be passed as function
12548  parameters or assigned to each other and cannot be a return value from
12549  a function, e.g.:
12550 \begin_deeper
12551 \layout Verse
12552
12553
12554 \family typewriter
12555 struct s { ...
12556  };
12557 \newline
12558 struct s s1, s2;
12559 \newline
12560 foo()
12561 \newline
12562 {
12563 \newline
12564 \SpecialChar ~
12565 \SpecialChar ~
12566 \SpecialChar ~
12567 \SpecialChar ~
12568 ...
12569
12570 \newline
12571 \SpecialChar ~
12572 \SpecialChar ~
12573 \SpecialChar ~
12574 \SpecialChar ~
12575 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
12576 \newline
12577 \SpecialChar ~
12578 \SpecialChar ~
12579 \SpecialChar ~
12580 \SpecialChar ~
12581 ...
12582
12583 \newline
12584 }
12585 \newline
12586 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
12587  */
12588 \newline
12589 {
12590 \newline
12591 \SpecialChar ~
12592 \SpecialChar ~
12593 \SpecialChar ~
12594 \SpecialChar ~
12595 struct s rets;
12596 \newline
12597 \SpecialChar ~
12598 \SpecialChar ~
12599 \SpecialChar ~
12600 \SpecialChar ~
12601 ...
12602
12603 \newline
12604 \SpecialChar ~
12605 \SpecialChar ~
12606 \SpecialChar ~
12607 \SpecialChar ~
12608 return rets;/* is invalid in SDCC although allowed in ANSI */
12609 \newline
12610 }
12611 \end_deeper
12612 \layout Itemize
12613
12614 'long long
12615 \begin_inset LatexCommand \index{long long (not supported)}
12616
12617 \end_inset
12618
12619 ' (64 bit integers
12620 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
12621
12622 \end_inset
12623
12624 ) not supported.
12625 \layout Itemize
12626
12627 'double
12628 \begin_inset LatexCommand \index{double (not supported)}
12629
12630 \end_inset
12631
12632 ' precision floating point
12633 \begin_inset LatexCommand \index{Floating point support}
12634
12635 \end_inset
12636
12637 not supported.
12638 \layout Itemize
12639
12640 No support for setjmp and longjmp (for now).
12641 \layout Itemize
12642
12643 Old K&R style
12644 \begin_inset LatexCommand \index{K\&R style}
12645
12646 \end_inset
12647
12648  function declarations are NOT allowed.
12649 \begin_deeper
12650 \layout Verse
12651
12652
12653 \family typewriter
12654 foo(i,j) /* this old style of function declarations */
12655 \newline
12656 int i,j; /* are valid in ANSI but not valid in SDCC */
12657 \newline
12658 {
12659 \newline
12660 \SpecialChar ~
12661 \SpecialChar ~
12662 \SpecialChar ~
12663 \SpecialChar ~
12664 ...
12665
12666 \newline
12667 }
12668 \end_deeper
12669 \layout Itemize
12670
12671 functions declared as pointers must be dereferenced during the call.
12672 \begin_deeper
12673 \layout Verse
12674
12675
12676 \family typewriter
12677 int (*foo)();
12678 \newline
12679 ...
12680
12681 \newline
12682 /* has to be called like this */
12683 \newline
12684 (*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
12685 \end_deeper
12686 \layout Subsection
12687
12688 Cyclomatic Complexity
12689 \begin_inset LatexCommand \index{Cyclomatic complexity}
12690
12691 \end_inset
12692
12693
12694 \layout Standard
12695
12696 Cyclomatic complexity of a function is defined as the number of independent
12697  paths the program can take during execution of the function.
12698  This is an important number since it defines the number test cases you
12699  have to generate to validate the function.
12700  The accepted industry standard for complexity number is 10, if the cyclomatic
12701  complexity reported by SDCC exceeds 10 you should think about simplification
12702  of the function logic.
12703  Note that the complexity level is not related to the number of lines of
12704  code in a function.
12705  Large functions can have low complexity, and small functions can have large
12706  complexity levels.
12707
12708 \newline
12709
12710 \newline
12711 SDCC uses the following formula to compute the complexity:
12712 \newline
12713
12714 \layout Standard
12715
12716 complexity = (number of edges in control flow graph) - (number of nodes
12717  in control flow graph) + 2;
12718 \newline
12719
12720 \newline
12721 Having said that the industry standard is 10, you should be aware that in
12722  some cases it be may unavoidable to have a complexity level of less than
12723  10.
12724  For example if you have switch statement with more than 10 case labels,
12725  each case label adds one to the complexity level.
12726  The complexity level is by no means an absolute measure of the algorithmic
12727  complexity of the function, it does however provide a good starting point
12728  for which functions you might look at for further optimization.
12729 \layout Section
12730 \pagebreak_top
12731 TIPS
12732 \layout Standard
12733
12734 Here are a few guidelines that will help the compiler generate more efficient
12735  code, some of the tips are specific to this compiler others are generally
12736  good programming practice.
12737 \layout Itemize
12738
12739 Use the smallest data type to represent your data-value.
12740  If it is known in advance that the value is going to be less than 256 then
12741  use an 'unsigned char' instead of a 'short' or 'int'.
12742 \layout Itemize
12743
12744 Use unsigned when it is known in advance that the value is not going to
12745  be negative.
12746  This helps especially if you are doing division or multiplication.
12747 \layout Itemize
12748
12749 NEVER jump into a LOOP.
12750 \layout Itemize
12751
12752 Declare the variables to be local whenever possible, especially loop control
12753  variables (induction).
12754 \layout Itemize
12755
12756 Since the compiler does not always do implicit integral promotion, the programme
12757 r should do an explicit cast when integral promotion is required.
12758 \layout Itemize
12759
12760 Reducing the size of division, multiplication & modulus operations can reduce
12761  code size substantially.
12762  Take the following code for example.
12763 \begin_deeper
12764 \layout Verse
12765
12766
12767 \family typewriter
12768 foobar(unsigned int p1, unsigned char ch)
12769 \newline
12770 {
12771 \newline
12772 \SpecialChar ~
12773 \SpecialChar ~
12774 \SpecialChar ~
12775 \SpecialChar ~
12776 unsigned char ch1 = p1 % ch ;
12777 \newline
12778 \SpecialChar ~
12779 \SpecialChar ~
12780 \SpecialChar ~
12781 \SpecialChar ~
12782 ....
12783 \newline
12784 }
12785 \layout Standard
12786
12787 For the modulus operation the variable ch will be promoted to unsigned int
12788  first then the modulus operation will be performed (this will lead to a
12789  call to support routine _moduint()), and the result will be casted to a
12790  char.
12791  If the code is changed to
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 = (unsigned char)p1 % ch ;
12805 \newline
12806 \SpecialChar ~
12807 \SpecialChar ~
12808 \SpecialChar ~
12809 \SpecialChar ~
12810 ....
12811 \newline
12812 }
12813 \layout Standard
12814
12815 It would substantially reduce the code generated (future versions of the
12816  compiler will be smart enough to detect such optimization opportunities).
12817 \end_deeper
12818 \layout Subsection
12819
12820 Notes on MCS51 memory
12821 \begin_inset LatexCommand \index{MCS51 memory}
12822
12823 \end_inset
12824
12825  layout
12826 \layout Standard
12827
12828 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
12829  RAM memory which is structured as follows
12830 \newline
12831
12832 \newline
12833 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
12834
12835 \newline
12836 - Bytes 20-2F - 16 bytes to hold 128 bit variables and,
12837 \newline
12838 - Bytes 30-7F - 80 bytes for general purpose use.
12839 \newline
12840
12841 \layout Standard
12842
12843 Additionally some members of the MCS51 family may have up to 128 bytes of
12844  additional, indirectly addressable, internal RAM memory (
12845 \emph on
12846 idata
12847 \emph default
12848 ).
12849  Furthermore, some chips may have some built in external memory (
12850 \emph on
12851 xdata
12852 \emph default
12853 ) which should not be confused with the internal, directly addressable RAM
12854  memory (
12855 \emph on
12856 data
12857 \emph default
12858 ).
12859  Usually this built in
12860 \emph on
12861 xdata
12862 \emph default
12863  memory has to be activated before using it (you can probably find this
12864  information on the datasheet of the microcontroller your are using).
12865 \layout Standard
12866
12867 Normally SDCC will only use the first bank
12868 \begin_inset LatexCommand \index{bank}
12869
12870 \end_inset
12871
12872  of registers (register bank 0), but it is possible to specify that other
12873  banks of registers should be used in interrupt
12874 \begin_inset LatexCommand \index{interrupt}
12875
12876 \end_inset
12877
12878  routines.
12879  By default, the compiler will place the stack after the last byte of allocated
12880  memory for variables.
12881  For example, if the first 2 banks of registers are used, and only four
12882  bytes are used for
12883 \emph on
12884 data
12885 \emph default
12886  variables, it will position the base of the internal stack at address 20
12887  (0x14).
12888  This implies that as the stack
12889 \begin_inset LatexCommand \index{stack}
12890
12891 \end_inset
12892
12893  grows, it will use up the remaining register banks, and the 16 bytes used
12894  by the 128 bit variables, and 80 bytes for general purpose use.
12895  If any bit variables are used, the data variables will be placed after
12896  the byte holding the last bit variable.
12897  For example, if register banks 0 and 1 are used, and there are 9 bit variables
12898  (two bytes used),
12899 \emph on
12900 data
12901 \emph default
12902  variables will be placed starting at address 0x22.
12903  You can also use -
12904 \begin_inset ERT
12905 status Collapsed
12906
12907 \layout Standard
12908
12909 \backslash
12910 /
12911 \end_inset
12912
12913 -data-loc
12914 \begin_inset LatexCommand \index{-\/-data-loc}
12915
12916 \end_inset
12917
12918  to specify the start address of the
12919 \emph on
12920 data
12921 \emph default
12922  and -
12923 \begin_inset ERT
12924 status Collapsed
12925
12926 \layout Standard
12927
12928 \backslash
12929 /
12930 \end_inset
12931
12932 -iram-size to specify the size of the total internal RAM (
12933 \emph on
12934 data
12935 \emph default
12936 +
12937 \emph on
12938 idata
12939 \emph default
12940 ).
12941
12942 \layout Standard
12943
12944 By default the 8051 linker will place the stack after the last byte of data
12945  variables.
12946  Option -
12947 \begin_inset ERT
12948 status Collapsed
12949
12950 \layout Standard
12951
12952 \backslash
12953 /
12954 \end_inset
12955
12956 -stack-loc
12957 \begin_inset LatexCommand \index{-\/-stack-loc}
12958
12959 \end_inset
12960
12961  allows you to specify the start of the stack, i.e.
12962  you could start it after any data in the general purpose area.
12963  If your microcontroller has additional indirectly addressable internal
12964  RAM (
12965 \emph on
12966 idata
12967 \emph default
12968 ) you can place the stack on it.
12969  You may also need to use -
12970 \begin_inset ERT
12971 status Collapsed
12972
12973 \layout Standard
12974
12975 \backslash
12976 /
12977 \end_inset
12978
12979 -xdata-loc
12980 \begin_inset LatexCommand \index{-\/-data-loc}
12981
12982 \end_inset
12983
12984  to set the start address of the external RAM (
12985 \emph on
12986 xdata
12987 \emph default
12988 ) and -
12989 \begin_inset ERT
12990 status Collapsed
12991
12992 \layout Standard
12993
12994 \backslash
12995 /
12996 \end_inset
12997
12998 -xram-size
12999 \begin_inset LatexCommand \index{-\/-data-loc}
13000
13001 \end_inset
13002
13003  to specify its size.
13004  Same goes for the code memory, using -
13005 \begin_inset ERT
13006 status Collapsed
13007
13008 \layout Standard
13009
13010 \backslash
13011 /
13012 \end_inset
13013
13014 -code-loc
13015 \begin_inset LatexCommand \index{-\/-data-loc}
13016
13017 \end_inset
13018
13019  and -
13020 \begin_inset ERT
13021 status Collapsed
13022
13023 \layout Standard
13024
13025 \backslash
13026 /
13027 \end_inset
13028
13029 -code-size
13030 \begin_inset LatexCommand \index{-\/-data-loc}
13031
13032 \end_inset
13033
13034 .
13035  If in doubt, don't specify any options and see if the resulting memory
13036  layout is appropriate, then you can adjust it.
13037 \layout Standard
13038
13039 The 8051 linker generates two files with memory allocation information.
13040  The first, with extension .map shows all the variables and segments.
13041  The second with extension .mem shows the final memory layout.
13042  The linker will complaint either if memory segments overlap, there is not
13043  enough memory, or there is not enough space for stack.
13044  If you get any linking warnings and/or errors related to stack or segments
13045  allocation, take a look at either the .map or .mem files to find out what
13046  the problem is.
13047  The .mem file may even suggest a solution to the problem.
13048 \layout Subsection
13049
13050 Tools
13051 \begin_inset LatexCommand \index{Tools}
13052
13053 \end_inset
13054
13055  included in the distribution
13056 \newline
13057
13058 \layout Standard
13059 \align center
13060
13061 \begin_inset  Tabular
13062 <lyxtabular version="3" rows="12" columns="3">
13063 <features>
13064 <column alignment="center" valignment="top" leftline="true" width="0pt">
13065 <column alignment="center" valignment="top" leftline="true" width="0pt">
13066 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
13067 <row topline="true" bottomline="true">
13068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13069 \begin_inset Text
13070
13071 \layout Standard
13072
13073 Name
13074 \end_inset
13075 </cell>
13076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13077 \begin_inset Text
13078
13079 \layout Standard
13080
13081 Purpose
13082 \end_inset
13083 </cell>
13084 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13085 \begin_inset Text
13086
13087 \layout Standard
13088
13089 Directory
13090 \end_inset
13091 </cell>
13092 </row>
13093 <row topline="true">
13094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13095 \begin_inset Text
13096
13097 \layout Standard
13098
13099 uCsim
13100 \end_inset
13101 </cell>
13102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13103 \begin_inset Text
13104
13105 \layout Standard
13106
13107 Simulator for various architectures
13108 \end_inset
13109 </cell>
13110 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13111 \begin_inset Text
13112
13113 \layout Standard
13114
13115 sdcc/sim/ucsim
13116 \end_inset
13117 </cell>
13118 </row>
13119 <row topline="true">
13120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13121 \begin_inset Text
13122
13123 \layout Standard
13124
13125 keil2sdcc.pl
13126 \end_inset
13127 </cell>
13128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13129 \begin_inset Text
13130
13131 \layout Standard
13132
13133 header file conversion
13134 \end_inset
13135 </cell>
13136 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13137 \begin_inset Text
13138
13139 \layout Standard
13140
13141 sdcc/support/scripts
13142 \end_inset
13143 </cell>
13144 </row>
13145 <row topline="true">
13146 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13147 \begin_inset Text
13148
13149 \layout Standard
13150
13151 mh2h.c
13152 \end_inset
13153 </cell>
13154 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13155 \begin_inset Text
13156
13157 \layout Standard
13158
13159 header file conversion
13160 \end_inset
13161 </cell>
13162 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13163 \begin_inset Text
13164
13165 \layout Standard
13166
13167 sdcc/support/scripts
13168 \end_inset
13169 </cell>
13170 </row>
13171 <row topline="true">
13172 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13173 \begin_inset Text
13174
13175 \layout Standard
13176
13177 as-gbz80
13178 \end_inset
13179 </cell>
13180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13181 \begin_inset Text
13182
13183 \layout Standard
13184
13185 Assembler
13186 \end_inset
13187 </cell>
13188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13189 \begin_inset Text
13190
13191 \layout Standard
13192
13193
13194 \family roman
13195 \series medium
13196 \shape up
13197 \size normal
13198 \emph off
13199 \bar no
13200 \noun off
13201 \color none
13202 sdcc/bin
13203 \end_inset
13204 </cell>
13205 </row>
13206 <row topline="true">
13207 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13208 \begin_inset Text
13209
13210 \layout Standard
13211
13212 as-z80
13213 \end_inset
13214 </cell>
13215 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13216 \begin_inset Text
13217
13218 \layout Standard
13219
13220 Assembler
13221 \end_inset
13222 </cell>
13223 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13224 \begin_inset Text
13225
13226 \layout Standard
13227
13228
13229 \family roman
13230 \series medium
13231 \shape up
13232 \size normal
13233 \emph off
13234 \bar no
13235 \noun off
13236 \color none
13237 sdcc/bin
13238 \end_inset
13239 </cell>
13240 </row>
13241 <row topline="true">
13242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13243 \begin_inset Text
13244
13245 \layout Standard
13246
13247 asx8051
13248 \end_inset
13249 </cell>
13250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13251 \begin_inset Text
13252
13253 \layout Standard
13254
13255 Assembler
13256 \end_inset
13257 </cell>
13258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13259 \begin_inset Text
13260
13261 \layout Standard
13262
13263
13264 \family roman
13265 \series medium
13266 \shape up
13267 \size normal
13268 \emph off
13269 \bar no
13270 \noun off
13271 \color none
13272 sdcc/bin
13273 \end_inset
13274 </cell>
13275 </row>
13276 <row topline="true">
13277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13278 \begin_inset Text
13279
13280 \layout Standard
13281
13282 sdcdb
13283 \end_inset
13284 </cell>
13285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13286 \begin_inset Text
13287
13288 \layout Standard
13289
13290 Simulator
13291 \end_inset
13292 </cell>
13293 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13294 \begin_inset Text
13295
13296 \layout Standard
13297
13298
13299 \family roman
13300 \series medium
13301 \shape up
13302 \size normal
13303 \emph off
13304 \bar no
13305 \noun off
13306 \color none
13307 sdcc/bin
13308 \end_inset
13309 </cell>
13310 </row>
13311 <row topline="true">
13312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13313 \begin_inset Text
13314
13315 \layout Standard
13316
13317 aslink
13318 \end_inset
13319 </cell>
13320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13321 \begin_inset Text
13322
13323 \layout Standard
13324
13325 Linker
13326 \end_inset
13327 </cell>
13328 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13329 \begin_inset Text
13330
13331 \layout Standard
13332
13333
13334 \family roman
13335 \series medium
13336 \shape up
13337 \size normal
13338 \emph off
13339 \bar no
13340 \noun off
13341 \color none
13342 sdcc/bin
13343 \end_inset
13344 </cell>
13345 </row>
13346 <row topline="true">
13347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13348 \begin_inset Text
13349
13350 \layout Standard
13351
13352 link-z80
13353 \end_inset
13354 </cell>
13355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13356 \begin_inset Text
13357
13358 \layout Standard
13359
13360 Linker
13361 \end_inset
13362 </cell>
13363 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13364 \begin_inset Text
13365
13366 \layout Standard
13367
13368
13369 \family roman
13370 \series medium
13371 \shape up
13372 \size normal
13373 \emph off
13374 \bar no
13375 \noun off
13376 \color none
13377 sdcc/bin
13378 \end_inset
13379 </cell>
13380 </row>
13381 <row topline="true">
13382 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13383 \begin_inset Text
13384
13385 \layout Standard
13386
13387 link-gbz80
13388 \end_inset
13389 </cell>
13390 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13391 \begin_inset Text
13392
13393 \layout Standard
13394
13395 Linker
13396 \end_inset
13397 </cell>
13398 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13399 \begin_inset Text
13400
13401 \layout Standard
13402
13403
13404 \family roman
13405 \series medium
13406 \shape up
13407 \size normal
13408 \emph off
13409 \bar no
13410 \noun off
13411 \color none
13412 sdcc/bin
13413 \end_inset
13414 </cell>
13415 </row>
13416 <row topline="true" bottomline="true">
13417 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13418 \begin_inset Text
13419
13420 \layout Standard
13421
13422 packihx
13423 \end_inset
13424 </cell>
13425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13426 \begin_inset Text
13427
13428 \layout Standard
13429
13430 ihx packer
13431 \end_inset
13432 </cell>
13433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13434 \begin_inset Text
13435
13436 \layout Standard
13437
13438
13439 \family roman
13440 \series medium
13441 \shape up
13442 \size normal
13443 \emph off
13444 \bar no
13445 \noun off
13446 \color none
13447 sdcc/bin
13448 \end_inset
13449 </cell>
13450 </row>
13451 </lyxtabular>
13452
13453 \end_inset
13454
13455
13456 \newline
13457
13458 \layout Subsection
13459
13460 Related open source tools
13461 \begin_inset LatexCommand \index{Related tools}
13462
13463 \end_inset
13464
13465
13466 \newline
13467
13468 \layout Standard
13469 \align center
13470
13471 \begin_inset  Tabular
13472 <lyxtabular version="3" rows="8" columns="3">
13473 <features>
13474 <column alignment="center" valignment="top" leftline="true" width="0pt">
13475 <column alignment="block" valignment="top" leftline="true" width="30line%">
13476 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
13477 <row topline="true" bottomline="true">
13478 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13479 \begin_inset Text
13480
13481 \layout Standard
13482
13483 Name
13484 \end_inset
13485 </cell>
13486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13487 \begin_inset Text
13488
13489 \layout Standard
13490
13491 Purpose
13492 \end_inset
13493 </cell>
13494 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13495 \begin_inset Text
13496
13497 \layout Standard
13498
13499 Where to get
13500 \end_inset
13501 </cell>
13502 </row>
13503 <row topline="true">
13504 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13505 \begin_inset Text
13506
13507 \layout Standard
13508
13509 gpsim
13510 \begin_inset LatexCommand \index{gpsim}
13511
13512 \end_inset
13513
13514
13515 \end_inset
13516 </cell>
13517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13518 \begin_inset Text
13519
13520 \layout Standard
13521
13522 PIC simulator
13523 \end_inset
13524 </cell>
13525 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13526 \begin_inset Text
13527
13528 \layout Standard
13529
13530
13531 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
13532
13533 \end_inset
13534
13535
13536 \end_inset
13537 </cell>
13538 </row>
13539 <row topline="true">
13540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13541 \begin_inset Text
13542
13543 \layout Standard
13544
13545 flP5
13546 \end_inset
13547 </cell>
13548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13549 \begin_inset Text
13550
13551 \layout Standard
13552
13553 PIC programmer
13554 \end_inset
13555 </cell>
13556 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13557 \begin_inset Text
13558
13559 \layout Standard
13560
13561
13562 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
13563
13564 \end_inset
13565
13566
13567 \end_inset
13568 </cell>
13569 </row>
13570 <row topline="true">
13571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13572 \begin_inset Text
13573
13574 \layout Standard
13575
13576 srecord
13577 \begin_inset LatexCommand \index{srecord}
13578
13579 \end_inset
13580
13581
13582 \end_inset
13583 </cell>
13584 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13585 \begin_inset Text
13586
13587 \layout Standard
13588
13589 Object file conversion, checksumming, ...
13590 \end_inset
13591 </cell>
13592 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13593 \begin_inset Text
13594
13595 \layout Standard
13596
13597
13598 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
13599
13600 \end_inset
13601
13602
13603 \end_inset
13604 </cell>
13605 </row>
13606 <row topline="true">
13607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13608 \begin_inset Text
13609
13610 \layout Standard
13611
13612 objdump
13613 \begin_inset LatexCommand \index{objdump}
13614
13615 \end_inset
13616
13617
13618 \end_inset
13619 </cell>
13620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13621 \begin_inset Text
13622
13623 \layout Standard
13624
13625 Object file conversion, ...
13626 \end_inset
13627 </cell>
13628 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13629 \begin_inset Text
13630
13631 \layout Standard
13632
13633 Part of binutils (should be there anyway)
13634 \end_inset
13635 </cell>
13636 </row>
13637 <row topline="true">
13638 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13639 \begin_inset Text
13640
13641 \layout Standard
13642
13643 doxygen
13644 \begin_inset LatexCommand \index{doxygen}
13645
13646 \end_inset
13647
13648
13649 \end_inset
13650 </cell>
13651 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13652 \begin_inset Text
13653
13654 \layout Standard
13655
13656 Source code documentation system
13657 \end_inset
13658 </cell>
13659 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13660 \begin_inset Text
13661
13662 \layout Standard
13663
13664
13665 \begin_inset LatexCommand \url{http://www.doxygen.org}
13666
13667 \end_inset
13668
13669
13670 \end_inset
13671 </cell>
13672 </row>
13673 <row topline="true">
13674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13675 \begin_inset Text
13676
13677 \layout Standard
13678
13679 splint
13680 \begin_inset LatexCommand \index{splint}
13681
13682 \end_inset
13683
13684
13685 \end_inset
13686 </cell>
13687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13688 \begin_inset Text
13689
13690 \layout Standard
13691
13692 Statically checks c sources
13693 \end_inset
13694 </cell>
13695 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13696 \begin_inset Text
13697
13698 \layout Standard
13699
13700
13701 \begin_inset LatexCommand \url{http://www.splint.org}
13702
13703 \end_inset
13704
13705
13706 \end_inset
13707 </cell>
13708 </row>
13709 <row topline="true" bottomline="true">
13710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13711 \begin_inset Text
13712
13713 \layout Standard
13714
13715 ddd
13716 \begin_inset LatexCommand \index{ddd}
13717
13718 \end_inset
13719
13720
13721 \end_inset
13722 </cell>
13723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13724 \begin_inset Text
13725
13726 \layout Standard
13727
13728 Debugger, serves nicely as GUI to sdcdb
13729 \begin_inset LatexCommand \index{sdcdb}
13730
13731 \end_inset
13732
13733
13734 \begin_inset Foot
13735 collapsed false
13736
13737 \layout Standard
13738
13739 (sdcdb and ddd are available for Unix only)
13740 \end_inset
13741
13742
13743 \end_inset
13744 </cell>
13745 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13746 \begin_inset Text
13747
13748 \layout Standard
13749
13750
13751 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
13752
13753 \end_inset
13754
13755
13756 \end_inset
13757 </cell>
13758 </row>
13759 </lyxtabular>
13760
13761 \end_inset
13762
13763
13764 \newline
13765
13766 \layout Subsection
13767
13768 Related documentation / recommended reading
13769 \newline
13770
13771 \layout Standard
13772 \align center
13773
13774 \begin_inset  Tabular
13775 <lyxtabular version="3" rows="5" columns="3">
13776 <features>
13777 <column alignment="center" valignment="top" leftline="true" width="0pt">
13778 <column alignment="block" valignment="top" leftline="true" width="30line%">
13779 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
13780 <row topline="true" bottomline="true">
13781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13782 \begin_inset Text
13783
13784 \layout Standard
13785
13786 Name
13787 \end_inset
13788 </cell>
13789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13790 \begin_inset Text
13791
13792 \layout Standard
13793
13794 Subject / Title
13795 \end_inset
13796 </cell>
13797 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13798 \begin_inset Text
13799
13800 \layout Standard
13801
13802 Where to get
13803 \end_inset
13804 </cell>
13805 </row>
13806 <row topline="true">
13807 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13808 \begin_inset Text
13809
13810 \layout Standard
13811
13812 S.
13813  S.
13814  Muchnick
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 Advanced Compiler Design and Implementation
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 bookstore
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
13841 \family roman
13842 \series medium
13843 \shape up
13844 \size normal
13845 \emph off
13846 \bar no
13847 \noun off
13848 \color none
13849 c-refcard.pdf
13850 \end_inset
13851 </cell>
13852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13853 \begin_inset Text
13854
13855 \layout Standard
13856
13857 C Reference Card
13858 \begin_inset LatexCommand \index{C Reference card}
13859
13860 \end_inset
13861
13862 , 2 pages
13863 \end_inset
13864 </cell>
13865 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13866 \begin_inset Text
13867
13868 \layout Standard
13869
13870
13871 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
13872
13873 \end_inset
13874
13875
13876 \end_inset
13877 </cell>
13878 </row>
13879 <row topline="true">
13880 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13881 \begin_inset Text
13882
13883 \layout Standard
13884
13885 test_suite_spec.pdf
13886 \end_inset
13887 </cell>
13888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13889 \begin_inset Text
13890
13891 \layout Standard
13892
13893 sdcc regression test
13894 \begin_inset LatexCommand \index{Regression test}
13895
13896 \end_inset
13897
13898
13899 \end_inset
13900 </cell>
13901 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13902 \begin_inset Text
13903
13904 \layout Standard
13905
13906 sdcc/doc
13907 \end_inset
13908 </cell>
13909 </row>
13910 <row topline="true" bottomline="true">
13911 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13912 \begin_inset Text
13913
13914 \layout Standard
13915
13916
13917 \family roman
13918 \series medium
13919 \shape up
13920 \size normal
13921 \emph off
13922 \bar no
13923 \noun off
13924 \color none
13925 cdbfileformat.pd
13926 \family default
13927 \series default
13928 \shape default
13929 \size default
13930 \emph default
13931 \bar default
13932 \noun default
13933 \color default
13934 f
13935 \end_inset
13936 </cell>
13937 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13938 \begin_inset Text
13939
13940 \layout Standard
13941
13942 sdcc internal documentation
13943 \end_inset
13944 </cell>
13945 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13946 \begin_inset Text
13947
13948 \layout Standard
13949
13950 sdcc/doc
13951 \end_inset
13952 </cell>
13953 </row>
13954 </lyxtabular>
13955
13956 \end_inset
13957
13958
13959 \newline
13960
13961 \layout Section
13962 \pagebreak_top
13963 Retargetting for other MCUs.
13964 \layout Standard
13965
13966 The issues for retargetting the compiler are far too numerous to be covered
13967  by this document.
13968  What follows is a brief description of each of the seven phases of the
13969  compiler and its MCU dependency.
13970 \layout Itemize
13971
13972 Parsing the source and building the annotated parse tree.
13973  This phase is largely MCU independent (except for the language extensions).
13974  Syntax & semantic checks are also done in this phase, along with some initial
13975  optimizations like back patching labels and the pattern matching optimizations
13976  like bit-rotation etc.
13977 \layout Itemize
13978
13979 The second phase involves generating an intermediate code which can be easy
13980  manipulated during the later phases.
13981  This phase is entirely MCU independent.
13982  The intermediate code generation assumes the target machine has unlimited
13983  number of registers, and designates them with the name iTemp.
13984  The compiler can be made to dump a human readable form of the code generated
13985  by using the -
13986 \begin_inset ERT
13987 status Collapsed
13988
13989 \layout Standard
13990
13991 \backslash
13992 /
13993 \end_inset
13994
13995 -dumpraw option.
13996 \layout Itemize
13997
13998 This phase does the bulk of the standard optimizations and is also MCU independe
13999 nt.
14000  This phase can be broken down into several sub-phases:
14001 \newline
14002
14003 \newline
14004 Break down intermediate code (iCode) into basic blocks.
14005 \newline
14006 Do control flow & data flow analysis on the basic blocks.
14007 \newline
14008 Do local common subexpression elimination, then global subexpression elimination
14009 \newline
14010 Dead code elimination
14011 \newline
14012 Loop optimizations
14013 \newline
14014 If loop optimizations caused any changes then do 'global subexpression eliminati
14015 on' and 'dead code elimination' again.
14016 \layout Itemize
14017
14018 This phase determines the live-ranges; by live range I mean those iTemp
14019  variables defined by the compiler that still survive after all the optimization
14020 s.
14021  Live range analysis
14022 \begin_inset LatexCommand \index{Live range analysis}
14023
14024 \end_inset
14025
14026  is essential for register allocation, since these computation determines
14027  which of these iTemps will be assigned to registers, and for how long.
14028 \layout Itemize
14029
14030 Phase five is register allocation.
14031  There are two parts to this process.
14032 \newline
14033
14034 \newline
14035 The first part I call 'register packing' (for lack of a better term).
14036  In this case several MCU specific expression folding is done to reduce
14037  register pressure.
14038 \newline
14039
14040 \newline
14041 The second part is more MCU independent and deals with allocating registers
14042  to the remaining live ranges.
14043  A lot of MCU specific code does creep into this phase because of the limited
14044  number of index registers available in the 8051.
14045 \layout Itemize
14046
14047 The Code generation phase is (unhappily), entirely MCU dependent and very
14048  little (if any at all) of this code can be reused for other MCU.
14049  However the scheme for allocating a homogenized assembler operand for each
14050  iCode operand may be reused.
14051 \layout Itemize
14052
14053 As mentioned in the optimization section the peep-hole optimizer is rule
14054  based system, which can reprogrammed for other MCUs.
14055 \layout Section
14056 \pagebreak_top
14057 SDCDB
14058 \begin_inset LatexCommand \index{sdcdb}
14059
14060 \end_inset
14061
14062  - Source Level Debugger
14063 \begin_inset LatexCommand \index{Debugger}
14064
14065 \end_inset
14066
14067
14068 \layout Standard
14069
14070 SDCC is distributed with a source level debugger.
14071  The debugger uses a command line interface, the command repertoire of the
14072  debugger has been kept as close to gdb
14073 \begin_inset LatexCommand \index{gdb}
14074
14075 \end_inset
14076
14077  (the GNU debugger) as possible.
14078  The configuration and build process is part of the standard compiler installati
14079 on, which also builds and installs the debugger in the target directory
14080  specified during configuration.
14081  The debugger allows you debug BOTH at the C source and at the ASM source
14082  level.
14083  Sdcdb is available on Unix platforms only.
14084 \layout Subsection
14085
14086 Compiling for Debugging
14087 \layout Standard
14088
14089 The \SpecialChar \-
14090 \SpecialChar \-
14091 debug option must be specified for all files for which debug information
14092  is to be generated.
14093  The complier generates a .adb file for each of these files.
14094  The linker creates the .cdb file from the .adb files and the address information.
14095  This .cdb is used by the debugger.
14096 \layout Subsection
14097
14098 How the Debugger Works
14099 \layout Standard
14100
14101 When the -
14102 \begin_inset ERT
14103 status Collapsed
14104
14105 \layout Standard
14106
14107 \backslash
14108 /
14109 \end_inset
14110
14111 -debug option is specified the compiler generates extra symbol information
14112  some of which are put into the the assembler source and some are put into
14113  the .adb file.
14114   Then the linker creates the .cdb file from the individual .adb files with
14115  the address information for the symbols.
14116  The debugger reads the symbolic information generated by the compiler &
14117  the address information generated by the linker.
14118  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
14119  execution is controlled by the debugger.
14120  When a command is issued for the debugger, it translates it into appropriate
14121  commands for the simulator.
14122 \layout Subsection
14123
14124 Starting the Debugger
14125 \layout Standard
14126
14127 The debugger can be started using the following command line.
14128  (Assume the file you are debugging has the file name foo).
14129 \newline
14130
14131 \newline
14132
14133 \family sans
14134 \series bold
14135 sdcdb foo
14136 \newline
14137
14138 \family default
14139 \series default
14140
14141 \newline
14142 The debugger will look for the following files.
14143 \layout Itemize
14144
14145 foo.c - the source file.
14146 \layout Itemize
14147
14148 foo.cdb - the debugger symbol information file.
14149 \layout Itemize
14150
14151 foo.ihx - the Intel hex format
14152 \begin_inset LatexCommand \index{Intel hex format}
14153
14154 \end_inset
14155
14156  object file.
14157 \layout Subsection
14158
14159 Command Line Options.
14160 \layout Itemize
14161
14162 -
14163 \begin_inset ERT
14164 status Collapsed
14165
14166 \layout Standard
14167
14168 \backslash
14169 /
14170 \end_inset
14171
14172 -directory=<source file directory> this option can used to specify the directory
14173  search list.
14174  The debugger will look into the directory list specified for source, cdb
14175  & ihx files.
14176  The items in the directory list must be separated by ':', e.g.
14177  if the source files can be in the directories /home/src1 and /home/src2,
14178  the -
14179 \begin_inset ERT
14180 status Collapsed
14181
14182 \layout Standard
14183
14184 \backslash
14185 /
14186 \end_inset
14187
14188 -directory option should be -
14189 \begin_inset ERT
14190 status Collapsed
14191
14192 \layout Standard
14193
14194 \backslash
14195 /
14196 \end_inset
14197
14198 -directory=/home/src1:/home/src2.
14199  Note there can be no spaces in the option.
14200
14201 \layout Itemize
14202
14203 -cd <directory> - change to the <directory>.
14204 \layout Itemize
14205
14206 -fullname - used by GUI front ends.
14207 \layout Itemize
14208
14209 -cpu <cpu-type> - this argument is passed to the simulator please see the
14210  simulator docs for details.
14211 \layout Itemize
14212
14213 -X <Clock frequency > this options is passed to the simulator please see
14214  the simulator docs for details.
14215 \layout Itemize
14216
14217 -s <serial port file> passed to simulator see the simulator docs for details.
14218 \layout Itemize
14219
14220 -S <serial in,out> passed to simulator see the simulator docs for details.
14221 \layout Subsection
14222
14223 Debugger Commands.
14224 \layout Standard
14225
14226 As mention earlier the command interface for the debugger has been deliberately
14227  kept as close the GNU debugger gdb, as possible.
14228  This will help the integration with existing graphical user interfaces
14229  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
14230 \layout Subsubsection
14231
14232 break [line | file:line | function | file:function]
14233 \layout Standard
14234
14235 Set breakpoint at specified line or function:
14236 \newline
14237
14238 \newline
14239
14240 \family sans
14241 \series bold
14242 sdcdb>break 100
14243 \newline
14244 sdcdb>break foo.c:100
14245 \newline
14246 sdcdb>break funcfoo
14247 \newline
14248 sdcdb>break foo.c:funcfoo
14249 \layout Subsubsection
14250
14251 clear [line | file:line | function | file:function ]
14252 \layout Standard
14253
14254 Clear breakpoint at specified line or function:
14255 \newline
14256
14257 \newline
14258
14259 \family sans
14260 \series bold
14261 sdcdb>clear 100
14262 \newline
14263 sdcdb>clear foo.c:100
14264 \newline
14265 sdcdb>clear funcfoo
14266 \newline
14267 sdcdb>clear foo.c:funcfoo
14268 \layout Subsubsection
14269
14270 continue
14271 \layout Standard
14272
14273 Continue program being debugged, after breakpoint.
14274 \layout Subsubsection
14275
14276 finish
14277 \layout Standard
14278
14279 Execute till the end of the current function.
14280 \layout Subsubsection
14281
14282 delete [n]
14283 \layout Standard
14284
14285 Delete breakpoint number 'n'.
14286  If used without any option clear ALL user defined break points.
14287 \layout Subsubsection
14288
14289 info [break | stack | frame | registers ]
14290 \layout Itemize
14291
14292 info break - list all breakpoints
14293 \layout Itemize
14294
14295 info stack - show the function call stack.
14296 \layout Itemize
14297
14298 info frame - show information about the current execution frame.
14299 \layout Itemize
14300
14301 info registers - show content of all registers.
14302 \layout Subsubsection
14303
14304 step
14305 \layout Standard
14306
14307 Step program until it reaches a different source line.
14308 \layout Subsubsection
14309
14310 next
14311 \layout Standard
14312
14313 Step program, proceeding through subroutine calls.
14314 \layout Subsubsection
14315
14316 run
14317 \layout Standard
14318
14319 Start debugged program.
14320 \layout Subsubsection
14321
14322 ptype variable
14323 \layout Standard
14324
14325 Print type information of the variable.
14326 \layout Subsubsection
14327
14328 print variable
14329 \layout Standard
14330
14331 print value of variable.
14332 \layout Subsubsection
14333
14334 file filename
14335 \layout Standard
14336
14337 load the given file name.
14338  Note this is an alternate method of loading file for debugging.
14339 \layout Subsubsection
14340
14341 frame
14342 \layout Standard
14343
14344 print information about current frame.
14345 \layout Subsubsection
14346
14347 set srcmode
14348 \layout Standard
14349
14350 Toggle between C source & assembly source.
14351 \layout Subsubsection
14352
14353 ! simulator command
14354 \layout Standard
14355
14356 Send the string following '!' to the simulator, the simulator response is
14357  displayed.
14358  Note the debugger does not interpret the command being sent to the simulator,
14359  so if a command like 'go' is sent the debugger can loose its execution
14360  context and may display incorrect values.
14361 \layout Subsubsection
14362
14363 quit.
14364 \layout Standard
14365
14366 "Watch me now.
14367  Iam going Down.
14368  My name is Bobby Brown"
14369 \layout Subsection
14370
14371 Interfacing with XEmacs
14372 \begin_inset LatexCommand \index{XEmacs}
14373
14374 \end_inset
14375
14376
14377 \begin_inset LatexCommand \index{Emacs}
14378
14379 \end_inset
14380
14381 .
14382 \layout Standard
14383
14384 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
14385  sdcdb.el and sdcdbsrc.el.
14386  These two files can be found in the $(prefix)/bin directory after the installat
14387 ion is complete.
14388  These files need to be loaded into XEmacs for the interface to work.
14389  This can be done at XEmacs startup time by inserting the following into
14390  your '.xemacs' file (which can be found in your HOME directory):
14391 \newline
14392
14393 \newline
14394
14395 \family typewriter
14396 (load-file sdcdbsrc.el)
14397 \family default
14398
14399 \newline
14400
14401 \newline
14402 .xemacs is a lisp file so the () around the command is REQUIRED.
14403  The files can also be loaded dynamically while XEmacs is running, set the
14404  environment variable 'EMACSLOADPATH' to the installation bin directory
14405  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
14406  To start the interface enter the following command:
14407 \newline
14408
14409 \newline
14410
14411 \family sans
14412 \series bold
14413 ESC-x sdcdbsrc
14414 \family default
14415 \series default
14416
14417 \newline
14418
14419 \newline
14420 You will prompted to enter the file name to be debugged.
14421
14422 \newline
14423
14424 \newline
14425 The command line options that are passed to the simulator directly are bound
14426  to default values in the file sdcdbsrc.el.
14427  The variables are listed below, these values maybe changed as required.
14428 \layout Itemize
14429
14430 sdcdbsrc-cpu-type '51
14431 \layout Itemize
14432
14433 sdcdbsrc-frequency '11059200
14434 \layout Itemize
14435
14436 sdcdbsrc-serial nil
14437 \layout Standard
14438
14439 The following is a list of key mapping for the debugger interface.
14440 \layout Standard
14441
14442 \SpecialChar ~
14443
14444 \family typewriter
14445
14446 \newline
14447 ;; Current Listing ::
14448 \newline
14449 ;;key\SpecialChar ~
14450 \SpecialChar ~
14451 \SpecialChar ~
14452 \SpecialChar ~
14453 \SpecialChar ~
14454 \SpecialChar ~
14455 \SpecialChar ~
14456 \SpecialChar ~
14457 \SpecialChar ~
14458 \SpecialChar ~
14459 \SpecialChar ~
14460 \SpecialChar ~
14461 \SpecialChar ~
14462 \SpecialChar ~
14463 \SpecialChar ~
14464 binding\SpecialChar ~
14465 \SpecialChar ~
14466 \SpecialChar ~
14467 \SpecialChar ~
14468 \SpecialChar ~
14469 \SpecialChar ~
14470 \SpecialChar ~
14471 \SpecialChar ~
14472 \SpecialChar ~
14473 \SpecialChar ~
14474 \SpecialChar ~
14475 \SpecialChar ~
14476 \SpecialChar ~
14477 \SpecialChar ~
14478 \SpecialChar ~
14479 \SpecialChar ~
14480 \SpecialChar ~
14481 \SpecialChar ~
14482 \SpecialChar ~
14483 \SpecialChar ~
14484 \SpecialChar ~
14485 \SpecialChar ~
14486 Comment
14487 \newline
14488 ;;---\SpecialChar ~
14489 \SpecialChar ~
14490 \SpecialChar ~
14491 \SpecialChar ~
14492 \SpecialChar ~
14493 \SpecialChar ~
14494 \SpecialChar ~
14495 \SpecialChar ~
14496 \SpecialChar ~
14497 \SpecialChar ~
14498 \SpecialChar ~
14499 \SpecialChar ~
14500 \SpecialChar ~
14501 \SpecialChar ~
14502 \SpecialChar ~
14503 ------\SpecialChar ~
14504 \SpecialChar ~
14505 \SpecialChar ~
14506 \SpecialChar ~
14507 \SpecialChar ~
14508 \SpecialChar ~
14509 \SpecialChar ~
14510 \SpecialChar ~
14511 \SpecialChar ~
14512 \SpecialChar ~
14513 \SpecialChar ~
14514 \SpecialChar ~
14515 \SpecialChar ~
14516 \SpecialChar ~
14517 \SpecialChar ~
14518 \SpecialChar ~
14519 \SpecialChar ~
14520 \SpecialChar ~
14521 \SpecialChar ~
14522 \SpecialChar ~
14523 \SpecialChar ~
14524 \SpecialChar ~
14525 --------
14526 \newline
14527 ;;
14528 \newline
14529 ;; n\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  sdcdb-next-from-src\SpecialChar ~
14544 \SpecialChar ~
14545 \SpecialChar ~
14546 \SpecialChar ~
14547 \SpecialChar ~
14548 \SpecialChar ~
14549 \SpecialChar ~
14550 \SpecialChar ~
14551 \SpecialChar ~
14552 \SpecialChar ~
14553 SDCDB next command
14554 \newline
14555 ;; b\SpecialChar ~
14556 \SpecialChar ~
14557 \SpecialChar ~
14558 \SpecialChar ~
14559 \SpecialChar ~
14560 \SpecialChar ~
14561 \SpecialChar ~
14562 \SpecialChar ~
14563 \SpecialChar ~
14564 \SpecialChar ~
14565 \SpecialChar ~
14566 \SpecialChar ~
14567 \SpecialChar ~
14568 \SpecialChar ~
14569  sdcdb-back-from-src\SpecialChar ~
14570 \SpecialChar ~
14571 \SpecialChar ~
14572 \SpecialChar ~
14573 \SpecialChar ~
14574 \SpecialChar ~
14575 \SpecialChar ~
14576 \SpecialChar ~
14577 \SpecialChar ~
14578 \SpecialChar ~
14579 SDCDB back command
14580 \newline
14581 ;; c\SpecialChar ~
14582 \SpecialChar ~
14583 \SpecialChar ~
14584 \SpecialChar ~
14585 \SpecialChar ~
14586 \SpecialChar ~
14587 \SpecialChar ~
14588 \SpecialChar ~
14589 \SpecialChar ~
14590 \SpecialChar ~
14591 \SpecialChar ~
14592 \SpecialChar ~
14593 \SpecialChar ~
14594 \SpecialChar ~
14595  sdcdb-cont-from-src\SpecialChar ~
14596 \SpecialChar ~
14597 \SpecialChar ~
14598 \SpecialChar ~
14599 \SpecialChar ~
14600 \SpecialChar ~
14601 \SpecialChar ~
14602 \SpecialChar ~
14603 \SpecialChar ~
14604 \SpecialChar ~
14605 SDCDB continue command
14606 \newline
14607 ;; s\SpecialChar ~
14608 \SpecialChar ~
14609 \SpecialChar ~
14610 \SpecialChar ~
14611 \SpecialChar ~
14612 \SpecialChar ~
14613 \SpecialChar ~
14614 \SpecialChar ~
14615 \SpecialChar ~
14616 \SpecialChar ~
14617 \SpecialChar ~
14618 \SpecialChar ~
14619 \SpecialChar ~
14620 \SpecialChar ~
14621  sdcdb-step-from-src\SpecialChar ~
14622 \SpecialChar ~
14623 \SpecialChar ~
14624 \SpecialChar ~
14625 \SpecialChar ~
14626 \SpecialChar ~
14627 \SpecialChar ~
14628 \SpecialChar ~
14629 \SpecialChar ~
14630 \SpecialChar ~
14631 SDCDB step command
14632 \newline
14633 ;; ?\SpecialChar ~
14634 \SpecialChar ~
14635 \SpecialChar ~
14636 \SpecialChar ~
14637 \SpecialChar ~
14638 \SpecialChar ~
14639 \SpecialChar ~
14640 \SpecialChar ~
14641 \SpecialChar ~
14642 \SpecialChar ~
14643 \SpecialChar ~
14644 \SpecialChar ~
14645 \SpecialChar ~
14646 \SpecialChar ~
14647  sdcdb-whatis-c-sexp\SpecialChar ~
14648 \SpecialChar ~
14649 \SpecialChar ~
14650 \SpecialChar ~
14651 \SpecialChar ~
14652 \SpecialChar ~
14653 \SpecialChar ~
14654 \SpecialChar ~
14655 \SpecialChar ~
14656 \SpecialChar ~
14657 SDCDB ptypecommand for data at
14658 \newline
14659 ;;\SpecialChar ~
14660 \SpecialChar ~
14661 \SpecialChar ~
14662 \SpecialChar ~
14663 \SpecialChar ~
14664 \SpecialChar ~
14665 \SpecialChar ~
14666 \SpecialChar ~
14667 \SpecialChar ~
14668 \SpecialChar ~
14669 \SpecialChar ~
14670 \SpecialChar ~
14671 \SpecialChar ~
14672 \SpecialChar ~
14673 \SpecialChar ~
14674 \SpecialChar ~
14675 \SpecialChar ~
14676 \SpecialChar ~
14677 \SpecialChar ~
14678 \SpecialChar ~
14679 \SpecialChar ~
14680 \SpecialChar ~
14681 \SpecialChar ~
14682 \SpecialChar ~
14683 \SpecialChar ~
14684 \SpecialChar ~
14685 \SpecialChar ~
14686 \SpecialChar ~
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  buffer point
14706 \newline
14707 ;; x\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  sdcdbsrc-delete\SpecialChar ~
14722 \SpecialChar ~
14723 \SpecialChar ~
14724 \SpecialChar ~
14725 \SpecialChar ~
14726 \SpecialChar ~
14727 \SpecialChar ~
14728 \SpecialChar ~
14729 \SpecialChar ~
14730 \SpecialChar ~
14731 \SpecialChar ~
14732 \SpecialChar ~
14733 \SpecialChar ~
14734 \SpecialChar ~
14735 SDCDB Delete all breakpoints if no arg
14736 \newline
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 \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 \SpecialChar ~
14764 \SpecialChar ~
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 given or delete arg (C-u arg x)
14784 \newline
14785 ;; m\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  sdcdbsrc-frame\SpecialChar ~
14800 \SpecialChar ~
14801 \SpecialChar ~
14802 \SpecialChar ~
14803 \SpecialChar ~
14804 \SpecialChar ~
14805 \SpecialChar ~
14806 \SpecialChar ~
14807 \SpecialChar ~
14808 \SpecialChar ~
14809 \SpecialChar ~
14810 \SpecialChar ~
14811 \SpecialChar ~
14812 \SpecialChar ~
14813 \SpecialChar ~
14814 SDCDB Display current frame if no arg,
14815 \newline
14816 ;;\SpecialChar ~
14817 \SpecialChar ~
14818 \SpecialChar ~
14819 \SpecialChar ~
14820 \SpecialChar ~
14821 \SpecialChar ~
14822 \SpecialChar ~
14823 \SpecialChar ~
14824 \SpecialChar ~
14825 \SpecialChar ~
14826 \SpecialChar ~
14827 \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 \SpecialChar ~
14843 \SpecialChar ~
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 given or display frame arg
14864 \newline
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 \SpecialChar ~
14892 \SpecialChar ~
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 buffer point
14913 \newline
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  sdcdbsrc-goto-sdcdb\SpecialChar ~
14929 \SpecialChar ~
14930 \SpecialChar ~
14931 \SpecialChar ~
14932 \SpecialChar ~
14933 \SpecialChar ~
14934 \SpecialChar ~
14935 \SpecialChar ~
14936 \SpecialChar ~
14937 \SpecialChar ~
14938 Goto the SDCDB output buffer
14939 \newline
14940 ;; p\SpecialChar ~
14941 \SpecialChar ~
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  sdcdb-print-c-sexp\SpecialChar ~
14955 \SpecialChar ~
14956 \SpecialChar ~
14957 \SpecialChar ~
14958 \SpecialChar ~
14959 \SpecialChar ~
14960 \SpecialChar ~
14961 \SpecialChar ~
14962 \SpecialChar ~
14963 \SpecialChar ~
14964 \SpecialChar ~
14965 SDCDB print command for data at
14966 \newline
14967 ;;\SpecialChar ~
14968 \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 \SpecialChar ~
14983 \SpecialChar ~
14984 \SpecialChar ~
14985 \SpecialChar ~
14986 \SpecialChar ~
14987 \SpecialChar ~
14988 \SpecialChar ~
14989 \SpecialChar ~
14990 \SpecialChar ~
14991 \SpecialChar ~
14992 \SpecialChar ~
14993 \SpecialChar ~
14994 \SpecialChar ~
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  buffer point
15014 \newline
15015 ;; g\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  sdcdbsrc-goto-sdcdb\SpecialChar ~
15030 \SpecialChar ~
15031 \SpecialChar ~
15032 \SpecialChar ~
15033 \SpecialChar ~
15034 \SpecialChar ~
15035 \SpecialChar ~
15036 \SpecialChar ~
15037 \SpecialChar ~
15038 \SpecialChar ~
15039 Goto the SDCDB output buffer
15040 \newline
15041 ;; t\SpecialChar ~
15042 \SpecialChar ~
15043 \SpecialChar ~
15044 \SpecialChar ~
15045 \SpecialChar ~
15046 \SpecialChar ~
15047 \SpecialChar ~
15048 \SpecialChar ~
15049 \SpecialChar ~
15050 \SpecialChar ~
15051 \SpecialChar ~
15052 \SpecialChar ~
15053 \SpecialChar ~
15054 \SpecialChar ~
15055  sdcdbsrc-mode\SpecialChar ~
15056 \SpecialChar ~
15057 \SpecialChar ~
15058 \SpecialChar ~
15059 \SpecialChar ~
15060 \SpecialChar ~
15061 \SpecialChar ~
15062 \SpecialChar ~
15063 \SpecialChar ~
15064 \SpecialChar ~
15065 \SpecialChar ~
15066 \SpecialChar ~
15067 \SpecialChar ~
15068 \SpecialChar ~
15069 \SpecialChar ~
15070 \SpecialChar ~
15071 Toggles Sdcdbsrc mode (turns it off)
15072 \newline
15073 ;;
15074 \newline
15075 ;; C-c C-f\SpecialChar ~
15076 \SpecialChar ~
15077 \SpecialChar ~
15078 \SpecialChar ~
15079 \SpecialChar ~
15080 \SpecialChar ~
15081 \SpecialChar ~
15082 \SpecialChar ~
15083  sdcdb-finish-from-src\SpecialChar ~
15084 \SpecialChar ~
15085 \SpecialChar ~
15086 \SpecialChar ~
15087 \SpecialChar ~
15088 \SpecialChar ~
15089 \SpecialChar ~
15090 \SpecialChar ~
15091 SDCDB finish command
15092 \newline
15093 ;;
15094 \newline
15095 ;; C-x SPC\SpecialChar ~
15096 \SpecialChar ~
15097 \SpecialChar ~
15098 \SpecialChar ~
15099 \SpecialChar ~
15100 \SpecialChar ~
15101 \SpecialChar ~
15102 \SpecialChar ~
15103  sdcdb-break\SpecialChar ~
15104 \SpecialChar ~
15105 \SpecialChar ~
15106 \SpecialChar ~
15107 \SpecialChar ~
15108 \SpecialChar ~
15109 \SpecialChar ~
15110 \SpecialChar ~
15111 \SpecialChar ~
15112 \SpecialChar ~
15113 \SpecialChar ~
15114 \SpecialChar ~
15115 \SpecialChar ~
15116 \SpecialChar ~
15117 \SpecialChar ~
15118 \SpecialChar ~
15119 \SpecialChar ~
15120 \SpecialChar ~
15121 Set break for line with point
15122 \newline
15123 ;; ESC t\SpecialChar ~
15124 \SpecialChar ~
15125 \SpecialChar ~
15126 \SpecialChar ~
15127 \SpecialChar ~
15128 \SpecialChar ~
15129 \SpecialChar ~
15130 \SpecialChar ~
15131 \SpecialChar ~
15132 \SpecialChar ~
15133  sdcdbsrc-mode\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 Toggle Sdcdbsrc mode
15150 \newline
15151 ;; ESC m\SpecialChar ~
15152 \SpecialChar ~
15153 \SpecialChar ~
15154 \SpecialChar ~
15155 \SpecialChar ~
15156 \SpecialChar ~
15157 \SpecialChar ~
15158 \SpecialChar ~
15159 \SpecialChar ~
15160 \SpecialChar ~
15161  sdcdbsrc-srcmode\SpecialChar ~
15162 \SpecialChar ~
15163 \SpecialChar ~
15164 \SpecialChar ~
15165 \SpecialChar ~
15166 \SpecialChar ~
15167 \SpecialChar ~
15168 \SpecialChar ~
15169 \SpecialChar ~
15170 \SpecialChar ~
15171 \SpecialChar ~
15172 \SpecialChar ~
15173  Toggle list mode
15174 \newline
15175 ;;
15176 \family default
15177
15178 \newline
15179
15180 \layout Section
15181
15182 Other Processors
15183 \layout Subsection
15184
15185 The Z80 and gbz80 port
15186 \layout Standard
15187
15188 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
15189  The port is incomplete - long support is incomplete (mul, div and mod are
15190  unimplemented), and both float and bitfield support is missing.
15191  Apart from that the code generated is correct.
15192 \layout Standard
15193
15194 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
15195  The stack frame is similar to that generated by the IAR Z80 compiler.
15196  IX is used as the base pointer, HL is used as a temporary register, and
15197  BC and DE are available for holding variables.
15198  IY is currently unused.
15199  Return values are stored in HL.
15200  One bad side effect of using IX as the base pointer is that a functions
15201  stack frame is limited to 127 bytes - this will be fixed in a later version.
15202 \layout Section
15203 \pagebreak_top
15204 Support
15205 \begin_inset LatexCommand \index{Support}
15206
15207 \end_inset
15208
15209
15210 \layout Standard
15211
15212 SDCC has grown to be a large project.
15213  The compiler alone (without the preprocessor, assembler and linker) is
15214  about 40,000 lines of code (blank stripped).
15215  The open source nature of this project is a key to its continued growth
15216  and support.
15217  You gain the benefit and support of many active software developers and
15218  end users.
15219  Is SDCC perfect? No, that's why we need your help.
15220  The developers take pride in fixing reported bugs.
15221  You can help by reporting the bugs and helping other SDCC users.
15222  There are lots of ways to contribute, and we encourage you to take part
15223  in making SDCC a great software package.
15224
15225 \layout Standard
15226
15227 The SDCC project is hosted on the sdcc sourceforge site at
15228 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
15229
15230 \end_inset
15231
15232 .
15233  You'll find the complete set of mailing lists
15234 \begin_inset LatexCommand \index{Mailing list}
15235
15236 \end_inset
15237
15238 , forums, bug reporting system, patch submission
15239 \begin_inset LatexCommand \index{Patch submission}
15240
15241 \end_inset
15242
15243  system, download
15244 \begin_inset LatexCommand \index{download}
15245
15246 \end_inset
15247
15248  area and cvs code repository
15249 \begin_inset LatexCommand \index{cvs code repository}
15250
15251 \end_inset
15252
15253  there.
15254 \layout Subsection
15255
15256 Reporting Bugs
15257 \begin_inset LatexCommand \index{Bugs}
15258
15259 \end_inset
15260
15261
15262 \begin_inset LatexCommand \index{Reporting bugs}
15263
15264 \end_inset
15265
15266
15267 \layout Standard
15268
15269 The recommended way of reporting bugs is using the infrastructure of the
15270  sourceforge site.
15271  You can follow the status of bug reports there and have an overview about
15272  the known bugs.
15273 \layout Standard
15274
15275 Bug reports are automatically forwarded to the developer mailing list and
15276  will be fixed ASAP.
15277  When reporting a bug, it is very useful to include a small test program
15278  (the smaller the better) which reproduces the problem.
15279  If you can isolate the problem by looking at the generated assembly code,
15280  this can be very helpful.
15281  Compiling your program with the -
15282 \begin_inset ERT
15283 status Collapsed
15284
15285 \layout Standard
15286
15287 \backslash
15288 /
15289 \end_inset
15290
15291 -dumpall
15292 \begin_inset LatexCommand \index{-\/-dumpall}
15293
15294 \end_inset
15295
15296  option can sometimes be useful in locating optimization problems.
15297  When reporting a bug please maker sure you:
15298 \layout Enumerate
15299
15300 Attach the code you are compiling with SDCC.
15301
15302 \layout Enumerate
15303
15304 Specify the exact command you use to run SDCC, or attach your Makefile.
15305
15306 \layout Enumerate
15307
15308 Specify the SDCC version (type "sdcc -v"), your platform, and operating
15309  system.
15310
15311 \layout Enumerate
15312
15313 Provide an exact copy of any error message or incorrect output.
15314
15315 \layout Enumerate
15316
15317 Put something meaningful in the subject of your message.
15318 \layout Standard
15319
15320 Please attempt to include these 5 important parts, as applicable, in all
15321  requests for support or when reporting any problems or bugs with SDCC.
15322  Though this will make your message lengthy, it will greatly improve your
15323  chance that SDCC users and developers will be able to help you.
15324  Some SDCC developers are frustrated by bug reports without code provided
15325  that they can use to reproduce and ultimately fix the problem, so please
15326  be sure to provide sample code if you are reporting a bug!
15327 \layout Standard
15328
15329 Please have a short check that you are using a recent version of SDCC and
15330  the bug is not yet known.
15331  This is the link for reporting bugs:
15332 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
15333
15334 \end_inset
15335
15336 .
15337 \layout Subsection
15338
15339 Requesting Features
15340 \begin_inset LatexCommand \index{Feature request}
15341
15342 \end_inset
15343
15344
15345 \begin_inset LatexCommand \index{Requesting features}
15346
15347 \end_inset
15348
15349
15350 \layout Standard
15351
15352 Like bug reports feature requests are forwarded to the developer mailing
15353  list.
15354  This is the link for requesting features:
15355 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
15356
15357 \end_inset
15358
15359 .
15360 \layout Subsection
15361
15362 Getting Help
15363 \layout Standard
15364
15365 These links should take you directly to the
15366 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
15367
15368 \end_inset
15369
15370
15371 \begin_inset Foot
15372 collapsed false
15373
15374 \layout Standard
15375
15376 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
15377  automated messages (mid 2003)
15378 \end_inset
15379
15380  and the
15381 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
15382
15383 \end_inset
15384
15385 , lists and forums are archived so if you are lucky someone already had
15386  a similar problem.
15387 \layout Subsection
15388
15389 ChangeLog
15390 \begin_inset LatexCommand \index{Changelog}
15391
15392 \end_inset
15393
15394
15395 \layout Standard
15396
15397 You can follow the status of the cvs version
15398 \begin_inset LatexCommand \index{version}
15399
15400 \end_inset
15401
15402  of SDCC by watching the file
15403 \begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
15404
15405 \end_inset
15406
15407  in the cvs-repository.
15408 \layout Subsection
15409
15410 Release policy
15411 \begin_inset LatexCommand \index{Release policy}
15412
15413 \end_inset
15414
15415
15416 \layout Standard
15417
15418 Historically there often were long delays between official releases and
15419  the sourceforge download area tends to get not updated at all.
15420  Current excuses might refer to problems with live range analysis, but if
15421  this is fixed, the next problem rising is that another excuse will have
15422  to be found.
15423  Kidding aside, we have to get better there! On the other hand there are
15424  daily snapshots available at
15425 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
15426
15427 \end_inset
15428
15429 , and you can always built the very last version (hopefully with many bugs
15430  fixed, and features added) from the source code available at
15431 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
15432
15433 \end_inset
15434
15435 .
15436 \layout Subsection
15437
15438 Examples
15439 \begin_inset LatexCommand \index{Examples}
15440
15441 \end_inset
15442
15443
15444 \layout Standard
15445
15446 You'll find some small examples in the directory sdcc/device/examples/
15447 \layout Comment
15448
15449 Maybe we should include some links to real world applications.
15450  Preferably pointer to pointers (one for each architecture) so this stays
15451  manageable here?
15452 \layout Subsection
15453
15454 Quality control
15455 \begin_inset LatexCommand \index{Quality control}
15456
15457 \end_inset
15458
15459
15460 \layout Standard
15461
15462 The compiler is passed through nightly compile and build checks.
15463  The so called
15464 \shape italic
15465 regression tests
15466 \shape default
15467
15468 \begin_inset LatexCommand \index{Regression test}
15469
15470 \end_inset
15471
15472  check that SDCC itself compiles flawlessly on several platforms and checks
15473  the quality of the code generated by SDCC by running the code through simulator
15474 s.
15475  There is a separate document
15476 \shape italic
15477 test_suite.pdf
15478 \begin_inset LatexCommand \index{Test suite}
15479
15480 \end_inset
15481
15482
15483 \shape default
15484  about this.
15485 \layout Standard
15486
15487 You'll find the test code in the directory
15488 \shape italic
15489 sdcc/support/regression
15490 \shape default
15491 .
15492  You can run these tests manually by running
15493 \family sans
15494 make
15495 \family default
15496  in this directory (or f.e.
15497
15498 \family sans
15499 make test-mcs51
15500 \family default
15501  if you don't want to run the complete tests).
15502  The test code might also be interesting if you want to look for examples
15503 \begin_inset LatexCommand \index{Examples}
15504
15505 \end_inset
15506
15507  checking corner cases of SDCC or if you plan to submit patches
15508 \begin_inset LatexCommand \index{Patch submission}
15509
15510 \end_inset
15511
15512 .
15513 \layout Standard
15514
15515 The pic port uses a different set of regression tests, you'll find them
15516  in the directory
15517 \shape italic
15518 sdcc/src/regression
15519 \shape default
15520 .
15521 \layout Section
15522 \pagebreak_top
15523 Compiler internals
15524 \begin_inset LatexCommand \index{Compiler internals}
15525
15526 \end_inset
15527
15528
15529 \layout Subsection
15530
15531 The anatomy of the compiler
15532 \layout Standard
15533
15534
15535 \shape italic
15536 This is an excerpt from an article published in Circuit Cellar Magazine
15537  in august 2000.
15538  It's a little outdated (the compiler is much more efficient now and user/develo
15539 per friendly), but pretty well exposes the guts of it all.
15540 \shape default
15541
15542 \newline
15543
15544 \newline
15545 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
15546  It is fairly easy to retarget for other 8-bit MCU.
15547  Here we take a look at some of the internals of the compiler.
15548
15549 \layout Paragraph*
15550
15551 Parsing
15552 \begin_inset LatexCommand \index{Parsing}
15553
15554 \end_inset
15555
15556
15557 \layout Standard
15558
15559 Parsing the input source file and creating an AST (Annotated Syntax Tree
15560 \begin_inset LatexCommand \index{Annotated syntax tree}
15561
15562 \end_inset
15563
15564 ).
15565  This phase also involves propagating types (annotating each node of the
15566  parse tree with type information) and semantic analysis.
15567  There are some MCU specific parsing rules.
15568  For example the storage classes, the extended storage classes are MCU specific
15569  while there may be a xdata storage class for 8051 there is no such storage
15570  class for z80 or Atmel AVR.
15571  SDCC allows MCU specific storage class extensions, i.e.
15572  xdata will be treated as a storage class specifier when parsing 8051 C
15573  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
15574  C code.
15575 \layout Paragraph*
15576
15577 Generating iCode
15578 \begin_inset LatexCommand \index{iCode}
15579
15580 \end_inset
15581
15582
15583 \layout Standard
15584
15585 Intermediate code generation.
15586  In this phase the AST is broken down into three-operand form (iCode).
15587  These three operand forms are represented as doubly linked lists.
15588  ICode is the term given to the intermediate form generated by the compiler.
15589  ICode example section shows some examples of iCode generated for some simple
15590  C source functions.
15591 \layout Paragraph*
15592
15593 Optimizations
15594 \begin_inset LatexCommand \index{Optimizations}
15595
15596 \end_inset
15597
15598 .
15599 \layout Standard
15600
15601 Bulk of the target independent optimizations is performed in this phase.
15602  The optimizations include constant propagation, common sub-expression eliminati
15603 on, loop invariant code movement, strength reduction of loop induction variables
15604  and dead-code elimination.
15605 \layout Paragraph*
15606
15607 Live range analysis
15608 \begin_inset LatexCommand \index{Live range analysis}
15609
15610 \end_inset
15611
15612
15613 \layout Standard
15614
15615 During intermediate code generation phase, the compiler assumes the target
15616  machine has infinite number of registers and generates a lot of temporary
15617  variables.
15618  The live range computation determines the lifetime of each of these compiler-ge
15619 nerated temporaries.
15620  A picture speaks a thousand words.
15621  ICode example sections show the live range annotations for each of the
15622  operand.
15623  It is important to note here, each iCode is assigned a number in the order
15624  of its execution in the function.
15625  The live ranges are computed in terms of these numbers.
15626  The from number is the number of the iCode which first defines the operand
15627  and the to number signifies the iCode which uses this operand last.
15628 \layout Paragraph*
15629
15630 Register Allocation
15631 \begin_inset LatexCommand \index{Register allocation}
15632
15633 \end_inset
15634
15635
15636 \layout Standard
15637
15638 The register allocation determines the type and number of registers needed
15639  by each operand.
15640  In most MCUs only a few registers can be used for indirect addressing.
15641  In case of 8051 for example the registers R0 & R1 can be used to indirectly
15642  address the internal ram and DPTR to indirectly address the external ram.
15643  The compiler will try to allocate the appropriate register to pointer variables
15644  if it can.
15645  ICode example section shows the operands annotated with the registers assigned
15646  to them.
15647  The compiler will try to keep operands in registers as much as possible;
15648  there are several schemes the compiler uses to do achieve this.
15649  When the compiler runs out of registers the compiler will check to see
15650  if there are any live operands which is not used or defined in the current
15651  basic block being processed, if there are any found then it will push that
15652  operand and use the registers in this block, the operand will then be popped
15653  at the end of the basic block.
15654
15655 \layout Standard
15656
15657 There are other MCU specific considerations in this phase.
15658  Some MCUs have an accumulator; very short-lived operands could be assigned
15659  to the accumulator instead of general-purpose register.
15660 \layout Paragraph*
15661
15662 Code generation
15663 \layout Standard
15664
15665 Figure II gives a table of iCode operations supported by the compiler.
15666  The code generation involves translating these operations into corresponding
15667  assembly code for the processor.
15668  This sounds overly simple but that is the essence of code generation.
15669  Some of the iCode operations are generated on a MCU specific manner for
15670  example, the z80 port does not use registers to pass parameters so the
15671  SEND and RECV iCode operations will not be generated, and it also does
15672  not support JUMPTABLES.
15673
15674 \newline
15675
15676 \series bold
15677 \shape italic
15678 \color red
15679 <Where is Figure II ?>
15680 \layout Paragraph*
15681
15682 ICode Example
15683 \begin_inset LatexCommand \index{iCode}
15684
15685 \end_inset
15686
15687
15688 \layout Standard
15689
15690 This section shows some details of iCode.
15691  The example C code does not do anything useful; it is used as an example
15692  to illustrate the intermediate code generated by the compiler.
15693 \layout Verse
15694
15695
15696 \family typewriter
15697 1.\SpecialChar ~
15698 xdata int * p;
15699 \newline
15700 2.\SpecialChar ~
15701 int gint;
15702 \newline
15703 3.\SpecialChar ~
15704 /* This function does nothing useful.
15705  It is used
15706 \newline
15707 4.\SpecialChar ~
15708 \SpecialChar ~
15709 \SpecialChar ~
15710 \SpecialChar ~
15711 for the purpose of explaining iCode */
15712 \newline
15713 5.\SpecialChar ~
15714 short function (data int *x)
15715 \newline
15716 6.\SpecialChar ~
15717 {
15718 \newline
15719 7.\SpecialChar ~
15720 \SpecialChar ~
15721 \SpecialChar ~
15722 short i=10; /* dead initialization eliminated */
15723 \newline
15724 8.\SpecialChar ~
15725 \SpecialChar ~
15726 \SpecialChar ~
15727 short sum=10; /* dead initialization eliminated */
15728 \newline
15729 9.\SpecialChar ~
15730 \SpecialChar ~
15731 \SpecialChar ~
15732 short mul;
15733 \newline
15734 10.\SpecialChar ~
15735 \SpecialChar ~
15736 int j ;
15737 \newline
15738 11.\SpecialChar ~
15739 \SpecialChar ~
15740 while (*x) *x++ = *p++;
15741 \newline
15742 12.\SpecialChar ~
15743 \SpecialChar ~
15744 \SpecialChar ~
15745 \SpecialChar ~
15746 sum = 0 ;
15747 \newline
15748 13.\SpecialChar ~
15749 \SpecialChar ~
15750 mul = 0;
15751 \newline
15752 14.\SpecialChar ~
15753 \SpecialChar ~
15754 /* compiler detects i,j to be induction variables */
15755 \newline
15756 15.\SpecialChar ~
15757 \SpecialChar ~
15758 for (i = 0, j = 10 ; i < 10 ; i++, j
15759 \family default
15760 -
15761 \begin_inset ERT
15762 status Collapsed
15763
15764 \layout Standard
15765
15766 \backslash
15767 /
15768 \end_inset
15769
15770 -
15771 \family typewriter
15772 ) {
15773 \newline
15774 16.\SpecialChar ~
15775 \SpecialChar ~
15776 \SpecialChar ~
15777 \SpecialChar ~
15778 sum += i;
15779 \newline
15780 17.\SpecialChar ~
15781 \SpecialChar ~
15782 \SpecialChar ~
15783 \SpecialChar ~
15784 mul += i * 3; /* this multiplication remains */
15785 \newline
15786 18.\SpecialChar ~
15787 \SpecialChar ~
15788 \SpecialChar ~
15789 \SpecialChar ~
15790 gint += j * 3;/* this multiplication changed to addition */
15791 \newline
15792 19.\SpecialChar ~
15793 \SpecialChar ~
15794 }
15795 \newline
15796 20.\SpecialChar ~
15797 \SpecialChar ~
15798 return sum+mul;
15799 \newline
15800 21.\SpecialChar ~
15801 }
15802 \layout Standard
15803
15804 In addition to the operands each iCode contains information about the filename
15805  and line it corresponds to in the source file.
15806  The first field in the listing should be interpreted as follows:
15807 \newline
15808
15809 \shape italic
15810 \size footnotesize
15811 Filename(linenumber: iCode Execution sequence number : ICode hash table
15812  key : loop depth of the iCode).
15813 \shape default
15814 \size default
15815
15816 \newline
15817 Then follows the human readable form of the ICode operation.
15818  Each operand of this triplet form can be of three basic types a) compiler
15819  generated temporary b) user defined variable c) a constant value.
15820  Note that local variables and parameters are replaced by compiler generated
15821  temporaries.
15822  Live ranges
15823 \begin_inset LatexCommand \index{Live range analysis}
15824
15825 \end_inset
15826
15827  are computed only for temporaries (i.e.
15828  live ranges are not computed for global variables).
15829  Registers
15830 \begin_inset LatexCommand \index{Register allocation}
15831
15832 \end_inset
15833
15834  are allocated for temporaries only.
15835  Operands are formatted in the following manner:
15836 \newline
15837
15838 \shape italic
15839 \size footnotesize
15840 Operand Name [lr live-from : live-to ] { type information } [ registers
15841  allocated ].
15842 \shape default
15843 \size default
15844
15845 \newline
15846 As mentioned earlier the live ranges are computed in terms of the execution
15847  sequence number of the iCodes, for example
15848 \newline
15849 the iTemp0 is live from (i.e.
15850  first defined in iCode with execution sequence number 3, and is last used
15851  in the iCode with sequence number 5).
15852  For induction variables such as iTemp21 the live range computation extends
15853  the lifetime from the start to the end of the loop.
15854 \newline
15855 The register allocator used the live range information to allocate registers,
15856  the same registers may be used for different temporaries if their live
15857  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
15858  iTemp17 since their live ranges do not overlap.
15859  In addition the allocator also takes into consideration the type and usage
15860  of a temporary, for example itemp6 is a pointer to near space and is used
15861  as to fetch data from (i.e.
15862  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
15863  Some short lived temporaries are allocated to special registers which have
15864  meaning to the code generator e.g.
15865  iTemp13 is allocated to a pseudo register CC which tells the back end that
15866  the temporary is used only for a conditional jump the code generation makes
15867  use of this information to optimize a compare and jump ICode.
15868 \newline
15869 There are several loop optimizations
15870 \begin_inset LatexCommand \index{Loop optimization}
15871
15872 \end_inset
15873
15874  performed by the compiler.
15875  It can detect induction variables iTemp21(i) and iTemp23(j).
15876  Also note the compiler does selective strength reduction
15877 \begin_inset LatexCommand \index{Strength reduction}
15878
15879 \end_inset
15880
15881 , i.e.
15882  the multiplication of an induction variable in line 18 (gint = j * 3) is
15883  changed to addition, a new temporary iTemp17 is allocated and assigned
15884  a initial value, a constant 3 is then added for each iteration of the loop.
15885  The compiler does not change the multiplication
15886 \begin_inset LatexCommand \index{Multiplication}
15887
15888 \end_inset
15889
15890  in line 17 however since the processor does support an 8 * 8 bit multiplication.
15891 \newline
15892 Note the dead code elimination
15893 \begin_inset LatexCommand \index{Dead-code elimination}
15894
15895 \end_inset
15896
15897  optimization eliminated the dead assignments in line 7 & 8 to I and sum
15898  respectively.
15899 \newline
15900
15901 \layout Standard
15902
15903
15904 \size footnotesize
15905 Sample.c (5:1:0:0) _entry($9) :
15906 \layout Standard
15907
15908
15909 \size footnotesize
15910 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
15911 \layout Standard
15912
15913
15914 \size footnotesize
15915 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
15916 \layout Standard
15917
15918
15919 \size footnotesize
15920 Sample.c(11:4:53:0) preHeaderLbl0($11) :
15921 \layout Standard
15922
15923
15924 \size footnotesize
15925 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
15926  * int}[r2]
15927 \layout Standard
15928
15929
15930 \size footnotesize
15931 Sample.c(11:6:5:1) _whilecontinue_0($1) :
15932 \layout Standard
15933
15934
15935 \size footnotesize
15936 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
15937  int}[r0]]
15938 \layout Standard
15939
15940
15941 \size footnotesize
15942 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
15943 \layout Standard
15944
15945
15946 \size footnotesize
15947 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
15948  * int}
15949 \layout Standard
15950
15951
15952 \size footnotesize
15953 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
15954  {short}
15955 \layout Standard
15956
15957
15958 \size footnotesize
15959 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
15960  * int}[DPTR]]
15961 \layout Standard
15962
15963
15964 \size footnotesize
15965 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
15966 }[r2 r3]
15967 \layout Standard
15968
15969
15970 \size footnotesize
15971 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
15972  * int}[r0] + 0x2 {short}
15973 \layout Standard
15974
15975
15976 \size footnotesize
15977 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
15978 \layout Standard
15979
15980
15981 \size footnotesize
15982 Sample.c(11:17:21:0)_whilebreak_0($3) :
15983 \layout Standard
15984
15985
15986 \size footnotesize
15987 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
15988 \layout Standard
15989
15990
15991 \size footnotesize
15992 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
15993 \layout Standard
15994
15995
15996 \size footnotesize
15997 Sample.c(15:20:54:0)preHeaderLbl1($13) :
15998 \layout Standard
15999
16000
16001 \size footnotesize
16002 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
16003 \layout Standard
16004
16005
16006 \size footnotesize
16007 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
16008 \layout Standard
16009
16010
16011 \size footnotesize
16012 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
16013 \layout Standard
16014
16015
16016 \size footnotesize
16017 Sample.c(15:24:26:1)_forcond_0($4) :
16018 \layout Standard
16019
16020
16021 \size footnotesize
16022 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
16023  < 0xa {short}
16024 \layout Standard
16025
16026
16027 \size footnotesize
16028 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
16029 \layout Standard
16030
16031
16032 \size footnotesize
16033 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
16034  + ITemp21 [lr21:38]{short}[r4]
16035 \layout Standard
16036
16037
16038 \size footnotesize
16039 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
16040  * 0x3 {short}
16041 \layout Standard
16042
16043
16044 \size footnotesize
16045 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
16046  + iTemp15 [lr29:30]{short}[r1]
16047 \layout Standard
16048
16049
16050 \size footnotesize
16051 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
16052  r0]- 0x3 {short}
16053 \layout Standard
16054
16055
16056 \size footnotesize
16057 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
16058 int}[r7 r0]
16059 \layout Standard
16060
16061
16062 \size footnotesize
16063 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
16064  + 0x1 {short}
16065 \layout Standard
16066
16067
16068 \size footnotesize
16069 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
16070  r6]- 0x1 {short}
16071 \layout Standard
16072
16073
16074 \size footnotesize
16075 Sample.c(19:38:47:1) goto _forcond_0($4)
16076 \layout Standard
16077
16078
16079 \size footnotesize
16080 Sample.c(19:39:48:0)_forbreak_0($7) :
16081 \layout Standard
16082
16083
16084 \size footnotesize
16085 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
16086  + ITemp11 [lr19:40]{short}[r3]
16087 \layout Standard
16088
16089
16090 \size footnotesize
16091 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
16092 \layout Standard
16093
16094
16095 \size footnotesize
16096 Sample.c(20:42:51:0)_return($8) :
16097 \layout Standard
16098
16099
16100 \size footnotesize
16101 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
16102 \size default
16103
16104 \newline
16105
16106 \newline
16107 Finally the code generated for this function:
16108 \newline
16109
16110 \layout Standard
16111
16112
16113 \size footnotesize
16114 .area DSEG (DATA)
16115 \layout Standard
16116
16117
16118 \size footnotesize
16119 _p::
16120 \layout Standard
16121
16122
16123 \size footnotesize
16124 \SpecialChar ~
16125 \SpecialChar ~
16126 .ds 2
16127 \layout Standard
16128
16129
16130 \size footnotesize
16131 _gint::
16132 \layout Standard
16133
16134
16135 \size footnotesize
16136 \SpecialChar ~
16137 \SpecialChar ~
16138 .ds 2
16139 \layout Standard
16140
16141
16142 \size footnotesize
16143 ; sample.c 5
16144 \layout Standard
16145
16146
16147 \size footnotesize
16148 ; ----------------------------------------------
16149 \layout Standard
16150
16151
16152 \size footnotesize
16153 ; function function
16154 \layout Standard
16155
16156
16157 \size footnotesize
16158 ; ----------------------------------------------
16159 \layout Standard
16160
16161
16162 \size footnotesize
16163 _function:
16164 \layout Standard
16165
16166
16167 \size footnotesize
16168 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
16169 \layout Standard
16170
16171
16172 \size footnotesize
16173 \SpecialChar ~
16174 \SpecialChar ~
16175 mov r2,dpl
16176 \layout Standard
16177
16178
16179 \size footnotesize
16180 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
16181 \layout Standard
16182
16183
16184 \size footnotesize
16185 \SpecialChar ~
16186 \SpecialChar ~
16187 mov ar0,r2
16188 \layout Standard
16189
16190
16191 \size footnotesize
16192 ;_whilecontinue_0($1) :
16193 \layout Standard
16194
16195
16196 \size footnotesize
16197 00101$:
16198 \layout Standard
16199
16200
16201 \size footnotesize
16202 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
16203 \layout Standard
16204
16205
16206 \size footnotesize
16207 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
16208 \layout Standard
16209
16210
16211 \size footnotesize
16212 \SpecialChar ~
16213 \SpecialChar ~
16214 mov ar2,@r0
16215 \layout Standard
16216
16217
16218 \size footnotesize
16219 \SpecialChar ~
16220 \SpecialChar ~
16221 inc r0
16222 \layout Standard
16223
16224
16225 \size footnotesize
16226 \SpecialChar ~
16227 \SpecialChar ~
16228 mov ar3,@r0
16229 \layout Standard
16230
16231
16232 \size footnotesize
16233 \SpecialChar ~
16234 \SpecialChar ~
16235 dec r0
16236 \layout Standard
16237
16238
16239 \size footnotesize
16240 \SpecialChar ~
16241 \SpecialChar ~
16242 mov a,r2
16243 \layout Standard
16244
16245
16246 \size footnotesize
16247 \SpecialChar ~
16248 \SpecialChar ~
16249 orl a,r3
16250 \layout Standard
16251
16252
16253 \size footnotesize
16254 \SpecialChar ~
16255 \SpecialChar ~
16256 jz 00103$
16257 \layout Standard
16258
16259
16260 \size footnotesize
16261 00114$:
16262 \layout Standard
16263
16264
16265 \size footnotesize
16266 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
16267 \layout Standard
16268
16269
16270 \size footnotesize
16271 \SpecialChar ~
16272 \SpecialChar ~
16273 mov dpl,_p
16274 \layout Standard
16275
16276
16277 \size footnotesize
16278 \SpecialChar ~
16279 \SpecialChar ~
16280 mov dph,(_p + 1)
16281 \layout Standard
16282
16283
16284 \size footnotesize
16285 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
16286 \layout Standard
16287
16288
16289 \size footnotesize
16290 \SpecialChar ~
16291 \SpecialChar ~
16292 mov a,#0x02
16293 \layout Standard
16294
16295
16296 \size footnotesize
16297 \SpecialChar ~
16298 \SpecialChar ~
16299 add a,_p
16300 \layout Standard
16301
16302
16303 \size footnotesize
16304 \SpecialChar ~
16305 \SpecialChar ~
16306 mov _p,a
16307 \layout Standard
16308
16309
16310 \size footnotesize
16311 \SpecialChar ~
16312 \SpecialChar ~
16313 clr a
16314 \layout Standard
16315
16316
16317 \size footnotesize
16318 \SpecialChar ~
16319 \SpecialChar ~
16320 addc a,(_p + 1)
16321 \layout Standard
16322
16323
16324 \size footnotesize
16325 \SpecialChar ~
16326 \SpecialChar ~
16327 mov (_p + 1),a
16328 \layout Standard
16329
16330
16331 \size footnotesize
16332 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
16333 \layout Standard
16334
16335
16336 \size footnotesize
16337 \SpecialChar ~
16338 \SpecialChar ~
16339 movx a,@dptr
16340 \layout Standard
16341
16342
16343 \size footnotesize
16344 \SpecialChar ~
16345 \SpecialChar ~
16346 mov r2,a
16347 \layout Standard
16348
16349
16350 \size footnotesize
16351 \SpecialChar ~
16352 \SpecialChar ~
16353 inc dptr
16354 \layout Standard
16355
16356
16357 \size footnotesize
16358 \SpecialChar ~
16359 \SpecialChar ~
16360 movx a,@dptr
16361 \layout Standard
16362
16363
16364 \size footnotesize
16365 \SpecialChar ~
16366 \SpecialChar ~
16367 mov r3,a
16368 \layout Standard
16369
16370
16371 \size footnotesize
16372 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
16373 \layout Standard
16374
16375
16376 \size footnotesize
16377 \SpecialChar ~
16378 \SpecialChar ~
16379 mov @r0,ar2
16380 \layout Standard
16381
16382
16383 \size footnotesize
16384 \SpecialChar ~
16385 \SpecialChar ~
16386 inc r0
16387 \layout Standard
16388
16389
16390 \size footnotesize
16391 \SpecialChar ~
16392 \SpecialChar ~
16393 mov @r0,ar3
16394 \layout Standard
16395
16396
16397 \size footnotesize
16398 ; iTemp6 [lr5:16]{_near * int}[r0] =
16399 \layout Standard
16400
16401
16402 \size footnotesize
16403 ; iTemp6 [lr5:16]{_near * int}[r0] +
16404 \layout Standard
16405
16406
16407 \size footnotesize
16408 ; 0x2 {short}
16409 \layout Standard
16410
16411
16412 \size footnotesize
16413 \SpecialChar ~
16414 \SpecialChar ~
16415 inc r0
16416 \layout Standard
16417
16418
16419 \size footnotesize
16420 ; goto _whilecontinue_0($1)
16421 \layout Standard
16422
16423
16424 \size footnotesize
16425 \SpecialChar ~
16426 \SpecialChar ~
16427 sjmp 00101$
16428 \layout Standard
16429
16430
16431 \size footnotesize
16432 ; _whilebreak_0($3) :
16433 \layout Standard
16434
16435
16436 \size footnotesize
16437 00103$:
16438 \layout Standard
16439
16440
16441 \size footnotesize
16442 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
16443 \layout Standard
16444
16445
16446 \size footnotesize
16447 \SpecialChar ~
16448 \SpecialChar ~
16449 mov r2,#0x00
16450 \layout Standard
16451
16452
16453 \size footnotesize
16454 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
16455 \layout Standard
16456
16457
16458 \size footnotesize
16459 \SpecialChar ~
16460 \SpecialChar ~
16461 mov r3,#0x00
16462 \layout Standard
16463
16464
16465 \size footnotesize
16466 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
16467 \layout Standard
16468
16469
16470 \size footnotesize
16471 \SpecialChar ~
16472 \SpecialChar ~
16473 mov r4,#0x00
16474 \layout Standard
16475
16476
16477 \size footnotesize
16478 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
16479 \layout Standard
16480
16481
16482 \size footnotesize
16483 \SpecialChar ~
16484 \SpecialChar ~
16485 mov r5,#0x0A
16486 \layout Standard
16487
16488
16489 \size footnotesize
16490 \SpecialChar ~
16491 \SpecialChar ~
16492 mov r6,#0x00
16493 \layout Standard
16494
16495
16496 \size footnotesize
16497 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
16498 \layout Standard
16499
16500
16501 \size footnotesize
16502 \SpecialChar ~
16503 \SpecialChar ~
16504 mov r7,#0x1E
16505 \layout Standard
16506
16507
16508 \size footnotesize
16509 \SpecialChar ~
16510 \SpecialChar ~
16511 mov r0,#0x00
16512 \layout Standard
16513
16514
16515 \size footnotesize
16516 ; _forcond_0($4) :
16517 \layout Standard
16518
16519
16520 \size footnotesize
16521 00104$:
16522 \layout Standard
16523
16524
16525 \size footnotesize
16526 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
16527 \layout Standard
16528
16529
16530 \size footnotesize
16531 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
16532 \layout Standard
16533
16534
16535 \size footnotesize
16536 \SpecialChar ~
16537 \SpecialChar ~
16538 clr c
16539 \layout Standard
16540
16541
16542 \size footnotesize
16543 \SpecialChar ~
16544 \SpecialChar ~
16545 mov a,r4
16546 \layout Standard
16547
16548
16549 \size footnotesize
16550 \SpecialChar ~
16551 \SpecialChar ~
16552 xrl a,#0x80
16553 \layout Standard
16554
16555
16556 \size footnotesize
16557 \SpecialChar ~
16558 \SpecialChar ~
16559 subb a,#0x8a
16560 \layout Standard
16561
16562
16563 \size footnotesize
16564 \SpecialChar ~
16565 \SpecialChar ~
16566 jnc 00107$
16567 \layout Standard
16568
16569
16570 \size footnotesize
16571 00115$:
16572 \layout Standard
16573
16574
16575 \size footnotesize
16576 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
16577 \layout Standard
16578
16579
16580 \size footnotesize
16581 ; iTemp21 [lr21:38]{short}[r4]
16582 \layout Standard
16583
16584
16585 \size footnotesize
16586 \SpecialChar ~
16587 \SpecialChar ~
16588 mov a,r4
16589 \layout Standard
16590
16591
16592 \size footnotesize
16593 \SpecialChar ~
16594 \SpecialChar ~
16595 add a,r2
16596 \layout Standard
16597
16598
16599 \size footnotesize
16600 \SpecialChar ~
16601 \SpecialChar ~
16602 mov r2,a
16603 \layout Standard
16604
16605
16606 \size footnotesize
16607 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
16608 \layout Standard
16609
16610
16611 \size footnotesize
16612 \SpecialChar ~
16613 \SpecialChar ~
16614 mov b,#0x03
16615 \layout Standard
16616
16617
16618 \size footnotesize
16619 \SpecialChar ~
16620 \SpecialChar ~
16621 mov a,r4
16622 \layout Standard
16623
16624
16625 \size footnotesize
16626 \SpecialChar ~
16627 \SpecialChar ~
16628 mul ab
16629 \layout Standard
16630
16631
16632 \size footnotesize
16633 \SpecialChar ~
16634 \SpecialChar ~
16635 mov r1,a
16636 \layout Standard
16637
16638
16639 \size footnotesize
16640 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
16641 \layout Standard
16642
16643
16644 \size footnotesize
16645 ; iTemp15 [lr29:30]{short}[r1]
16646 \layout Standard
16647
16648
16649 \size footnotesize
16650 \SpecialChar ~
16651 \SpecialChar ~
16652 add a,r3
16653 \layout Standard
16654
16655
16656 \size footnotesize
16657 \SpecialChar ~
16658 \SpecialChar ~
16659 mov r3,a
16660 \layout Standard
16661
16662
16663 \size footnotesize
16664 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
16665 \layout Standard
16666
16667
16668 \size footnotesize
16669 \SpecialChar ~
16670 \SpecialChar ~
16671 mov a,r7
16672 \layout Standard
16673
16674
16675 \size footnotesize
16676 \SpecialChar ~
16677 \SpecialChar ~
16678 add a,#0xfd
16679 \layout Standard
16680
16681
16682 \size footnotesize
16683 \SpecialChar ~
16684 \SpecialChar ~
16685 mov r7,a
16686 \layout Standard
16687
16688
16689 \size footnotesize
16690 \SpecialChar ~
16691 \SpecialChar ~
16692 mov a,r0
16693 \layout Standard
16694
16695
16696 \size footnotesize
16697 \SpecialChar ~
16698 \SpecialChar ~
16699 addc a,#0xff
16700 \layout Standard
16701
16702
16703 \size footnotesize
16704 \SpecialChar ~
16705 \SpecialChar ~
16706 mov r0,a
16707 \layout Standard
16708
16709
16710 \size footnotesize
16711 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
16712 \layout Standard
16713
16714
16715 \size footnotesize
16716 \SpecialChar ~
16717 \SpecialChar ~
16718 mov a,r7
16719 \layout Standard
16720
16721
16722 \size footnotesize
16723 \SpecialChar ~
16724 \SpecialChar ~
16725 add a,_gint
16726 \layout Standard
16727
16728
16729 \size footnotesize
16730 \SpecialChar ~
16731 \SpecialChar ~
16732 mov _gint,a
16733 \layout Standard
16734
16735
16736 \size footnotesize
16737 \SpecialChar ~
16738 \SpecialChar ~
16739 mov a,r0
16740 \layout Standard
16741
16742
16743 \size footnotesize
16744 \SpecialChar ~
16745 \SpecialChar ~
16746 addc a,(_gint + 1)
16747 \layout Standard
16748
16749
16750 \size footnotesize
16751 \SpecialChar ~
16752 \SpecialChar ~
16753 mov (_gint + 1),a
16754 \layout Standard
16755
16756
16757 \size footnotesize
16758 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
16759 \layout Standard
16760
16761
16762 \size footnotesize
16763 \SpecialChar ~
16764 \SpecialChar ~
16765 inc r4
16766 \layout Standard
16767
16768
16769 \size footnotesize
16770 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
16771 \layout Standard
16772
16773
16774 \size footnotesize
16775 \SpecialChar ~
16776 \SpecialChar ~
16777 dec r5
16778 \layout Standard
16779
16780
16781 \size footnotesize
16782 \SpecialChar ~
16783 \SpecialChar ~
16784 cjne r5,#0xff,00104$
16785 \layout Standard
16786
16787
16788 \size footnotesize
16789 \SpecialChar ~
16790 \SpecialChar ~
16791 dec r6
16792 \layout Standard
16793
16794
16795 \size footnotesize
16796 ; goto _forcond_0($4)
16797 \layout Standard
16798
16799
16800 \size footnotesize
16801 \SpecialChar ~
16802 \SpecialChar ~
16803 sjmp 00104$
16804 \layout Standard
16805
16806
16807 \size footnotesize
16808 ; _forbreak_0($7) :
16809 \layout Standard
16810
16811
16812 \size footnotesize
16813 00107$:
16814 \layout Standard
16815
16816
16817 \size footnotesize
16818 ; ret iTemp24 [lr40:41]{short}
16819 \layout Standard
16820
16821
16822 \size footnotesize
16823 \SpecialChar ~
16824 \SpecialChar ~
16825 mov a,r3
16826 \layout Standard
16827
16828
16829 \size footnotesize
16830 \SpecialChar ~
16831 \SpecialChar ~
16832 add a,r2
16833 \layout Standard
16834
16835
16836 \size footnotesize
16837 \SpecialChar ~
16838 \SpecialChar ~
16839 mov dpl,a
16840 \layout Standard
16841
16842
16843 \size footnotesize
16844 ; _return($8) :
16845 \layout Standard
16846
16847
16848 \size footnotesize
16849 00108$:
16850 \layout Standard
16851
16852
16853 \size footnotesize
16854 \SpecialChar ~
16855 \SpecialChar ~
16856 ret
16857 \newline
16858
16859 \layout Subsection
16860
16861 A few words about basic block successors, predecessors and dominators
16862 \layout Standard
16863
16864 Successors are basic blocks
16865 \begin_inset LatexCommand \index{Basic blocks}
16866
16867 \end_inset
16868
16869  that might execute after this basic block.
16870 \newline
16871 Predecessors are basic blocks that might execute before reaching this basic
16872  block.
16873 \newline
16874 Dominators are basic blocks that WILL execute before reaching this basic
16875  block.
16876 \newline
16877
16878 \layout Standard
16879
16880 [basic block 1]
16881 \layout Standard
16882
16883 if (something)
16884 \layout Standard
16885
16886 [basic block 2]
16887 \layout Standard
16888
16889 else
16890 \layout Standard
16891
16892 [basic block 3]
16893 \layout Standard
16894
16895 [basic block 4]
16896 \newline
16897
16898 \layout Standard
16899
16900 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
16901 \layout Standard
16902
16903 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
16904 \layout Standard
16905
16906 c) domVect of [BB4] = BB1 ...
16907  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
16908  was executed.
16909 \layout Section
16910
16911 Acknowledgments
16912 \layout Standard
16913
16914
16915 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
16916
16917 \end_inset
16918
16919
16920 \newline
16921
16922 \newline
16923
16924 \emph on
16925 Thanks to all the other volunteer developers who have helped with coding,
16926  testing, web-page creation, distribution sets, etc.
16927  You know who you are :-)
16928 \emph default
16929
16930 \newline
16931
16932 \layout Standard
16933
16934 This document was initially written by Sandeep Dutta
16935 \layout Standard
16936
16937 All product names mentioned herein may be trademarks
16938 \begin_inset LatexCommand \index{Trademarks}
16939
16940 \end_inset
16941
16942  of their respective companies.
16943
16944 \layout Section
16945
16946 Alphabetical index
16947 \layout Standard
16948
16949 To avoid confusion, the installation and building options for sdcc itself
16950  (chapter 2) are not part of the index.
16951 \layout Standard
16952
16953
16954 \begin_inset LatexCommand \printindex{}
16955
16956 \end_inset
16957
16958
16959 \the_end