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

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