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