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

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