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