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