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 Optimization Options
5202 \begin_inset LatexCommand \index{Options optimization}
5203
5204 \end_inset
5205
5206
5207 \begin_inset LatexCommand \index{Optimization 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 -nogcse
5228 \begin_inset LatexCommand \index{-\/-nogcse}
5229
5230 \end_inset
5231
5232
5233 \series default
5234  Will not do global subexpression elimination, this option may be used when
5235  the compiler creates undesirably large stack/data spaces to store compiler
5236  temporaries.
5237  A warning message will be generated when this happens and the compiler
5238  will indicate the number of extra bytes it allocated.
5239  It recommended that this option NOT be used, #pragma\SpecialChar ~
5240 NOGCSE
5241 \begin_inset LatexCommand \index{\#pragma NOGCSE}
5242
5243 \end_inset
5244
5245  can be used to turn off global subexpression elimination
5246 \begin_inset LatexCommand \index{Subexpression elimination}
5247
5248 \end_inset
5249
5250  for a given function only.
5251 \layout List
5252 \labelwidthstring 00.00.0000
5253
5254
5255 \series bold
5256 -
5257 \begin_inset ERT
5258 status Collapsed
5259
5260 \layout Standard
5261
5262 \backslash
5263 /
5264 \end_inset
5265
5266 -noinvariant
5267 \begin_inset LatexCommand \index{-\/-noinvariant}
5268
5269 \end_inset
5270
5271
5272 \series default
5273  Will not do loop invariant optimizations, this may be turned off for reasons
5274  explained for the previous option.
5275  For more details of loop optimizations performed see section Loop Invariants.It
5276  recommended that this option NOT be used, #pragma\SpecialChar ~
5277 NOINVARIANT
5278 \begin_inset LatexCommand \index{\#pragma NOINVARIANT}
5279
5280 \end_inset
5281
5282  can be used to turn off invariant optimizations for a given function only.
5283 \layout List
5284 \labelwidthstring 00.00.0000
5285
5286
5287 \series bold
5288 -
5289 \begin_inset ERT
5290 status Collapsed
5291
5292 \layout Standard
5293
5294 \backslash
5295 /
5296 \end_inset
5297
5298 -noinduction
5299 \begin_inset LatexCommand \index{-\/-noinduction}
5300
5301 \end_inset
5302
5303
5304 \series default
5305  Will not do loop induction optimizations, see section strength reduction
5306  for more details.It is recommended that this option is NOT used, #pragma\SpecialChar ~
5307 NOINDUCT
5308 ION
5309 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
5310
5311 \end_inset
5312
5313  can be used to turn off induction optimizations for a given function only.
5314 \layout List
5315 \labelwidthstring 00.00.0000
5316
5317
5318 \series bold
5319 -
5320 \begin_inset ERT
5321 status Collapsed
5322
5323 \layout Standard
5324
5325 \backslash
5326 /
5327 \end_inset
5328
5329 -nojtbound
5330 \begin_inset LatexCommand \index{-\/-nojtbound}
5331
5332 \end_inset
5333
5334
5335 \size large
5336 \bar under
5337
5338 \series default
5339 \size default
5340 \bar default
5341  Will not generate boundary condition check when switch statements
5342 \begin_inset LatexCommand \index{switch statement}
5343
5344 \end_inset
5345
5346  are implemented using jump-tables.
5347  See section Switch Statements for more details.
5348  It is recommended that this option is NOT used, #pragma\SpecialChar ~
5349 NOJTBOUND
5350 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
5351
5352 \end_inset
5353
5354  can be used to turn off boundary checking for jump tables for a given function
5355  only.
5356 \layout List
5357 \labelwidthstring 00.00.0000
5358
5359
5360 \series bold
5361 -
5362 \begin_inset ERT
5363 status Collapsed
5364
5365 \layout Standard
5366
5367 \backslash
5368 /
5369 \end_inset
5370
5371 -noloopreverse
5372 \begin_inset LatexCommand \index{-\/-noloopreverse}
5373
5374 \end_inset
5375
5376
5377 \series default
5378 \size large
5379
5380 \size default
5381 Will not do loop reversal
5382 \begin_inset LatexCommand \index{Loop reversing}
5383
5384 \end_inset
5385
5386 optimization.
5387 \layout List
5388 \labelwidthstring 00.00.0000
5389
5390 -
5391 \begin_inset ERT
5392 status Collapsed
5393
5394 \layout Standard
5395
5396 \backslash
5397 /
5398 \end_inset
5399
5400 -
5401 \series bold
5402 nolabelopt
5403 \series default
5404
5405 \begin_inset LatexCommand \index{-\/-nolabelopt }
5406
5407 \end_inset
5408
5409 Will not optimize labels (makes the dumpfiles more readable).
5410 \layout List
5411 \labelwidthstring 00.00.0000
5412
5413
5414 \series bold
5415 -
5416 \begin_inset ERT
5417 status Collapsed
5418
5419 \layout Standard
5420
5421 \backslash
5422 /
5423 \end_inset
5424
5425 -no-xinit-opt
5426 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
5427
5428 \end_inset
5429
5430
5431 \series default
5432  Will not memcpy initialized data in far space from code space.
5433  This saves a few bytes in code space if you don't have initialized data.
5434 \layout Subsubsection
5435
5436 Other Options
5437 \begin_inset LatexCommand \index{Options other}
5438
5439 \end_inset
5440
5441
5442 \layout List
5443 \labelwidthstring 00.00.0000
5444
5445
5446 \series bold
5447 -c\SpecialChar ~
5448 -
5449 \begin_inset ERT
5450 status Collapsed
5451
5452 \layout Standard
5453
5454 \backslash
5455 /
5456 \end_inset
5457
5458 -compile-only
5459 \begin_inset LatexCommand \index{-\/-compile-only}
5460
5461 \end_inset
5462
5463
5464 \begin_inset LatexCommand \index{-c -\/-compile-only}
5465
5466 \end_inset
5467
5468
5469 \series default
5470  will compile and assemble the source, but will not call the linkage editor.
5471 \layout List
5472 \labelwidthstring 00.00.0000
5473
5474
5475 \series bold
5476 -
5477 \series default
5478
5479 \begin_inset ERT
5480 status Collapsed
5481
5482 \layout Standard
5483
5484 \backslash
5485 /
5486 \end_inset
5487
5488
5489 \series bold
5490 -c1mode
5491 \begin_inset LatexCommand \index{-\/-c1mode}
5492
5493 \end_inset
5494
5495
5496 \series default
5497  reads the preprocessed source from standard input and compiles it.
5498  The file name for the assembler output must be specified using the -o option.
5499 \layout List
5500 \labelwidthstring 00.00.0000
5501
5502
5503 \series bold
5504 -E
5505 \begin_inset LatexCommand \index{-E}
5506
5507 \end_inset
5508
5509
5510 \series default
5511  Run only the C preprocessor.
5512  Preprocess all the C source files specified and output the results to standard
5513  output.
5514 \layout List
5515 \labelwidthstring 00.00.0000
5516
5517
5518 \series bold
5519 -o\SpecialChar ~
5520 <path/file>
5521 \begin_inset LatexCommand \index{-o <path/file>}
5522
5523 \end_inset
5524
5525
5526 \series default
5527 The output path resp.
5528  file where everything will be placed.
5529  If the parameter is a path, it must have a trailing slash (or backslash
5530  for the Windows binaries) to be recognized as a path.
5531
5532 \layout List
5533 \labelwidthstring 00.00.0000
5534
5535
5536 \series bold
5537 -
5538 \begin_inset ERT
5539 status Collapsed
5540
5541 \layout Standard
5542
5543 \backslash
5544 /
5545 \end_inset
5546
5547 -stack-auto
5548 \begin_inset LatexCommand \index{-\/-stack-auto}
5549
5550 \end_inset
5551
5552
5553 \series default
5554 \size large
5555 \emph on
5556
5557 \size default
5558 \emph default
5559 All functions in the source file will be compiled as
5560 \emph on
5561 reentrant
5562 \emph default
5563
5564 \begin_inset LatexCommand \index{reentrant}
5565
5566 \end_inset
5567
5568 , i.e.
5569  the parameters and local variables will be allocated on the stack
5570 \begin_inset LatexCommand \index{stack}
5571
5572 \end_inset
5573
5574 .
5575  see section Parameters and Local Variables for more details.
5576  If this option is used all source files in the project should be compiled
5577  with this option.
5578
5579 \layout List
5580 \labelwidthstring 00.00.0000
5581
5582
5583 \series bold
5584 -
5585 \begin_inset ERT
5586 status Collapsed
5587
5588 \layout Standard
5589
5590 \backslash
5591 /
5592 \end_inset
5593
5594 -xstack
5595 \begin_inset LatexCommand \index{-\/-xstack}
5596
5597 \end_inset
5598
5599
5600 \series default
5601  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5602  variables and passing parameters.
5603  See section on external stack for more details.
5604 \layout List
5605 \labelwidthstring 00.00.0000
5606
5607
5608 \series bold
5609 -
5610 \begin_inset ERT
5611 status Collapsed
5612
5613 \layout Standard
5614
5615 \backslash
5616 /
5617 \end_inset
5618
5619 -callee-saves
5620 \begin_inset LatexCommand \index{-\/-callee-saves}
5621
5622 \end_inset
5623
5624
5625 \begin_inset LatexCommand \index{function prologue}
5626
5627 \end_inset
5628
5629  function1[,function2][,function3]....
5630
5631 \series default
5632  The compiler by default uses a caller saves convention for register saving
5633  across function calls, however this can cause unnecessary register pushing
5634  & popping when calling small functions from larger functions.
5635  This option can be used to switch the register saving convention for the
5636  function names specified.
5637  The compiler will not save registers when calling these functions, no extra
5638  code will be generated at the entry & exit for these functions to save
5639  & restore the registers used by these functions, this can SUBSTANTIALLY
5640  reduce code & improve run time performance of the generated code.
5641  In the future the compiler (with inter procedural analysis) will be able
5642  to determine the appropriate scheme to use for each function call.
5643  DO NOT use this option for built-in functions such as _mulint..., if this
5644  option is used for a library function the appropriate library function
5645  needs to be recompiled with the same option.
5646  If the project consists of multiple source files then all the source file
5647  should be compiled with the same -
5648 \begin_inset ERT
5649 status Collapsed
5650
5651 \layout Standard
5652
5653 \backslash
5654 /
5655 \end_inset
5656
5657 -callee-saves option string.
5658  Also see #pragma\SpecialChar ~
5659 CALLEE-SAVES
5660 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
5661
5662 \end_inset
5663
5664 .
5665 \layout List
5666 \labelwidthstring 00.00.0000
5667
5668
5669 \series bold
5670 -
5671 \begin_inset ERT
5672 status Collapsed
5673
5674 \layout Standard
5675
5676 \backslash
5677 /
5678 \end_inset
5679
5680 -debug
5681 \begin_inset LatexCommand \index{-\/-debug}
5682
5683 \end_inset
5684
5685
5686 \bar under
5687
5688 \series default
5689 \bar default
5690 When this option is used the compiler will generate debug information, that
5691  can be used with the SDCDB.
5692  The debug information is collected in a file with .cdb extension.
5693  For more information see documentation for SDCDB.
5694 \layout List
5695 \labelwidthstring 00.00.0000
5696
5697
5698 \series bold
5699 -
5700 \begin_inset ERT
5701 status Collapsed
5702
5703 \layout Standard
5704
5705 \backslash
5706 /
5707 \end_inset
5708
5709 -peep-file
5710 \series default
5711
5712 \begin_inset LatexCommand \index{-\/-peep-file}
5713
5714 \end_inset
5715
5716 <filename> This option can be used to use additional rules to be used by
5717  the peep hole optimizer.
5718  See section Peep Hole optimizations for details on how to write these rules.
5719 \layout List
5720 \labelwidthstring 00.00.0000
5721
5722
5723 \series bold
5724 -S
5725 \begin_inset LatexCommand \index{-S}
5726
5727 \end_inset
5728
5729
5730 \size large
5731 \bar under
5732
5733 \series default
5734 \size default
5735 \bar default
5736 Stop after the stage of compilation proper; do not assemble.
5737  The output is an assembler code file for the input file specified.
5738 \layout List
5739 \labelwidthstring 00.00.0000
5740
5741
5742 \series bold
5743 -Wa_asmOption[,asmOption]
5744 \series default
5745
5746 \begin_inset LatexCommand \index{-Wa\_asmOption[,asmOption]}
5747
5748 \end_inset
5749
5750 ...
5751  Pass the asmOption to the assembler.
5752 \layout List
5753 \labelwidthstring 00.00.0000
5754
5755
5756 \series bold
5757 -Wl_linkOption[,linkOption]
5758 \series default
5759
5760 \begin_inset LatexCommand \index{-Wl\_linkOption[,linkOption]}
5761
5762 \end_inset
5763
5764 ...
5765  Pass the linkOption to the linker.
5766 \layout List
5767 \labelwidthstring 00.00.0000
5768
5769
5770 \series bold
5771 -
5772 \begin_inset ERT
5773 status Collapsed
5774
5775 \layout Standard
5776
5777 \backslash
5778 /
5779 \end_inset
5780
5781 -int-long-reent
5782 \begin_inset LatexCommand \index{-\/-int-long-reent}
5783
5784 \end_inset
5785
5786
5787 \series default
5788  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
5789  Note by default these libraries are compiled as non-reentrant.
5790  See section Installation for more details.
5791 \layout List
5792 \labelwidthstring 00.00.0000
5793
5794
5795 \series bold
5796 -
5797 \begin_inset ERT
5798 status Collapsed
5799
5800 \layout Standard
5801
5802 \backslash
5803 /
5804 \end_inset
5805
5806 -cyclomatic
5807 \begin_inset LatexCommand \index{-\/-cyclomatic}
5808
5809 \end_inset
5810
5811
5812 \bar under
5813
5814 \series default
5815 \bar default
5816 This option will cause the compiler to generate an information message for
5817  each function in the source file.
5818  The message contains some
5819 \emph on
5820 important
5821 \emph default
5822  information about the function.
5823  The number of edges and nodes the compiler detected in the control flow
5824  graph of the function, and most importantly the
5825 \emph on
5826 cyclomatic complexity
5827 \begin_inset LatexCommand \index{Cyclomatic complexity}
5828
5829 \end_inset
5830
5831
5832 \emph default
5833  see section on Cyclomatic Complexity for more details.
5834 \layout List
5835 \labelwidthstring 00.00.0000
5836
5837
5838 \series bold
5839 -
5840 \begin_inset ERT
5841 status Collapsed
5842
5843 \layout Standard
5844
5845 \backslash
5846 /
5847 \end_inset
5848
5849 -float-reent
5850 \begin_inset LatexCommand \index{-\/-float-reent}
5851
5852 \end_inset
5853
5854
5855 \bar under
5856
5857 \series default
5858 \bar default
5859  Floating point library is compiled as reentrant
5860 \begin_inset LatexCommand \index{reentrant}
5861
5862 \end_inset
5863
5864 .See section Installation for more details.
5865 \layout List
5866 \labelwidthstring 00.00.0000
5867
5868
5869 \series bold
5870 -
5871 \begin_inset ERT
5872 status Collapsed
5873
5874 \layout Standard
5875
5876 \backslash
5877 /
5878 \end_inset
5879
5880 -nooverlay
5881 \begin_inset LatexCommand \index{-\/-nooverlay}
5882
5883 \end_inset
5884
5885
5886 \series default
5887   The compiler will not overlay parameters and local variables of any function,
5888  see section Parameters and local variables for more details.
5889 \layout List
5890 \labelwidthstring 00.00.0000
5891
5892
5893 \series bold
5894 -
5895 \begin_inset ERT
5896 status Collapsed
5897
5898 \layout Standard
5899
5900 \backslash
5901 /
5902 \end_inset
5903
5904 -main-return
5905 \begin_inset LatexCommand \index{-\/-main-return}
5906
5907 \end_inset
5908
5909
5910 \series default
5911  This option can be used when the code generated is called by a monitor
5912  program.
5913  The compiler will generate a 'ret' upon return from the 'main'
5914 \begin_inset LatexCommand \index{main return}
5915
5916 \end_inset
5917
5918  function.
5919  The default option is to lock up i.e.
5920  generate a 'ljmp '.
5921 \layout List
5922 \labelwidthstring 00.00.0000
5923
5924
5925 \series bold
5926 -
5927 \begin_inset ERT
5928 status Collapsed
5929
5930 \layout Standard
5931
5932 \backslash
5933 /
5934 \end_inset
5935
5936 -no-peep
5937 \begin_inset LatexCommand \index{-\/-no-peep}
5938
5939 \end_inset
5940
5941
5942 \series default
5943   Disable peep-hole optimization.
5944 \layout List
5945 \labelwidthstring 00.00.0000
5946
5947
5948 \series bold
5949 -
5950 \begin_inset ERT
5951 status Collapsed
5952
5953 \layout Standard
5954
5955 \backslash
5956 /
5957 \end_inset
5958
5959 -peep-asm
5960 \begin_inset LatexCommand \index{-\/-peep-asm}
5961
5962 \end_inset
5963
5964
5965 \series default
5966   Pass the inline assembler code through the peep hole optimizer.
5967  This can cause unexpected changes to inline assembler code, please go through
5968  the peephole optimizer
5969 \begin_inset LatexCommand \index{Peephole optimizer}
5970
5971 \end_inset
5972
5973  rules defined in the source file tree '<target>/peeph.def' before using
5974  this option.
5975 \layout List
5976 \labelwidthstring 00.00.0000
5977
5978
5979 \series bold
5980 -
5981 \begin_inset ERT
5982 status Collapsed
5983
5984 \layout Standard
5985
5986 \backslash
5987 /
5988 \end_inset
5989
5990 -iram-size
5991 \series default
5992 <Value>
5993 \begin_inset LatexCommand \index{-\/-iram-size<Value>}
5994
5995 \end_inset
5996
5997  Causes the linker to check if the internal ram usage is within limits of
5998  the given value.
5999 \layout List
6000 \labelwidthstring 00.00.0000
6001
6002
6003 \series bold
6004 -
6005 \begin_inset ERT
6006 status Collapsed
6007
6008 \layout Standard
6009
6010 \backslash
6011 /
6012 \end_inset
6013
6014 -xram-size
6015 \series default
6016 <Value>
6017 \begin_inset LatexCommand \index{-\/-xram-size<Value>}
6018
6019 \end_inset
6020
6021  Causes the linker to check if the external ram usage is within limits of
6022  the given value.
6023 \layout List
6024 \labelwidthstring 00.00.0000
6025
6026
6027 \series bold
6028 -
6029 \begin_inset ERT
6030 status Collapsed
6031
6032 \layout Standard
6033
6034 \backslash
6035 /
6036 \end_inset
6037
6038 -code-size
6039 \series default
6040 <Value>
6041 \begin_inset LatexCommand \index{-\/-code-size<Value>}
6042
6043 \end_inset
6044
6045  Causes the linker to check if the code usage is within limits of the given
6046  value.
6047 \layout List
6048 \labelwidthstring 00.00.0000
6049
6050
6051 \series bold
6052 -
6053 \begin_inset ERT
6054 status Collapsed
6055
6056 \layout Standard
6057
6058 \backslash
6059 /
6060 \end_inset
6061
6062 -nostdincl
6063 \begin_inset LatexCommand \index{-\/-nostdincl}
6064
6065 \end_inset
6066
6067
6068 \series default
6069  This will prevent the compiler from passing on the default include path
6070  to the preprocessor.
6071 \layout List
6072 \labelwidthstring 00.00.0000
6073
6074
6075 \series bold
6076 -
6077 \begin_inset ERT
6078 status Collapsed
6079
6080 \layout Standard
6081
6082 \backslash
6083 /
6084 \end_inset
6085
6086 -nostdlib
6087 \begin_inset LatexCommand \index{-\/-nostdlib}
6088
6089 \end_inset
6090
6091
6092 \series default
6093  This will prevent the compiler from passing on the default library
6094 \begin_inset LatexCommand \index{Libraries}
6095
6096 \end_inset
6097
6098  path to the linker.
6099 \layout List
6100 \labelwidthstring 00.00.0000
6101
6102
6103 \series bold
6104 -
6105 \begin_inset ERT
6106 status Collapsed
6107
6108 \layout Standard
6109
6110 \backslash
6111 /
6112 \end_inset
6113
6114 -verbose
6115 \begin_inset LatexCommand \index{-\/-verbose}
6116
6117 \end_inset
6118
6119
6120 \series default
6121  Shows the various actions the compiler is performing.
6122 \layout List
6123 \labelwidthstring 00.00.0000
6124
6125
6126 \series bold
6127 -V
6128 \begin_inset LatexCommand \index{-V}
6129
6130 \end_inset
6131
6132
6133 \series default
6134  Shows the actual commands the compiler is executing.
6135 \layout List
6136 \labelwidthstring 00.00.0000
6137
6138
6139 \series bold
6140 -
6141 \begin_inset ERT
6142 status Collapsed
6143
6144 \layout Standard
6145
6146 \backslash
6147 /
6148 \end_inset
6149
6150 -no-c-code-in-asm
6151 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
6152
6153 \end_inset
6154
6155
6156 \series default
6157  Hides your ugly and inefficient c-code from the asm file, so you can always
6158  blame the compiler :).
6159 \layout List
6160 \labelwidthstring 00.00.0000
6161
6162
6163 \series bold
6164 -
6165 \begin_inset ERT
6166 status Collapsed
6167
6168 \layout Standard
6169
6170 \backslash
6171 /
6172 \end_inset
6173
6174 -i-code-in-asm
6175 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
6176
6177 \end_inset
6178
6179
6180 \series default
6181  Include i-codes in the asm file.
6182  Sounds like noise but is most helpful for debugging the compiler itself.
6183 \layout List
6184 \labelwidthstring 00.00.0000
6185
6186
6187 \series bold
6188 -
6189 \begin_inset ERT
6190 status Collapsed
6191
6192 \layout Standard
6193
6194 \backslash
6195 /
6196 \end_inset
6197
6198 -less-pedantic
6199 \begin_inset LatexCommand \index{-\/-less-pedantic}
6200
6201 \end_inset
6202
6203
6204 \series default
6205  Disable some of the more pedantic warnings (jwk burps: please be more specific
6206  here, please!)
6207 \layout List
6208 \labelwidthstring 00.00.0000
6209
6210
6211 \series bold
6212 -
6213 \begin_inset ERT
6214 status Collapsed
6215
6216 \layout Standard
6217
6218 \backslash
6219 /
6220 \end_inset
6221
6222 -print-search-dirs
6223 \begin_inset LatexCommand \index{-\/-print-search-dirs}
6224
6225 \end_inset
6226
6227
6228 \series default
6229  Display the directories in the compiler's search path
6230 \layout List
6231 \labelwidthstring 00.00.0000
6232
6233
6234 \series bold
6235 -
6236 \begin_inset ERT
6237 status Collapsed
6238
6239 \layout Standard
6240
6241 \backslash
6242 /
6243 \end_inset
6244
6245 -vc
6246 \begin_inset LatexCommand \index{-\/-vc}
6247
6248 \end_inset
6249
6250
6251 \series default
6252  Display errors and warnings using MSVC style, so you can use SDCC with
6253  visual studio
6254 \layout List
6255 \labelwidthstring 00.00.0000
6256
6257
6258 \series bold
6259 -
6260 \begin_inset ERT
6261 status Collapsed
6262
6263 \layout Standard
6264
6265 \backslash
6266 /
6267 \end_inset
6268
6269 -use-stderr
6270 \begin_inset LatexCommand \index{-\/-use-stdout}
6271
6272 \end_inset
6273
6274
6275 \series default
6276  Send errors and warnings to stdout instead of stderr
6277 \layout Subsubsection
6278
6279 Intermediate Dump Options
6280 \begin_inset LatexCommand \index{Options intermediate dump}
6281
6282 \end_inset
6283
6284
6285 \begin_inset LatexCommand \index{Intermediate dump options}
6286
6287 \end_inset
6288
6289
6290 \layout Standard
6291
6292 The following options are provided for the purpose of retargetting and debugging
6293  the compiler.
6294  These provided a means to dump the intermediate code (iCode
6295 \begin_inset LatexCommand \index{iCode}
6296
6297 \end_inset
6298
6299 ) generated by the compiler in human readable form at various stages of
6300  the compilation process.
6301
6302 \layout List
6303 \labelwidthstring 00.00.0000
6304
6305
6306 \series bold
6307 -
6308 \begin_inset ERT
6309 status Collapsed
6310
6311 \layout Standard
6312
6313 \backslash
6314 /
6315 \end_inset
6316
6317 -dumpraw
6318 \begin_inset LatexCommand \index{-\/-dumpraw}
6319
6320 \end_inset
6321
6322
6323 \series default
6324  This option will cause the compiler to dump the intermediate code into
6325  a file of named
6326 \emph on
6327 <source filename>.dumpraw
6328 \emph default
6329  just after the intermediate code has been generated for a function, i.e.
6330  before any optimizations are done.
6331  The basic blocks
6332 \begin_inset LatexCommand \index{Basic blocks}
6333
6334 \end_inset
6335
6336  at this stage ordered in the depth first number, so they may not be in
6337  sequence of execution.
6338 \layout List
6339 \labelwidthstring 00.00.0000
6340
6341
6342 \series bold
6343 -
6344 \begin_inset ERT
6345 status Collapsed
6346
6347 \layout Standard
6348
6349 \backslash
6350 /
6351 \end_inset
6352
6353 -dumpgcse
6354 \begin_inset LatexCommand \index{-\/-dumpgcse}
6355
6356 \end_inset
6357
6358
6359 \series default
6360  Will create a dump of iCode's, after global subexpression elimination
6361 \begin_inset LatexCommand \index{Global subexpression elimination}
6362
6363 \end_inset
6364
6365 , into a file named
6366 \emph on
6367 <source filename>.dumpgcse.
6368 \layout List
6369 \labelwidthstring 00.00.0000
6370
6371
6372 \series bold
6373 -
6374 \begin_inset ERT
6375 status Collapsed
6376
6377 \layout Standard
6378
6379 \backslash
6380 /
6381 \end_inset
6382
6383 -dumpdeadcode
6384 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
6385
6386 \end_inset
6387
6388
6389 \series default
6390  Will create a dump of iCode's, after deadcode elimination
6391 \begin_inset LatexCommand \index{Dead-code elimination}
6392
6393 \end_inset
6394
6395 , into a file named
6396 \emph on
6397 <source filename>.dumpdeadcode.
6398 \layout List
6399 \labelwidthstring 00.00.0000
6400
6401
6402 \series bold
6403 -
6404 \begin_inset ERT
6405 status Collapsed
6406
6407 \layout Standard
6408
6409 \backslash
6410 /
6411 \end_inset
6412
6413 -dumploop
6414 \begin_inset LatexCommand \index{-\/-dumploop}
6415
6416 \end_inset
6417
6418
6419 \series default
6420 \size large
6421
6422 \size default
6423 Will create a dump of iCode's, after loop optimizations
6424 \begin_inset LatexCommand \index{Loop optimization}
6425
6426 \end_inset
6427
6428 , into a file named
6429 \emph on
6430 <source filename>.dumploop.
6431 \layout List
6432 \labelwidthstring 00.00.0000
6433
6434
6435 \series bold
6436 -
6437 \begin_inset ERT
6438 status Collapsed
6439
6440 \layout Standard
6441
6442 \backslash
6443 /
6444 \end_inset
6445
6446 -dumprange
6447 \begin_inset LatexCommand \index{-\/-dumprange}
6448
6449 \end_inset
6450
6451
6452 \series default
6453 \size large
6454
6455 \size default
6456 Will create a dump of iCode's, after live range analysis
6457 \begin_inset LatexCommand \index{Live range analysis}
6458
6459 \end_inset
6460
6461 , into a file named
6462 \emph on
6463 <source filename>.dumprange.
6464 \layout List
6465 \labelwidthstring 00.00.0000
6466
6467
6468 \series bold
6469 -
6470 \begin_inset ERT
6471 status Collapsed
6472
6473 \layout Standard
6474
6475 \backslash
6476 /
6477 \end_inset
6478
6479 -dumlrange
6480 \begin_inset LatexCommand \index{-\/-dumlrange}
6481
6482 \end_inset
6483
6484
6485 \series default
6486  Will dump the life ranges
6487 \begin_inset LatexCommand \index{Live range analysis}
6488
6489 \end_inset
6490
6491  for all symbols.
6492 \layout List
6493 \labelwidthstring 00.00.0000
6494
6495
6496 \series bold
6497 -
6498 \begin_inset ERT
6499 status Collapsed
6500
6501 \layout Standard
6502
6503 \backslash
6504 /
6505 \end_inset
6506
6507 -dumpregassign
6508 \begin_inset LatexCommand \index{-\/-dumpregassign}
6509
6510 \end_inset
6511
6512
6513 \bar under
6514
6515 \series default
6516 \bar default
6517 Will create a dump of iCode's, after register assignment
6518 \begin_inset LatexCommand \index{Register assignment}
6519
6520 \end_inset
6521
6522 , into a file named
6523 \emph on
6524 <source filename>.dumprassgn.
6525 \layout List
6526 \labelwidthstring 00.00.0000
6527
6528
6529 \series bold
6530 -
6531 \begin_inset ERT
6532 status Collapsed
6533
6534 \layout Standard
6535
6536 \backslash
6537 /
6538 \end_inset
6539
6540 -dumplrange
6541 \begin_inset LatexCommand \index{-\/-dumplrange}
6542
6543 \end_inset
6544
6545
6546 \series default
6547  Will create a dump of the live ranges of iTemp's
6548 \layout List
6549 \labelwidthstring 00.00.0000
6550
6551
6552 \series bold
6553 -
6554 \begin_inset ERT
6555 status Collapsed
6556
6557 \layout Standard
6558
6559 \backslash
6560 /
6561 \end_inset
6562
6563 -dumpall
6564 \begin_inset LatexCommand \index{-\/-dumpall}
6565
6566 \end_inset
6567
6568
6569 \size large
6570 \bar under
6571
6572 \series default
6573 \size default
6574 \bar default
6575 Will cause all the above mentioned dumps to be created.
6576 \layout Subsection
6577
6578 Environment variables
6579 \begin_inset LatexCommand \index{Environment variables}
6580
6581 \end_inset
6582
6583
6584 \layout Standard
6585
6586 SDCC recognizes the following environment variables:
6587 \layout List
6588 \labelwidthstring 00.00.0000
6589
6590
6591 \series bold
6592 SDCC_LEAVE_SIGNALS
6593 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
6594
6595 \end_inset
6596
6597
6598 \series default
6599  SDCC installs a signal handler
6600 \begin_inset LatexCommand \index{signal handler}
6601
6602 \end_inset
6603
6604  to be able to delete temporary files after an user break (^C) or an exception.
6605  If this environment variable is set, SDCC won't install the signal handler
6606  in order to be able to debug SDCC.
6607 \layout List
6608 \labelwidthstring 00.00.0000
6609
6610
6611 \series bold
6612 TMP
6613 \begin_inset LatexCommand \index{TMP}
6614
6615 \end_inset
6616
6617 ,\SpecialChar ~
6618 TEMP
6619 \begin_inset LatexCommand \index{TEMP}
6620
6621 \end_inset
6622
6623 ,\SpecialChar ~
6624 TMPDIR
6625 \begin_inset LatexCommand \index{TMPDIR}
6626
6627 \end_inset
6628
6629
6630 \series default
6631  Path, where temporary files will be created.
6632  The order of the variables is the search order.
6633  In a standard *nix environment these variables are not set, and there's
6634  no need to set them.
6635  On Windows it's recommended to set one of them.
6636 \layout List
6637 \labelwidthstring 00.00.0000
6638
6639
6640 \series bold
6641 SDCC_HOME
6642 \begin_inset LatexCommand \index{SDCC\_HOME}
6643
6644 \end_inset
6645
6646
6647 \series default
6648  Path, see
6649 \begin_inset Quotes sld
6650 \end_inset
6651
6652 2.3 Install and search paths
6653 \begin_inset Quotes srd
6654 \end_inset
6655
6656 .
6657 \layout List
6658 \labelwidthstring 00.00.0000
6659
6660
6661 \series bold
6662 SDCC_INCLUDE
6663 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
6664
6665 \end_inset
6666
6667
6668 \series default
6669  Path, see
6670 \begin_inset Quotes sld
6671 \end_inset
6672
6673 2.3 Install and search paths
6674 \begin_inset Quotes srd
6675 \end_inset
6676
6677 .
6678 \layout List
6679 \labelwidthstring 00.00.0000
6680
6681
6682 \series bold
6683 SDCC_LIB
6684 \begin_inset LatexCommand \index{SDCC\_LIB}
6685
6686 \end_inset
6687
6688
6689 \series default
6690  Path, see
6691 \begin_inset Quotes sld
6692 \end_inset
6693
6694 2.3 Install and search paths
6695 \begin_inset Quotes srd
6696 \end_inset
6697
6698 .
6699 \layout Standard
6700
6701 There are some more environment variables recognized by SDCC, but these
6702  are solely used for debugging purposes.
6703  They can change or disappear very quickly, and will never be documented.
6704 \layout Subsection
6705
6706 MCS51/DS390 Storage Class
6707 \begin_inset LatexCommand \index{Storage class}
6708
6709 \end_inset
6710
6711  Language Extensions
6712 \layout Standard
6713
6714 In addition to the ANSI storage classes SDCC allows the following MCS51
6715  specific storage classes.
6716 \layout Subsubsection
6717
6718 xdata
6719 \begin_inset LatexCommand \index{xdata}
6720
6721 \end_inset
6722
6723
6724 \layout Standard
6725
6726 Variables declared with this storage class will be placed in the extern
6727  RAM.
6728  This is the
6729 \series bold
6730 default
6731 \series default
6732  storage class for Large Memory model, e.g.:
6733 \layout Verse
6734
6735
6736 \family typewriter
6737 xdata unsigned char xduc;
6738 \layout Subsubsection
6739
6740 data
6741 \begin_inset LatexCommand \index{data}
6742
6743 \end_inset
6744
6745
6746 \layout Standard
6747
6748 This is the
6749 \series bold
6750 default
6751 \series default
6752  storage class for Small Memory model.
6753  Variables declared with this storage class will be allocated in the internal
6754  RAM, e.g.:
6755 \layout Verse
6756
6757
6758 \family typewriter
6759 data int iramdata;
6760 \layout Subsubsection
6761
6762 idata
6763 \begin_inset LatexCommand \index{idata}
6764
6765 \end_inset
6766
6767
6768 \layout Standard
6769
6770 Variables declared with this storage class will be allocated into the indirectly
6771  addressable portion of the internal ram of a 8051, e.g.:
6772 \layout Verse
6773
6774
6775 \family typewriter
6776 idata int idi;
6777 \layout Subsubsection
6778
6779 bit
6780 \begin_inset LatexCommand \index{bit}
6781
6782 \end_inset
6783
6784
6785 \layout Standard
6786
6787 This is a data-type and a storage class specifier.
6788  When a variable is declared as a bit, it is allocated into the bit addressable
6789  memory of 8051, e.g.:
6790 \layout Verse
6791
6792
6793 \family typewriter
6794 bit iFlag;
6795 \layout Subsubsection
6796
6797 sfr
6798 \begin_inset LatexCommand \index{sfr}
6799
6800 \end_inset
6801
6802  / sbit
6803 \begin_inset LatexCommand \index{sbit}
6804
6805 \end_inset
6806
6807
6808 \layout Standard
6809
6810 Like the bit keyword,
6811 \emph on
6812 sfr / sbit
6813 \emph default
6814 signifies both a data-type and storage class, they are used to describe
6815  the special function registers and special bit variables of a 8051, eg:
6816 \layout Verse
6817
6818
6819 \family typewriter
6820 sfr at 0x80 P0; /* special function register P0 at location 0x80 */
6821 \newline
6822 sbit at 0xd7 CY; /* CY (Carry Flag
6823 \begin_inset LatexCommand \index{Flags}
6824
6825 \end_inset
6826
6827
6828 \begin_inset LatexCommand \index{Carry flag}
6829
6830 \end_inset
6831
6832 ) */
6833 \layout Subsection
6834
6835 Pointers
6836 \begin_inset LatexCommand \index{Pointers}
6837
6838 \end_inset
6839
6840
6841 \layout Standard
6842
6843 SDCC allows (via language extensions) pointers to explicitly point to any
6844  of the memory spaces
6845 \begin_inset LatexCommand \index{Memory model}
6846
6847 \end_inset
6848
6849  of the 8051.
6850  In addition to the explicit pointers, the compiler uses (by default) generic
6851  pointers which can be used to point to any of the memory spaces.
6852 \newline
6853
6854 \newline
6855 Pointer declaration examples:
6856 \layout Verse
6857
6858
6859 \family typewriter
6860 /* pointer physically in xternal ram pointing to object in internal ram
6861  */
6862 \newline
6863 data unsigned char * xdata p;
6864 \newline
6865
6866 \newline
6867 /* pointer physically in code rom pointing to data in xdata space */
6868 \newline
6869 xdata unsigned char * code p;
6870 \newline
6871
6872 \newline
6873 /* pointer physically in code space pointing to data in code space */
6874 \newline
6875 code unsigned char * code p;
6876 \newline
6877
6878 \newline
6879 /* the following is a generic pointer physically located in xdata space
6880  */
6881 \newline
6882 char * xdata p;
6883 \layout Standard
6884
6885 Well you get the idea.
6886
6887 \newline
6888
6889 \newline
6890 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
6891 \emph on
6892 generic
6893 \emph default
6894  pointers.
6895
6896 \size small
6897
6898 \newline
6899
6900 \newline
6901
6902 \size default
6903 The highest order byte of the
6904 \emph on
6905 generic
6906 \emph default
6907  pointers contains the data space information.
6908  Assembler support routines are called whenever data is stored or retrieved
6909  using
6910 \emph on
6911 generic
6912 \emph default
6913  pointers.
6914  These are useful for developing reusable library
6915 \begin_inset LatexCommand \index{Libraries}
6916
6917 \end_inset
6918
6919  routines.
6920  Explicitly specifying the pointer type will generate the most efficient
6921  code.
6922 \layout Subsection
6923
6924 Parameters
6925 \begin_inset LatexCommand \index{Parameters}
6926
6927 \end_inset
6928
6929  & Local Variables
6930 \begin_inset LatexCommand \index{Local variable}
6931
6932 \end_inset
6933
6934
6935 \layout Standard
6936
6937 Automatic (local) variables and parameters to functions can either be placed
6938  on the stack or in data-space.
6939  The default action of the compiler is to place these variables in the internal
6940  RAM (for small model) or external RAM (for large model).
6941  This in fact makes them
6942 \emph on
6943 static
6944 \begin_inset LatexCommand \index{static}
6945
6946 \end_inset
6947
6948
6949 \emph default
6950  so by default functions are non-reentrant
6951 \begin_inset LatexCommand \index{reentrant}
6952
6953 \end_inset
6954
6955 .
6956 \newline
6957
6958 \newline
6959 They can be placed on the stack
6960 \begin_inset LatexCommand \index{stack}
6961
6962 \end_inset
6963
6964  either by using the
6965 \emph on
6966  -
6967 \begin_inset ERT
6968 status Collapsed
6969
6970 \layout Standard
6971
6972 \backslash
6973 /
6974 \end_inset
6975
6976 -stack-auto
6977 \begin_inset LatexCommand \index{-\/-stack-auto}
6978
6979 \end_inset
6980
6981
6982 \emph default
6983  option or by using the
6984 \emph on
6985 reentrant
6986 \begin_inset LatexCommand \index{reentrant}
6987
6988 \end_inset
6989
6990
6991 \emph default
6992  keyword in the function declaration, e.g.:
6993 \layout Verse
6994
6995
6996 \family typewriter
6997 unsigned char foo(char i) reentrant
6998 \newline
6999 {
7000 \newline
7001 ...
7002
7003 \newline
7004 }
7005 \layout Standard
7006
7007 Since stack space on 8051 is limited, the
7008 \emph on
7009 reentrant
7010 \emph default
7011 keyword or the
7012 \emph on
7013  -
7014 \begin_inset ERT
7015 status Collapsed
7016
7017 \layout Standard
7018
7019 \backslash
7020 /
7021 \end_inset
7022
7023 -stack-auto
7024 \emph default
7025  option should be used sparingly.
7026  Note that the reentrant keyword just means that the parameters & local
7027  variables will be allocated to the stack, it
7028 \emph on
7029 does not
7030 \emph default
7031  mean that the function is register bank independent.
7032 \newline
7033
7034 \newline
7035 Local variables can be assigned storage classes and absolute
7036 \begin_inset LatexCommand \index{Absolute addressing}
7037
7038 \end_inset
7039
7040  addresses, e.g.:
7041 \layout Verse
7042
7043
7044 \family typewriter
7045 unsigned char foo() {
7046 \newline
7047 \SpecialChar ~
7048 \SpecialChar ~
7049 \SpecialChar ~
7050 \SpecialChar ~
7051 xdata unsigned char i;
7052 \newline
7053 \SpecialChar ~
7054 \SpecialChar ~
7055 \SpecialChar ~
7056 \SpecialChar ~
7057 bit bvar;
7058 \newline
7059 \SpecialChar ~
7060 \SpecialChar ~
7061 \SpecialChar ~
7062 \SpecialChar ~
7063 data at 0x31 unsigned char j;
7064 \newline
7065 \SpecialChar ~
7066 \SpecialChar ~
7067 \SpecialChar ~
7068 \SpecialChar ~
7069 ...
7070
7071 \newline
7072 }
7073 \layout Standard
7074
7075 In the above example the variable
7076 \emph on
7077 i
7078 \emph default
7079  will be allocated in the external ram,
7080 \emph on
7081 bvar
7082 \emph default
7083  in bit addressable space and
7084 \emph on
7085  j
7086 \emph default
7087  in internal ram.
7088  When compiled with
7089 \emph on
7090 -
7091 \begin_inset ERT
7092 status Collapsed
7093
7094 \layout Standard
7095
7096 \backslash
7097 /
7098 \end_inset
7099
7100 -stack-auto
7101 \emph default
7102  or when a function is declared as
7103 \emph on
7104 reentrant
7105 \emph default
7106  this should only be done for static variables.
7107 \layout Standard
7108
7109 Parameters however are not allowed any storage class, (storage classes for
7110  parameters will be ignored), their allocation is governed by the memory
7111  model in use, and the reentrancy options.
7112 \layout Subsection
7113
7114 Overlaying
7115 \begin_inset LatexCommand \index{Overlaying}
7116
7117 \end_inset
7118
7119
7120 \layout Standard
7121
7122 For non-reentrant
7123 \begin_inset LatexCommand \index{reentrant}
7124
7125 \end_inset
7126
7127  functions SDCC will try to reduce internal ram space usage by overlaying
7128  parameters and local variables of a function (if possible).
7129  Parameters and local variables of a function will be allocated to an overlayabl
7130 e segment if the function has
7131 \emph on
7132 no other function calls and the function is non-reentrant and the memory
7133  model
7134 \begin_inset LatexCommand \index{Memory model}
7135
7136 \end_inset
7137
7138  is small.
7139
7140 \emph default
7141  If an explicit storage class
7142 \begin_inset LatexCommand \index{Storage class}
7143
7144 \end_inset
7145
7146  is specified for a local variable, it will NOT be overlayed.
7147 \layout Standard
7148
7149 Note that the compiler (not the linkage editor) makes the decision for overlayin
7150 g the data items.
7151  Functions that are called from an interrupt service routine should be preceded
7152  by a #pragma\SpecialChar ~
7153 NOOVERLAY
7154 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
7155
7156 \end_inset
7157
7158  if they are not reentrant.
7159 \layout Standard
7160
7161 Also note that the compiler does not do any processing of inline
7162 \begin_inset LatexCommand \index{inline}
7163
7164 \end_inset
7165
7166  assembler code, so the compiler might incorrectly assign local variables
7167  and parameters of a function into the overlay segment if the inline assembler
7168  code calls other c-functions that might use the overlay.
7169  In that case the #pragma\SpecialChar ~
7170 NOOVERLAY should be used.
7171 \layout Standard
7172
7173 Parameters and Local variables of functions that contain 16 or 32 bit multiplica
7174 tion
7175 \begin_inset LatexCommand \index{Multiplication}
7176
7177 \end_inset
7178
7179  or division
7180 \begin_inset LatexCommand \index{Division}
7181
7182 \end_inset
7183
7184  will NOT be overlayed since these are implemented using external functions,
7185  e.g.:
7186 \layout Verse
7187
7188
7189 \family typewriter
7190 #pragma SAVE
7191 \newline
7192 #pragma NOOVERLAY
7193 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
7194
7195 \end_inset
7196
7197
7198 \newline
7199 void set_error(unsigned char errcd)
7200 \newline
7201 {
7202 \newline
7203 \SpecialChar ~
7204 \SpecialChar ~
7205 \SpecialChar ~
7206 \SpecialChar ~
7207 P3 = errcd;
7208 \newline
7209 }
7210 \newline
7211 #pragma RESTORE
7212 \newline
7213
7214 \newline
7215 void some_isr () interrupt
7216 \begin_inset LatexCommand \index{interrupt}
7217
7218 \end_inset
7219
7220  2 using
7221 \begin_inset LatexCommand \index{using}
7222
7223 \end_inset
7224
7225  1
7226 \newline
7227 {
7228 \newline
7229 \SpecialChar ~
7230 \SpecialChar ~
7231 \SpecialChar ~
7232 \SpecialChar ~
7233 ...
7234 \newline
7235 \SpecialChar ~
7236 \SpecialChar ~
7237 \SpecialChar ~
7238 \SpecialChar ~
7239 set_error(10);
7240 \newline
7241 \SpecialChar ~
7242 \SpecialChar ~
7243 \SpecialChar ~
7244 \SpecialChar ~
7245 ...
7246
7247 \newline
7248 }
7249 \layout Standard
7250
7251 In the above example the parameter
7252 \emph on
7253 errcd
7254 \emph default
7255  for the function
7256 \emph on
7257 set_error
7258 \emph default
7259  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
7260 NOOVERLAY was
7261  not present, this could cause unpredictable runtime behavior when called
7262  from an ISR.
7263  The #pragma\SpecialChar ~
7264 NOOVERLAY ensures that the parameters and local variables for
7265  the function are NOT overlayed.
7266 \layout Subsection
7267
7268 Interrupt Service Routines
7269 \layout Standard
7270
7271 SDCC allows interrupt service routines to be coded in C, with some extended
7272  keywords.
7273 \layout Verse
7274
7275
7276 \family typewriter
7277 void timer_isr (void) interrupt 2 using 1
7278 \newline
7279 {
7280 \newline
7281 ..
7282
7283 \newline
7284 }
7285 \layout Standard
7286
7287 The number following the
7288 \emph on
7289 interrupt
7290 \begin_inset LatexCommand \index{interrupt}
7291
7292 \end_inset
7293
7294
7295 \emph default
7296  keyword is the interrupt number this routine will service.
7297  The compiler will insert a call to this routine in the interrupt vector
7298  table for the interrupt number specified.
7299  The
7300 \emph on
7301 using
7302 \emph default
7303  keyword is used to tell the compiler to use the specified register bank
7304  (8051 specific) when generating code for this function.
7305  Note that when some function is called from an interrupt service routine
7306  it should be preceded by a #pragma\SpecialChar ~
7307 NOOVERLAY
7308 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
7309
7310 \end_inset
7311
7312  if it is not reentrant.
7313  A special note here, int (16 bit) and long (32 bit) integer division
7314 \begin_inset LatexCommand \index{Division}
7315
7316 \end_inset
7317
7318 , multiplication
7319 \begin_inset LatexCommand \index{Multiplication}
7320
7321 \end_inset
7322
7323  & modulus
7324 \begin_inset LatexCommand \index{Modulus}
7325
7326 \end_inset
7327
7328  operations are implemented using external support routines developed in
7329  ANSI-C, if an interrupt service routine needs to do any of these operations
7330  then the support routines (as mentioned in a following section) will have
7331  to be recompiled using the
7332 \emph on
7333  -
7334 \begin_inset ERT
7335 status Collapsed
7336
7337 \layout Standard
7338
7339 \backslash
7340 /
7341 \end_inset
7342
7343 -stack-auto
7344 \begin_inset LatexCommand \index{-\/-stack-auto}
7345
7346 \end_inset
7347
7348
7349 \emph default
7350  option and the source file will need to be compiled using the
7351 \emph on
7352 -
7353 \begin_inset ERT
7354 status Collapsed
7355
7356 \layout Standard
7357
7358 \backslash
7359 /
7360 \end_inset
7361
7362 -int-long-ren
7363 \emph default
7364 t
7365 \begin_inset LatexCommand \index{-\/-int-long-rent}
7366
7367 \end_inset
7368
7369  compiler option.
7370 \layout Standard
7371
7372 If you have multiple source files in your project, interrupt service routines
7373  can be present in any of them, but a prototype of the isr MUST be present
7374  or included in the file that contains the function
7375 \emph on
7376 main
7377 \emph default
7378 .
7379 \layout Standard
7380
7381 Interrupt Numbers and the corresponding address & descriptions for the Standard
7382  8051 are listed below.
7383  SDCC will automatically adjust the interrupt vector table to the maximum
7384  interrupt number specified.
7385 \newline
7386
7387 \layout Standard
7388 \align center
7389
7390 \begin_inset  Tabular
7391 <lyxtabular version="3" rows="6" columns="3">
7392 <features>
7393 <column alignment="center" valignment="top" leftline="true" width="0in">
7394 <column alignment="center" valignment="top" leftline="true" width="0in">
7395 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
7396 <row topline="true" bottomline="true">
7397 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7398 \begin_inset Text
7399
7400 \layout Standard
7401
7402 Interrupt #
7403 \end_inset
7404 </cell>
7405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7406 \begin_inset Text
7407
7408 \layout Standard
7409
7410 Description
7411 \end_inset
7412 </cell>
7413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7414 \begin_inset Text
7415
7416 \layout Standard
7417
7418 Vector Address
7419 \end_inset
7420 </cell>
7421 </row>
7422 <row topline="true">
7423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7424 \begin_inset Text
7425
7426 \layout Standard
7427
7428 0
7429 \end_inset
7430 </cell>
7431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7432 \begin_inset Text
7433
7434 \layout Standard
7435
7436 External 0
7437 \end_inset
7438 </cell>
7439 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7440 \begin_inset Text
7441
7442 \layout Standard
7443
7444 0x0003
7445 \end_inset
7446 </cell>
7447 </row>
7448 <row topline="true">
7449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7450 \begin_inset Text
7451
7452 \layout Standard
7453
7454 1
7455 \end_inset
7456 </cell>
7457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7458 \begin_inset Text
7459
7460 \layout Standard
7461
7462 Timer 0
7463 \end_inset
7464 </cell>
7465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7466 \begin_inset Text
7467
7468 \layout Standard
7469
7470 0x000B
7471 \end_inset
7472 </cell>
7473 </row>
7474 <row topline="true">
7475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7476 \begin_inset Text
7477
7478 \layout Standard
7479
7480 2
7481 \end_inset
7482 </cell>
7483 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7484 \begin_inset Text
7485
7486 \layout Standard
7487
7488 External 1
7489 \end_inset
7490 </cell>
7491 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7492 \begin_inset Text
7493
7494 \layout Standard
7495
7496 0x0013
7497 \end_inset
7498 </cell>
7499 </row>
7500 <row topline="true">
7501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7502 \begin_inset Text
7503
7504 \layout Standard
7505
7506 3
7507 \end_inset
7508 </cell>
7509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7510 \begin_inset Text
7511
7512 \layout Standard
7513
7514 Timer 1
7515 \end_inset
7516 </cell>
7517 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7518 \begin_inset Text
7519
7520 \layout Standard
7521
7522 0x001B
7523 \end_inset
7524 </cell>
7525 </row>
7526 <row topline="true" bottomline="true">
7527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7528 \begin_inset Text
7529
7530 \layout Standard
7531
7532 4
7533 \end_inset
7534 </cell>
7535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
7536 \begin_inset Text
7537
7538 \layout Standard
7539
7540 Serial
7541 \end_inset
7542 </cell>
7543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
7544 \begin_inset Text
7545
7546 \layout Standard
7547
7548 0x0023
7549 \end_inset
7550 </cell>
7551 </row>
7552 </lyxtabular>
7553
7554 \end_inset
7555
7556
7557 \newline
7558
7559 \layout Standard
7560
7561 If the interrupt service routine is defined without
7562 \emph on
7563 using
7564 \begin_inset LatexCommand \index{using}
7565
7566 \end_inset
7567
7568
7569 \emph default
7570  a register bank or with register bank 0 (using 0), the compiler will save
7571  the registers used by itself on the stack upon entry and restore them at
7572  exit, however if such an interrupt service routine calls another function
7573  then the entire register bank will be saved on the stack.
7574  This scheme may be advantageous for small interrupt service routines which
7575  have low register usage.
7576 \layout Standard
7577
7578 If the interrupt service routine is defined to be using a specific register
7579  bank then only
7580 \emph on
7581 a, b & dptr
7582 \emph default
7583  are save and restored, if such an interrupt service routine calls another
7584  function (using another register bank) then the entire register bank of
7585  the called function will be saved on the stack.
7586  This scheme is recommended for larger interrupt service routines.
7587 \layout Standard
7588
7589 Calling other functions from an interrupt service routine is not recommended,
7590  avoid it if possible.
7591 \newline
7592
7593 \newline
7594 Also see the _naked modifier.
7595 \layout Subsection
7596
7597 Critical Functions
7598 \layout Standard
7599
7600
7601 \shape italic
7602 <TODO: this isn't implemented at all!>
7603 \shape default
7604
7605 \newline
7606
7607 \newline
7608 A special keyword may be associated with a function declaring it as
7609 \emph on
7610 critical
7611 \emph default
7612 .
7613  SDCC will generate code to disable all interrupts upon entry to a critical
7614  function and enable them back before returning.
7615  Note that nesting critical functions may cause unpredictable results.
7616 \layout Verse
7617
7618
7619 \family typewriter
7620 int foo () critical
7621 \newline
7622 {
7623 \newline
7624 ...
7625
7626 \newline
7627 ...
7628
7629 \newline
7630 }
7631 \layout Standard
7632
7633 The critical attribute maybe used with other attributes like
7634 \emph on
7635 reentrant.
7636 \layout Subsection
7637
7638 Naked Functions
7639 \begin_inset LatexCommand \index{Naked functions}
7640
7641 \end_inset
7642
7643
7644 \layout Standard
7645
7646 A special keyword may be associated with a function declaring it as
7647 \emph on
7648 _naked
7649 \begin_inset LatexCommand \index{\_naked}
7650
7651 \end_inset
7652
7653 .
7654
7655 \emph default
7656 The
7657 \emph on
7658 _naked
7659 \emph default
7660  function modifier attribute prevents the compiler from generating prologue
7661 \begin_inset LatexCommand \index{function prologue}
7662
7663 \end_inset
7664
7665  and epilogue
7666 \begin_inset LatexCommand \index{function epilogue}
7667
7668 \end_inset
7669
7670  code for that function.
7671  This means that the user is entirely responsible for such things as saving
7672  any registers that may need to be preserved, selecting the proper register
7673  bank, generating the
7674 \emph on
7675 return
7676 \emph default
7677  instruction at the end, etc.
7678  Practically, this means that the contents of the function must be written
7679  in inline assembler.
7680  This is particularly useful for interrupt functions, which can have a large
7681  (and often unnecessary) prologue/epilogue.
7682  For example, compare the code generated by these two functions:
7683 \layout Verse
7684
7685
7686 \family typewriter
7687 data unsigned char counter;
7688 \newline
7689 void simpleInterrupt(void) interrupt
7690 \begin_inset LatexCommand \index{interrupt}
7691
7692 \end_inset
7693
7694  1
7695 \newline
7696 {
7697 \newline
7698 \SpecialChar ~
7699 \SpecialChar ~
7700 \SpecialChar ~
7701 \SpecialChar ~
7702 counter++;
7703 \newline
7704 }
7705 \newline
7706
7707 \newline
7708 void nakedInterrupt(void) interrupt 2 _naked
7709 \newline
7710 {
7711 \newline
7712 \SpecialChar ~
7713 \SpecialChar ~
7714 \SpecialChar ~
7715 \SpecialChar ~
7716 _asm
7717 \begin_inset LatexCommand \index{\_asm}
7718
7719 \end_inset
7720
7721
7722 \newline
7723 \SpecialChar ~
7724 \SpecialChar ~
7725 \SpecialChar ~
7726 \SpecialChar ~
7727 \SpecialChar ~
7728 \SpecialChar ~
7729 inc\SpecialChar ~
7730 \SpecialChar ~
7731 \SpecialChar ~
7732 \SpecialChar ~
7733 \SpecialChar ~
7734 _counter
7735 \newline
7736 \SpecialChar ~
7737 \SpecialChar ~
7738 \SpecialChar ~
7739 \SpecialChar ~
7740 \SpecialChar ~
7741 \SpecialChar ~
7742 reti\SpecialChar ~
7743 \SpecialChar ~
7744 \SpecialChar ~
7745 \SpecialChar ~
7746 ; MUST explicitly include ret in _naked function.
7747 \newline
7748 \SpecialChar ~
7749 \SpecialChar ~
7750 \SpecialChar ~
7751 \SpecialChar ~
7752 _endasm
7753 \begin_inset LatexCommand \index{\_endasm}
7754
7755 \end_inset
7756
7757 ;
7758 \newline
7759 }
7760 \layout Standard
7761
7762 For an 8051 target, the generated simpleInterrupt looks like:
7763 \layout Verse
7764
7765
7766 \family typewriter
7767 _simpleIterrupt:
7768 \newline
7769 \SpecialChar ~
7770 \SpecialChar ~
7771 \SpecialChar ~
7772 \SpecialChar ~
7773 push\SpecialChar ~
7774 \SpecialChar ~
7775 \SpecialChar ~
7776 \SpecialChar ~
7777 acc
7778 \newline
7779 \SpecialChar ~
7780 \SpecialChar ~
7781 \SpecialChar ~
7782 \SpecialChar ~
7783 push\SpecialChar ~
7784 \SpecialChar ~
7785 \SpecialChar ~
7786 \SpecialChar ~
7787 b
7788 \newline
7789 \SpecialChar ~
7790 \SpecialChar ~
7791 \SpecialChar ~
7792 \SpecialChar ~
7793 push\SpecialChar ~
7794 \SpecialChar ~
7795 \SpecialChar ~
7796 \SpecialChar ~
7797 dpl
7798 \newline
7799 \SpecialChar ~
7800 \SpecialChar ~
7801 \SpecialChar ~
7802 \SpecialChar ~
7803 push\SpecialChar ~
7804 \SpecialChar ~
7805 \SpecialChar ~
7806 \SpecialChar ~
7807 dph
7808 \newline
7809 \SpecialChar ~
7810 \SpecialChar ~
7811 \SpecialChar ~
7812 \SpecialChar ~
7813 push\SpecialChar ~
7814 \SpecialChar ~
7815 \SpecialChar ~
7816 \SpecialChar ~
7817 psw
7818 \newline
7819 \SpecialChar ~
7820 \SpecialChar ~
7821 \SpecialChar ~
7822 \SpecialChar ~
7823 mov\SpecialChar ~
7824 \SpecialChar ~
7825 \SpecialChar ~
7826 \SpecialChar ~
7827 \SpecialChar ~
7828 psw,#0x00
7829 \newline
7830 \SpecialChar ~
7831 \SpecialChar ~
7832 \SpecialChar ~
7833 \SpecialChar ~
7834 inc\SpecialChar ~
7835 \SpecialChar ~
7836 \SpecialChar ~
7837 \SpecialChar ~
7838 \SpecialChar ~
7839 _counter
7840 \newline
7841 \SpecialChar ~
7842 \SpecialChar ~
7843 \SpecialChar ~
7844 \SpecialChar ~
7845 pop\SpecialChar ~
7846 \SpecialChar ~
7847 \SpecialChar ~
7848 \SpecialChar ~
7849 \SpecialChar ~
7850 psw
7851 \newline
7852 \SpecialChar ~
7853 \SpecialChar ~
7854 \SpecialChar ~
7855 \SpecialChar ~
7856 pop\SpecialChar ~
7857 \SpecialChar ~
7858 \SpecialChar ~
7859 \SpecialChar ~
7860 \SpecialChar ~
7861 dph
7862 \newline
7863 \SpecialChar ~
7864 \SpecialChar ~
7865 \SpecialChar ~
7866 \SpecialChar ~
7867 pop\SpecialChar ~
7868 \SpecialChar ~
7869 \SpecialChar ~
7870 \SpecialChar ~
7871 \SpecialChar ~
7872 dpl
7873 \newline
7874 \SpecialChar ~
7875 \SpecialChar ~
7876 \SpecialChar ~
7877 \SpecialChar ~
7878 pop\SpecialChar ~
7879 \SpecialChar ~
7880 \SpecialChar ~
7881 \SpecialChar ~
7882 \SpecialChar ~
7883 b
7884 \newline
7885 \SpecialChar ~
7886 \SpecialChar ~
7887 \SpecialChar ~
7888 \SpecialChar ~
7889 pop\SpecialChar ~
7890 \SpecialChar ~
7891 \SpecialChar ~
7892 \SpecialChar ~
7893 \SpecialChar ~
7894 acc
7895 \newline
7896 \SpecialChar ~
7897 \SpecialChar ~
7898 \SpecialChar ~
7899 \SpecialChar ~
7900 reti
7901 \layout Standard
7902
7903 whereas nakedInterrupt looks like:
7904 \layout Verse
7905
7906
7907 \family typewriter
7908 _nakedInterrupt:
7909 \newline
7910 \SpecialChar ~
7911 \SpecialChar ~
7912 \SpecialChar ~
7913 \SpecialChar ~
7914 inc\SpecialChar ~
7915 \SpecialChar ~
7916 \SpecialChar ~
7917 \SpecialChar ~
7918 _counter
7919 \newline
7920 \SpecialChar ~
7921 \SpecialChar ~
7922 \SpecialChar ~
7923 \SpecialChar ~
7924 reti\SpecialChar ~
7925 \SpecialChar ~
7926 \SpecialChar ~
7927 ; MUST explicitly include ret(i) in _naked function.
7928 \layout Standard
7929
7930 While there is nothing preventing you from writing C code inside a _naked
7931  function, there are many ways to shoot yourself in the foot doing this,
7932  and it is recommended that you stick to inline assembler.
7933 \layout Subsection
7934
7935 Functions using private banks
7936 \begin_inset LatexCommand \index{bank}
7937
7938 \end_inset
7939
7940
7941 \layout Standard
7942
7943 The
7944 \emph on
7945 using
7946 \begin_inset LatexCommand \index{using}
7947
7948 \end_inset
7949
7950
7951 \emph default
7952  attribute (which tells the compiler to use a register bank other than the
7953  default bank zero) should only be applied to
7954 \emph on
7955 interrupt
7956 \begin_inset LatexCommand \index{interrupt}
7957
7958 \end_inset
7959
7960
7961 \emph default
7962  functions (see note 1 below).
7963  This will in most circumstances make the generated ISR code more efficient
7964  since it will not have to save registers on the stack.
7965 \layout Standard
7966
7967 The
7968 \emph on
7969 using
7970 \emph default
7971  attribute will have no effect on the generated code for a
7972 \emph on
7973 non-interrupt
7974 \emph default
7975  function (but may occasionally be useful anyway
7976 \begin_inset Foot
7977 collapsed false
7978
7979 \layout Standard
7980
7981 possible exception: if a function is called ONLY from 'interrupt' functions
7982  using a particular bank, it can be declared with the same 'using' attribute
7983  as the calling 'interrupt' functions.
7984  For instance, if you have several ISRs using bank one, and all of them
7985  call memcpy(), it might make sense to create a specialized version of memcpy()
7986  'using 1', since this would prevent the ISR from having to save bank zero
7987  to the stack on entry and switch to bank zero before calling the function
7988 \end_inset
7989
7990 ).
7991 \newline
7992
7993 \emph on
7994 (pending: I don't think this has been done yet)
7995 \layout Standard
7996
7997 An
7998 \emph on
7999 interrupt
8000 \emph default
8001  function using a non-zero bank will assume that it can trash that register
8002  bank, and will not save it.
8003  Since high-priority interrupts
8004 \begin_inset LatexCommand \index{interrupt priority}
8005
8006 \end_inset
8007
8008  can interrupt low-priority ones on the 8051 and friends, this means that
8009  if a high-priority ISR
8010 \emph on
8011 using
8012 \emph default
8013  a particular bank occurs while processing a low-priority ISR
8014 \emph on
8015 using
8016 \emph default
8017  the same bank, terrible and bad things can happen.
8018  To prevent this, no single register bank should be
8019 \emph on
8020 used
8021 \emph default
8022  by both a high priority and a low priority ISR.
8023  This is probably most easily done by having all high priority ISRs use
8024  one bank and all low priority ISRs use another.
8025  If you have an ISR which can change priority at runtime, you're on your
8026  own: I suggest using the default bank zero and taking the small performance
8027  hit.
8028 \layout Standard
8029
8030 It is most efficient if your ISR calls no other functions.
8031  If your ISR must call other functions, it is most efficient if those functions
8032  use the same bank as the ISR (see note 1 below); the next best is if the
8033  called functions use bank zero.
8034  It is very inefficient to call a function using a different, non-zero bank
8035  from an ISR.
8036
8037 \layout Subsection
8038
8039 Absolute Addressing
8040 \begin_inset LatexCommand \index{Absolute addressing}
8041
8042 \end_inset
8043
8044
8045 \layout Standard
8046
8047 Data items can be assigned an absolute address with the
8048 \emph on
8049 at
8050 \begin_inset LatexCommand \index{at}
8051
8052 \end_inset
8053
8054  <address>
8055 \emph default
8056  keyword, in addition to a storage class, e.g.:
8057 \layout Verse
8058
8059
8060 \family typewriter
8061 xdata
8062 \begin_inset LatexCommand \index{xdata}
8063
8064 \end_inset
8065
8066  at
8067 \begin_inset LatexCommand \index{at}
8068
8069 \end_inset
8070
8071  0x8000 unsigned char PORTA_8255 ;
8072 \layout Standard
8073
8074 In the above example the PORTA_8255 will be allocated to the location 0x8000
8075  of the external ram.
8076  Note that this feature is provided to give the programmer access to
8077 \emph on
8078 memory mapped
8079 \emph default
8080  devices attached to the controller.
8081  The compiler does not actually reserve any space for variables declared
8082  in this way (they are implemented with an equate in the assembler).
8083  Thus it is left to the programmer to make sure there are no overlaps with
8084  other variables that are declared without the absolute address.
8085  The assembler listing file (.lst
8086 \begin_inset LatexCommand \index{.lst}
8087
8088 \end_inset
8089
8090 ) and the linker output files (.rst
8091 \begin_inset LatexCommand \index{.rst}
8092
8093 \end_inset
8094
8095 ) and (.map
8096 \begin_inset LatexCommand \index{.map}
8097
8098 \end_inset
8099
8100 ) are a good places to look for such overlaps.
8101 \newline
8102
8103 \newline
8104 Absolute address can be specified for variables in all storage classes,
8105  e.g.:
8106 \layout Verse
8107
8108
8109 \family typewriter
8110 bit
8111 \begin_inset LatexCommand \index{bit}
8112
8113 \end_inset
8114
8115  at
8116 \begin_inset LatexCommand \index{at}
8117
8118 \end_inset
8119
8120  0x02 bvar;
8121 \layout Standard
8122
8123 The above example will allocate the variable at offset 0x02 in the bit-addressab
8124 le space.
8125  There is no real advantage to assigning absolute addresses to variables
8126  in this manner, unless you want strict control over all the variables allocated.
8127  One possible use would be to write hardware portable code.
8128  For example, if you have a routine that uses one or more of the microcontroller
8129  I/O pins, and such pins are different for two different hardwares, you
8130  can declare the I/O pins in you routine using
8131 \layout Verse
8132
8133
8134 \family typewriter
8135 extern bit SDI;
8136 \newline
8137 extern bit SCLK;
8138 \newline
8139 extern bit CPOL;
8140 \newline
8141
8142 \newline
8143 void DS1306_put(unsigned char value)
8144 \newline
8145 {
8146 \newline
8147 \SpecialChar ~
8148 \SpecialChar ~
8149 \SpecialChar ~
8150 \SpecialChar ~
8151 unsigned char mask=0x80;
8152 \newline
8153
8154 \newline
8155 \SpecialChar ~
8156 \SpecialChar ~
8157 \SpecialChar ~
8158 \SpecialChar ~
8159 while(mask)
8160 \newline
8161 \SpecialChar ~
8162 \SpecialChar ~
8163 \SpecialChar ~
8164 \SpecialChar ~
8165 {
8166 \newline
8167 \SpecialChar ~
8168 \SpecialChar ~
8169 \SpecialChar ~
8170 \SpecialChar ~
8171 \SpecialChar ~
8172 \SpecialChar ~
8173 \SpecialChar ~
8174 \SpecialChar ~
8175 SDI=(value & mask)?1:0;
8176 \newline
8177 \SpecialChar ~
8178 \SpecialChar ~
8179 \SpecialChar ~
8180 \SpecialChar ~
8181 \SpecialChar ~
8182 \SpecialChar ~
8183 \SpecialChar ~
8184 \SpecialChar ~
8185 SCLK=!CPOL;
8186 \newline
8187 \SpecialChar ~
8188 \SpecialChar ~
8189 \SpecialChar ~
8190 \SpecialChar ~
8191 \SpecialChar ~
8192 \SpecialChar ~
8193 \SpecialChar ~
8194 \SpecialChar ~
8195 SCLK=CPOL;
8196 \newline
8197 \SpecialChar ~
8198 \SpecialChar ~
8199 \SpecialChar ~
8200 \SpecialChar ~
8201 \SpecialChar ~
8202 \SpecialChar ~
8203 \SpecialChar ~
8204 \SpecialChar ~
8205 mask/=2;
8206 \newline
8207 \SpecialChar ~
8208 \SpecialChar ~
8209 \SpecialChar ~
8210 \SpecialChar ~
8211 }
8212 \newline
8213 }
8214 \layout Standard
8215
8216 Then, someplace in the code for the first hardware you would use
8217 \layout Verse
8218
8219
8220 \family typewriter
8221 bit at 0x80 SDI;\SpecialChar ~
8222 \SpecialChar ~
8223 \SpecialChar ~
8224 \SpecialChar ~
8225 /*I/O port 0, bit 0*/
8226 \newline
8227 bit at 0x81 SCLK;\SpecialChar ~
8228 \SpecialChar ~
8229 \SpecialChar ~
8230 /*I/O port 0, bit 1*/
8231 \newline
8232 bit CPOL;\SpecialChar ~
8233 \SpecialChar ~
8234 \SpecialChar ~
8235 \SpecialChar ~
8236 \SpecialChar ~
8237 \SpecialChar ~
8238 \SpecialChar ~
8239 \SpecialChar ~
8240 \SpecialChar ~
8241 \SpecialChar ~
8242 \SpecialChar ~
8243 /*This is a variable, let the linker allocate this one*/
8244 \layout Standard
8245
8246 Similarly, for the second hardware you would use
8247 \layout Verse
8248
8249
8250 \family typewriter
8251 bit at 0x83 SDI;\SpecialChar ~
8252 \SpecialChar ~
8253 \SpecialChar ~
8254 \SpecialChar ~
8255 /*I/O port 0, bit 3*/
8256 \newline
8257 bit at 0x91 SCLK;\SpecialChar ~
8258 \SpecialChar ~
8259 \SpecialChar ~
8260 /*I/O port 1, bit 1*/
8261 \newline
8262 bit CPOL;\SpecialChar ~
8263 \SpecialChar ~
8264 \SpecialChar ~
8265 \SpecialChar ~
8266 \SpecialChar ~
8267 \SpecialChar ~
8268 \SpecialChar ~
8269 \SpecialChar ~
8270 \SpecialChar ~
8271 \SpecialChar ~
8272 \SpecialChar ~
8273 /*This is a variable, let the linker allocate this one*/
8274 \layout Standard
8275
8276 and you can use the same hardware dependent routine without changes, as
8277  for example in a library.
8278  This is somehow similar to sbit, but only one absolute address has to be
8279  specified in the whole project.
8280 \layout Subsection
8281
8282 Startup Code
8283 \begin_inset LatexCommand \index{Startup code}
8284
8285 \end_inset
8286
8287
8288 \layout Standard
8289
8290 The compiler inserts a call to the C routine
8291 \emph on
8292 _sdcc_external_startup()
8293 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
8294
8295 \end_inset
8296
8297
8298 \series bold
8299 \emph default
8300
8301 \series default
8302 at the start of the CODE area.
8303  This routine is in the runtime library
8304 \begin_inset LatexCommand \index{Runtime library}
8305
8306 \end_inset
8307
8308 .
8309  By default this routine returns 0, if this routine returns a non-zero value,
8310  the static & global variable initialization will be skipped and the function
8311  main will be invoked Other wise static & global variables will be initialized
8312  before the function main is invoked.
8313  You could add a
8314 \emph on
8315 _sdcc_external_startup()
8316 \emph default
8317  routine to your program to override the default if you need to setup hardware
8318  or perform some other critical operation prior to static & global variable
8319  initialization.
8320 \layout Subsection
8321
8322 Inline Assembler Code
8323 \begin_inset LatexCommand \index{Assembler routines}
8324
8325 \end_inset
8326
8327
8328 \layout Standard
8329
8330 SDCC allows the use of in-line assembler with a few restriction as regards
8331  labels.
8332  All labels defined within inline assembler code
8333 \emph on
8334 has to be
8335 \emph default
8336  of the form
8337 \emph on
8338 nnnnn$
8339 \emph default
8340  where nnnn is a number less than 100 (which implies a limit of utmost 100
8341  inline assembler labels
8342 \emph on
8343 per function
8344 \emph default
8345 \noun on
8346 )
8347 \noun default
8348 .
8349  It is strongly recommended that each assembly instruction (including labels)
8350  be placed in a separate line (as the example shows).
8351  When the
8352 \emph on
8353 -
8354 \begin_inset ERT
8355 status Collapsed
8356
8357 \layout Standard
8358
8359 \backslash
8360 /
8361 \end_inset
8362
8363 -peep-asm
8364 \begin_inset LatexCommand \index{-\/-peep-asm}
8365
8366 \end_inset
8367
8368
8369 \emph default
8370  command line option is used, the inline assembler code will be passed through
8371  the peephole optimizer
8372 \begin_inset LatexCommand \index{Peephole optimizer}
8373
8374 \end_inset
8375
8376 .
8377  This might cause some unexpected changes in the inline assembler code.
8378  Please go through the peephole optimizer rules defined in file
8379 \emph on
8380 SDCCpeeph.def
8381 \emph default
8382  carefully before using this option.
8383 \layout Verse
8384
8385
8386 \family typewriter
8387 _asm
8388 \begin_inset LatexCommand \index{\_asm}
8389
8390 \end_inset
8391
8392
8393 \newline
8394 \SpecialChar ~
8395 \SpecialChar ~
8396 \SpecialChar ~
8397 \SpecialChar ~
8398 mov\SpecialChar ~
8399 \SpecialChar ~
8400 \SpecialChar ~
8401 \SpecialChar ~
8402 \SpecialChar ~
8403 b,#10
8404 \newline
8405 00001$:
8406 \newline
8407 \SpecialChar ~
8408 \SpecialChar ~
8409 \SpecialChar ~
8410 \SpecialChar ~
8411 djnz\SpecialChar ~
8412 \SpecialChar ~
8413 \SpecialChar ~
8414 \SpecialChar ~
8415 b,00001$
8416 \newline
8417 _endasm
8418 \begin_inset LatexCommand \index{\_endasm}
8419
8420 \end_inset
8421
8422  ;
8423 \layout Standard
8424
8425 The inline assembler code can contain any valid code understood by the assembler
8426 , this includes any assembler directives and comment lines.
8427  The compiler does not do any validation of the code within the
8428 \family typewriter
8429 _asm ...
8430  _endasm;
8431 \family default
8432  keyword pair.
8433
8434 \newline
8435
8436 \newline
8437 Inline assembler code cannot reference any C-Labels, however it can reference
8438  labels
8439 \begin_inset LatexCommand \index{Labels}
8440
8441 \end_inset
8442
8443  defined by the inline assembler, e.g.:
8444 \layout Verse
8445
8446
8447 \family typewriter
8448 foo() {
8449 \newline
8450 \SpecialChar ~
8451 \SpecialChar ~
8452 \SpecialChar ~
8453 \SpecialChar ~
8454 /* some c code */
8455 \newline
8456 \SpecialChar ~
8457 \SpecialChar ~
8458 \SpecialChar ~
8459 \SpecialChar ~
8460 _asm
8461 \newline
8462 \SpecialChar ~
8463 \SpecialChar ~
8464 \SpecialChar ~
8465 \SpecialChar ~
8466 \SpecialChar ~
8467 \SpecialChar ~
8468 ; some assembler code
8469 \newline
8470 \SpecialChar ~
8471 \SpecialChar ~
8472 \SpecialChar ~
8473 \SpecialChar ~
8474 \SpecialChar ~
8475 \SpecialChar ~
8476 ljmp $0003
8477 \newline
8478 \SpecialChar ~
8479 \SpecialChar ~
8480 \SpecialChar ~
8481 \SpecialChar ~
8482 _endasm;
8483 \newline
8484 \SpecialChar ~
8485 \SpecialChar ~
8486 \SpecialChar ~
8487 \SpecialChar ~
8488 /* some more c code */
8489 \newline
8490 clabel:\SpecialChar ~
8491 \SpecialChar ~
8492 /* inline assembler cannot reference this label */
8493 \newline
8494 \SpecialChar ~
8495 \SpecialChar ~
8496 \SpecialChar ~
8497 \SpecialChar ~
8498 _asm
8499 \newline
8500 \SpecialChar ~
8501 \SpecialChar ~
8502 \SpecialChar ~
8503 \SpecialChar ~
8504 $0003: ;label (can be reference by inline assembler only)
8505 \newline
8506 \SpecialChar ~
8507 \SpecialChar ~
8508 \SpecialChar ~
8509 \SpecialChar ~
8510 _endasm ;
8511 \newline
8512 \SpecialChar ~
8513 \SpecialChar ~
8514 \SpecialChar ~
8515 \SpecialChar ~
8516 /* some more c code */
8517 \newline
8518 }
8519 \layout Standard
8520
8521 In other words inline assembly code can access labels defined in inline
8522  assembly within the scope of the function.
8523  The same goes the other way, ie.
8524  labels defines in inline assembly CANNOT be accessed by C statements.
8525 \layout Subsection
8526
8527 int (16 bit)
8528 \begin_inset LatexCommand \index{int (16 bit)}
8529
8530 \end_inset
8531
8532  and long (32 bit)
8533 \begin_inset LatexCommand \index{long (32 bit)}
8534
8535 \end_inset
8536
8537  Support
8538 \layout Standard
8539
8540 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
8541  multiplication and modulus operations are implemented by support routines.
8542  These support routines are all developed in ANSI-C to facilitate porting
8543  to other MCUs, although some model specific assembler optimizations are
8544  used.
8545  The following files contain the described routine, all of them can be found
8546  in <installdir>/share/sdcc/lib.
8547 \newline
8548
8549 \layout Standard
8550 \align center
8551
8552 \begin_inset  Tabular
8553 <lyxtabular version="3" rows="11" columns="2">
8554 <features>
8555 <column alignment="center" valignment="top" leftline="true" width="0(null)">
8556 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
8557 <row topline="true" bottomline="true">
8558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8559 \begin_inset Text
8560
8561 \layout Standard
8562
8563
8564 \series bold
8565 Function
8566 \end_inset
8567 </cell>
8568 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8569 \begin_inset Text
8570
8571 \layout Standard
8572
8573
8574 \series bold
8575 Description
8576 \end_inset
8577 </cell>
8578 </row>
8579 <row topline="true">
8580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8581 \begin_inset Text
8582
8583 \layout Standard
8584
8585 _mulint.c
8586 \end_inset
8587 </cell>
8588 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8589 \begin_inset Text
8590
8591 \layout Standard
8592
8593 16 bit multiplication
8594 \end_inset
8595 </cell>
8596 </row>
8597 <row topline="true">
8598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8599 \begin_inset Text
8600
8601 \layout Standard
8602
8603 _divsint.c
8604 \end_inset
8605 </cell>
8606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8607 \begin_inset Text
8608
8609 \layout Standard
8610
8611  signed 16 bit division (calls _divuint)
8612 \end_inset
8613 </cell>
8614 </row>
8615 <row topline="true">
8616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8617 \begin_inset Text
8618
8619 \layout Standard
8620
8621 _divuint.c
8622 \end_inset
8623 </cell>
8624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8625 \begin_inset Text
8626
8627 \layout Standard
8628
8629  unsigned 16 bit division
8630 \end_inset
8631 </cell>
8632 </row>
8633 <row topline="true">
8634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8635 \begin_inset Text
8636
8637 \layout Standard
8638
8639 _modsint.c
8640 \end_inset
8641 </cell>
8642 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8643 \begin_inset Text
8644
8645 \layout Standard
8646
8647 signed 16 bit modulus (calls _moduint)
8648 \end_inset
8649 </cell>
8650 </row>
8651 <row topline="true">
8652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8653 \begin_inset Text
8654
8655 \layout Standard
8656
8657 _moduint.c
8658 \end_inset
8659 </cell>
8660 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8661 \begin_inset Text
8662
8663 \layout Standard
8664
8665 unsigned 16 bit modulus
8666 \end_inset
8667 </cell>
8668 </row>
8669 <row topline="true">
8670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8671 \begin_inset Text
8672
8673 \layout Standard
8674
8675 _mullong.c
8676 \end_inset
8677 </cell>
8678 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8679 \begin_inset Text
8680
8681 \layout Standard
8682
8683 32 bit multiplication
8684 \end_inset
8685 </cell>
8686 </row>
8687 <row topline="true">
8688 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8689 \begin_inset Text
8690
8691 \layout Standard
8692
8693 _divslong.c
8694 \end_inset
8695 </cell>
8696 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8697 \begin_inset Text
8698
8699 \layout Standard
8700
8701  signed 32 division (calls _divulong)
8702 \end_inset
8703 </cell>
8704 </row>
8705 <row topline="true">
8706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8707 \begin_inset Text
8708
8709 \layout Standard
8710
8711 _divulong.c
8712 \end_inset
8713 </cell>
8714 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8715 \begin_inset Text
8716
8717 \layout Standard
8718
8719 unsigned 32 division
8720 \end_inset
8721 </cell>
8722 </row>
8723 <row topline="true">
8724 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8725 \begin_inset Text
8726
8727 \layout Standard
8728
8729 _modslong.c
8730 \end_inset
8731 </cell>
8732 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8733 \begin_inset Text
8734
8735 \layout Standard
8736
8737  signed 32 bit modulus (calls _modulong)
8738 \end_inset
8739 </cell>
8740 </row>
8741 <row topline="true" bottomline="true">
8742 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8743 \begin_inset Text
8744
8745 \layout Standard
8746
8747 _modulong.c
8748 \end_inset
8749 </cell>
8750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8751 \begin_inset Text
8752
8753 \layout Standard
8754
8755 unsigned 32 bit modulus
8756 \end_inset
8757 </cell>
8758 </row>
8759 </lyxtabular>
8760
8761 \end_inset
8762
8763
8764 \newline
8765
8766 \layout Standard
8767
8768 Since they are compiled as
8769 \emph on
8770 non-reentrant
8771 \emph default
8772
8773 \begin_inset LatexCommand \index{reentrant}
8774
8775 \end_inset
8776
8777 , interrupt
8778 \begin_inset LatexCommand \index{interrupt}
8779
8780 \end_inset
8781
8782  service routines should not do any of the above operations.
8783  If this is unavoidable then the above routines will need to be compiled
8784  with the
8785 \emph on
8786 -
8787 \begin_inset ERT
8788 status Collapsed
8789
8790 \layout Standard
8791
8792 \backslash
8793 /
8794 \end_inset
8795
8796 -stack-auto
8797 \begin_inset LatexCommand \index{-\/-stack-auto}
8798
8799 \end_inset
8800
8801
8802 \emph default
8803  option, after which the source program will have to be compiled with
8804 \emph on
8805 -
8806 \begin_inset ERT
8807 status Collapsed
8808
8809 \layout Standard
8810
8811 \backslash
8812 /
8813 \end_inset
8814
8815 -int-long-rent
8816 \begin_inset LatexCommand \index{-\/-int-long-rent}
8817
8818 \end_inset
8819
8820
8821 \emph default
8822  option.
8823  Notice that you don't have to call this routines directly.
8824  The compiler will use them automatically every time a integer operation
8825  is required.
8826 \layout Subsection
8827
8828 Floating Point Support
8829 \begin_inset LatexCommand \index{Floating point support}
8830
8831 \end_inset
8832
8833
8834 \layout Standard
8835
8836 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
8837  floating point support routines are derived from gcc's floatlib.c and consists
8838  of the following routines:
8839 \newline
8840
8841 \layout Standard
8842 \align center
8843
8844 \size footnotesize
8845
8846 \begin_inset  Tabular
8847 <lyxtabular version="3" rows="17" columns="2">
8848 <features>
8849 <column alignment="center" valignment="top" leftline="true" width="0(null)">
8850 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
8851 <row topline="true" bottomline="true">
8852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8853 \begin_inset Text
8854
8855 \layout Standard
8856
8857
8858 \family roman
8859 \series medium
8860 \shape up
8861 \size normal
8862 \emph off
8863 \bar no
8864 \noun off
8865 \color none
8866 Function
8867 \end_inset
8868 </cell>
8869 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8870 \begin_inset Text
8871
8872 \layout Standard
8873
8874 Description
8875 \end_inset
8876 </cell>
8877 </row>
8878 <row topline="true">
8879 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8880 \begin_inset Text
8881
8882 \layout Standard
8883
8884
8885 \family roman
8886 \series medium
8887 \shape up
8888 \size normal
8889 \emph off
8890 \bar no
8891 \noun off
8892 \color none
8893 _fsadd.c
8894 \end_inset
8895 </cell>
8896 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8897 \begin_inset Text
8898
8899 \layout Standard
8900
8901
8902 \family roman
8903 \series medium
8904 \shape up
8905 \size normal
8906 \emph off
8907 \bar no
8908 \noun off
8909 \color none
8910 add floating point numbers
8911 \end_inset
8912 </cell>
8913 </row>
8914 <row topline="true">
8915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8916 \begin_inset Text
8917
8918 \layout Standard
8919
8920
8921 \family roman
8922 \series medium
8923 \shape up
8924 \size normal
8925 \emph off
8926 \bar no
8927 \noun off
8928 \color none
8929 _fssub.c
8930 \end_inset
8931 </cell>
8932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8933 \begin_inset Text
8934
8935 \layout Standard
8936
8937
8938 \family roman
8939 \series medium
8940 \shape up
8941 \size normal
8942 \emph off
8943 \bar no
8944 \noun off
8945 \color none
8946 subtract floating point numbers
8947 \end_inset
8948 </cell>
8949 </row>
8950 <row topline="true">
8951 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8952 \begin_inset Text
8953
8954 \layout Standard
8955
8956
8957 \family roman
8958 \series medium
8959 \shape up
8960 \size normal
8961 \emph off
8962 \bar no
8963 \noun off
8964 \color none
8965 _fsdiv.c
8966 \end_inset
8967 </cell>
8968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
8969 \begin_inset Text
8970
8971 \layout Standard
8972
8973
8974 \family roman
8975 \series medium
8976 \shape up
8977 \size normal
8978 \emph off
8979 \bar no
8980 \noun off
8981 \color none
8982 divide floating point numbers
8983 \end_inset
8984 </cell>
8985 </row>
8986 <row topline="true">
8987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
8988 \begin_inset Text
8989
8990 \layout Standard
8991
8992
8993 \family roman
8994 \series medium
8995 \shape up
8996 \size normal
8997 \emph off
8998 \bar no
8999 \noun off
9000 \color none
9001 _fsmul.c
9002 \end_inset
9003 </cell>
9004 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9005 \begin_inset Text
9006
9007 \layout Standard
9008
9009
9010 \family roman
9011 \series medium
9012 \shape up
9013 \size normal
9014 \emph off
9015 \bar no
9016 \noun off
9017 \color none
9018 multiply floating point numbers
9019 \end_inset
9020 </cell>
9021 </row>
9022 <row topline="true">
9023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9024 \begin_inset Text
9025
9026 \layout Standard
9027
9028
9029 \family roman
9030 \series medium
9031 \shape up
9032 \size normal
9033 \emph off
9034 \bar no
9035 \noun off
9036 \color none
9037 _fs2uchar.c
9038 \end_inset
9039 </cell>
9040 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9041 \begin_inset Text
9042
9043 \layout Standard
9044
9045
9046 \family roman
9047 \series medium
9048 \shape up
9049 \size normal
9050 \emph off
9051 \bar no
9052 \noun off
9053 \color none
9054 convert floating point to unsigned char
9055 \end_inset
9056 </cell>
9057 </row>
9058 <row topline="true">
9059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9060 \begin_inset Text
9061
9062 \layout Standard
9063
9064
9065 \family roman
9066 \series medium
9067 \shape up
9068 \size normal
9069 \emph off
9070 \bar no
9071 \noun off
9072 \color none
9073 _fs2char.c
9074 \end_inset
9075 </cell>
9076 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9077 \begin_inset Text
9078
9079 \layout Standard
9080
9081
9082 \family roman
9083 \series medium
9084 \shape up
9085 \size normal
9086 \emph off
9087 \bar no
9088 \noun off
9089 \color none
9090 convert floating point to signed char
9091 \end_inset
9092 </cell>
9093 </row>
9094 <row topline="true">
9095 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9096 \begin_inset Text
9097
9098 \layout Standard
9099
9100
9101 \family roman
9102 \series medium
9103 \shape up
9104 \size normal
9105 \emph off
9106 \bar no
9107 \noun off
9108 \color none
9109 _fs2uint.c
9110 \end_inset
9111 </cell>
9112 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9113 \begin_inset Text
9114
9115 \layout Standard
9116
9117
9118 \family roman
9119 \series medium
9120 \shape up
9121 \size normal
9122 \emph off
9123 \bar no
9124 \noun off
9125 \color none
9126 convert floating point to unsigned int
9127 \end_inset
9128 </cell>
9129 </row>
9130 <row topline="true">
9131 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9132 \begin_inset Text
9133
9134 \layout Standard
9135
9136
9137 \family roman
9138 \series medium
9139 \shape up
9140 \size normal
9141 \emph off
9142 \bar no
9143 \noun off
9144 \color none
9145 _fs2int.c
9146 \end_inset
9147 </cell>
9148 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9149 \begin_inset Text
9150
9151 \layout Standard
9152
9153
9154 \family roman
9155 \series medium
9156 \shape up
9157 \size normal
9158 \emph off
9159 \bar no
9160 \noun off
9161 \color none
9162 convert floating point to signed int
9163 \end_inset
9164 </cell>
9165 </row>
9166 <row topline="true">
9167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9168 \begin_inset Text
9169
9170 \layout Standard
9171
9172
9173 \family roman
9174 \series medium
9175 \shape up
9176 \size normal
9177 \emph off
9178 \bar no
9179 \noun off
9180 \color none
9181 _fs2ulong.
9182 \family default
9183 \series default
9184 \shape default
9185 \size default
9186 \emph default
9187 \bar default
9188 \noun default
9189 \color default
9190 c
9191 \end_inset
9192 </cell>
9193 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9194 \begin_inset Text
9195
9196 \layout Standard
9197
9198
9199 \family roman
9200 \series medium
9201 \shape up
9202 \size normal
9203 \emph off
9204 \bar no
9205 \noun off
9206 \color none
9207 convert floating point to unsigned long
9208 \end_inset
9209 </cell>
9210 </row>
9211 <row topline="true">
9212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9213 \begin_inset Text
9214
9215 \layout Standard
9216
9217
9218 \family roman
9219 \series medium
9220 \shape up
9221 \size normal
9222 \emph off
9223 \bar no
9224 \noun off
9225 \color none
9226 _fs2long.c
9227 \end_inset
9228 </cell>
9229 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9230 \begin_inset Text
9231
9232 \layout Standard
9233
9234
9235 \family roman
9236 \series medium
9237 \shape up
9238 \size normal
9239 \emph off
9240 \bar no
9241 \noun off
9242 \color none
9243 convert floating point to signed long
9244 \end_inset
9245 </cell>
9246 </row>
9247 <row topline="true">
9248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9249 \begin_inset Text
9250
9251 \layout Standard
9252
9253
9254 \family roman
9255 \series medium
9256 \shape up
9257 \size normal
9258 \emph off
9259 \bar no
9260 \noun off
9261 \color none
9262 _uchar2fs.c
9263 \end_inset
9264 </cell>
9265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9266 \begin_inset Text
9267
9268 \layout Standard
9269
9270
9271 \family roman
9272 \series medium
9273 \shape up
9274 \size normal
9275 \emph off
9276 \bar no
9277 \noun off
9278 \color none
9279 convert unsigned char to floating point
9280 \end_inset
9281 </cell>
9282 </row>
9283 <row topline="true">
9284 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9285 \begin_inset Text
9286
9287 \layout Standard
9288
9289
9290 \family roman
9291 \series medium
9292 \shape up
9293 \size normal
9294 \emph off
9295 \bar no
9296 \noun off
9297 \color none
9298 _char2fs.c
9299 \end_inset
9300 </cell>
9301 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9302 \begin_inset Text
9303
9304 \layout Standard
9305
9306
9307 \family roman
9308 \series medium
9309 \shape up
9310 \size normal
9311 \emph off
9312 \bar no
9313 \noun off
9314 \color none
9315 convert char to floating point number
9316 \end_inset
9317 </cell>
9318 </row>
9319 <row topline="true">
9320 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9321 \begin_inset Text
9322
9323 \layout Standard
9324
9325
9326 \family roman
9327 \series medium
9328 \shape up
9329 \size normal
9330 \emph off
9331 \bar no
9332 \noun off
9333 \color none
9334 _uint2fs.c
9335 \end_inset
9336 </cell>
9337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9338 \begin_inset Text
9339
9340 \layout Standard
9341
9342
9343 \family roman
9344 \series medium
9345 \shape up
9346 \size normal
9347 \emph off
9348 \bar no
9349 \noun off
9350 \color none
9351 convert unsigned int to floating point
9352 \end_inset
9353 </cell>
9354 </row>
9355 <row topline="true">
9356 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9357 \begin_inset Text
9358
9359 \layout Standard
9360
9361
9362 \family roman
9363 \series medium
9364 \shape up
9365 \size normal
9366 \emph off
9367 \bar no
9368 \noun off
9369 \color none
9370 _int2fs.c
9371 \end_inset
9372 </cell>
9373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9374 \begin_inset Text
9375
9376 \layout Standard
9377
9378
9379 \family roman
9380 \series medium
9381 \shape up
9382 \size normal
9383 \emph off
9384 \bar no
9385 \noun off
9386 \color none
9387 convert int to floating point numbers
9388 \end_inset
9389 </cell>
9390 </row>
9391 <row topline="true">
9392 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9393 \begin_inset Text
9394
9395 \layout Standard
9396
9397
9398 \family roman
9399 \series medium
9400 \shape up
9401 \size normal
9402 \emph off
9403 \bar no
9404 \noun off
9405 \color none
9406 _ulong2fs.c
9407 \end_inset
9408 </cell>
9409 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9410 \begin_inset Text
9411
9412 \layout Standard
9413
9414
9415 \family roman
9416 \series medium
9417 \shape up
9418 \size normal
9419 \emph off
9420 \bar no
9421 \noun off
9422 \color none
9423 convert unsigned long to floating point number
9424 \end_inset
9425 </cell>
9426 </row>
9427 <row topline="true" bottomline="true">
9428 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9429 \begin_inset Text
9430
9431 \layout Standard
9432
9433
9434 \family roman
9435 \series medium
9436 \shape up
9437 \size normal
9438 \emph off
9439 \bar no
9440 \noun off
9441 \color none
9442 _long2fs.c
9443 \end_inset
9444 </cell>
9445 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9446 \begin_inset Text
9447
9448 \layout Standard
9449
9450
9451 \family roman
9452 \series medium
9453 \shape up
9454 \size normal
9455 \emph off
9456 \bar no
9457 \noun off
9458 \color none
9459 convert long to floating point number
9460 \end_inset
9461 </cell>
9462 </row>
9463 </lyxtabular>
9464
9465 \end_inset
9466
9467
9468 \newline
9469
9470 \layout Standard
9471
9472 Note if all these routines are used simultaneously the data space might
9473  overflow.
9474  For serious floating point usage it is strongly recommended that the large
9475  model be used.
9476  Also notice that you don't have to call this routines directly.
9477  The compiler will use them automatically every time a floating point operation
9478  is required.
9479 \layout Subsection
9480
9481 MCS51 Memory Models
9482 \begin_inset LatexCommand \index{Memory model}
9483
9484 \end_inset
9485
9486
9487 \begin_inset LatexCommand \index{MCS51 memory}
9488
9489 \end_inset
9490
9491
9492 \layout Standard
9493
9494 SDCC allows two memory models for MCS51 code, small and large.
9495  Modules compiled with different memory models should
9496 \emph on
9497 never
9498 \emph default
9499  be combined together or the results would be unpredictable.
9500  The library routines supplied with the compiler are compiled as both small
9501  and large.
9502  The compiled library modules are contained in separate directories as small
9503  and large so that you can link to either set.
9504
9505 \layout Standard
9506
9507 When the large model is used all variables declared without a storage class
9508  will be allocated into the external ram, this includes all parameters and
9509  local variables (for non-reentrant
9510 \begin_inset LatexCommand \index{reentrant}
9511
9512 \end_inset
9513
9514  functions).
9515  When the small model is used variables without storage class are allocated
9516  in the internal ram.
9517 \layout Standard
9518
9519 Judicious usage of the processor specific storage classes
9520 \begin_inset LatexCommand \index{Storage class}
9521
9522 \end_inset
9523
9524  and the 'reentrant' function type will yield much more efficient code,
9525  than using the large model.
9526  Several optimizations are disabled when the program is compiled using the
9527  large model, it is therefore strongly recommended that the small model
9528  be used unless absolutely required.
9529 \layout Subsection
9530
9531 DS390 Memory Models
9532 \begin_inset LatexCommand \index{Memory model}
9533
9534 \end_inset
9535
9536
9537 \begin_inset LatexCommand \index{DS390 memory model}
9538
9539 \end_inset
9540
9541
9542 \layout Standard
9543
9544 The only model supported is Flat 24
9545 \begin_inset LatexCommand \index{Flat 24 (memory model)}
9546
9547 \end_inset
9548
9549 .
9550  This generates code for the 24 bit contiguous addressing mode of the Dallas
9551  DS80C390 part.
9552  In this mode, up to four meg of external RAM or code space can be directly
9553  addressed.
9554  See the data sheets at www.dalsemi.com for further information on this part.
9555 \newline
9556
9557 \newline
9558 In older versions of the compiler, this option was used with the MCS51 code
9559  generator (
9560 \emph on
9561 -mmcs51
9562 \emph default
9563 ).
9564  Now, however, the '390 has it's own code generator, selected by the
9565 \emph on
9566 -mds390
9567 \emph default
9568  switch.
9569
9570 \newline
9571
9572 \newline
9573 Note that the compiler does not generate any code to place the processor
9574  into 24 bitmode (although
9575 \emph on
9576 tinibios
9577 \emph default
9578  in the ds390 libraries will do that for you).
9579  If you don't use
9580 \emph on
9581 tinibios
9582 \emph default
9583
9584 \begin_inset LatexCommand \index{Tinibios (DS390)}
9585
9586 \end_inset
9587
9588 , the boot loader or similar code must ensure that the processor is in 24
9589  bit contiguous addressing mode before calling the SDCC startup code.
9590 \newline
9591
9592 \newline
9593 Like the
9594 \emph on
9595 -
9596 \begin_inset ERT
9597 status Collapsed
9598
9599 \layout Standard
9600
9601 \backslash
9602 /
9603 \end_inset
9604
9605 -model-large
9606 \emph default
9607  option, variables will by default be placed into the XDATA segment.
9608
9609 \newline
9610
9611 \newline
9612 Segments may be placed anywhere in the 4 meg address space using the usual
9613  -
9614 \begin_inset ERT
9615 status Collapsed
9616
9617 \layout Standard
9618
9619 \backslash
9620 /
9621 \end_inset
9622
9623 -*-loc options.
9624  Note that if any segments are located above 64K, the -r flag must be passed
9625  to the linker to generate the proper segment relocations, and the Intel
9626  HEX output format must be used.
9627  The -r flag can be passed to the linker by using the option
9628 \emph on
9629 -Wl-r
9630 \emph default
9631  on the sdcc command line.
9632  However, currently the linker can not handle code segments > 64k.
9633 \layout Subsection
9634
9635 Defines Created by the Compiler
9636 \begin_inset LatexCommand \index{Defines created by the compiler}
9637
9638 \end_inset
9639
9640
9641 \layout Standard
9642
9643 The compiler creates the following #defines
9644 \begin_inset LatexCommand \index{\#defines}
9645
9646 \end_inset
9647
9648 :
9649 \newline
9650
9651 \layout Standard
9652
9653
9654 \begin_inset  Tabular
9655 <lyxtabular version="3" rows="10" columns="2">
9656 <features>
9657 <column alignment="center" valignment="top" leftline="true" width="0(null)">
9658 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
9659 <row topline="true" bottomline="true">
9660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9661 \begin_inset Text
9662
9663 \layout Standard
9664
9665
9666 \series bold
9667 #define
9668 \end_inset
9669 </cell>
9670 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9671 \begin_inset Text
9672
9673 \layout Standard
9674
9675
9676 \series bold
9677 Description
9678 \end_inset
9679 </cell>
9680 </row>
9681 <row topline="true">
9682 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9683 \begin_inset Text
9684
9685 \layout Standard
9686
9687 SDCC
9688 \begin_inset LatexCommand \index{SDCC}
9689
9690 \end_inset
9691
9692
9693 \end_inset
9694 </cell>
9695 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9696 \begin_inset Text
9697
9698 \layout Standard
9699
9700 this Symbol is always defined
9701 \end_inset
9702 </cell>
9703 </row>
9704 <row topline="true">
9705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9706 \begin_inset Text
9707
9708 \layout Standard
9709
9710 SDCC_mcs51
9711 \begin_inset LatexCommand \index{SDCC\_mcs51}
9712
9713 \end_inset
9714
9715  or SDCC_ds390
9716 \begin_inset LatexCommand \index{SDCC\_ds390}
9717
9718 \end_inset
9719
9720  or SDCC_z80
9721 \begin_inset LatexCommand \index{SDCC\_z80}
9722
9723 \end_inset
9724
9725 , etc
9726 \end_inset
9727 </cell>
9728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9729 \begin_inset Text
9730
9731 \layout Standard
9732
9733 depending on the model used (e.g.: -mds390
9734 \end_inset
9735 </cell>
9736 </row>
9737 <row topline="true">
9738 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9739 \begin_inset Text
9740
9741 \layout Standard
9742
9743 __mcs51
9744 \begin_inset LatexCommand \index{\_\_mcs51}
9745
9746 \end_inset
9747
9748  or __ds390
9749 \begin_inset LatexCommand \index{\_\_ds390}
9750
9751 \end_inset
9752
9753  or __z80
9754 \begin_inset LatexCommand \index{\_\_z80}
9755
9756 \end_inset
9757
9758 , etc
9759 \end_inset
9760 </cell>
9761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9762 \begin_inset Text
9763
9764 \layout Standard
9765
9766 depending on the model used (e.g.
9767  -mz80)
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_STACK_AUTO
9778 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
9779
9780 \end_inset
9781
9782
9783 \end_inset
9784 </cell>
9785 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9786 \begin_inset Text
9787
9788 \layout Standard
9789
9790 when
9791 \emph on
9792 -
9793 \begin_inset ERT
9794 status Collapsed
9795
9796 \layout Standard
9797
9798 \backslash
9799 /
9800 \end_inset
9801
9802 -stack-auto
9803 \emph default
9804  option is used
9805 \end_inset
9806 </cell>
9807 </row>
9808 <row topline="true">
9809 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9810 \begin_inset Text
9811
9812 \layout Standard
9813
9814 SDCC_MODEL_SMALL
9815 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
9816
9817 \end_inset
9818
9819
9820 \end_inset
9821 </cell>
9822 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9823 \begin_inset Text
9824
9825 \layout Standard
9826
9827 when
9828 \emph on
9829 -
9830 \begin_inset ERT
9831 status Collapsed
9832
9833 \layout Standard
9834
9835 \backslash
9836 /
9837 \end_inset
9838
9839 -model-small
9840 \emph default
9841  is used
9842 \end_inset
9843 </cell>
9844 </row>
9845 <row topline="true">
9846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9847 \begin_inset Text
9848
9849 \layout Standard
9850
9851 SDCC_MODEL_LARGE
9852 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
9853
9854 \end_inset
9855
9856
9857 \end_inset
9858 </cell>
9859 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9860 \begin_inset Text
9861
9862 \layout Standard
9863
9864 when
9865 \emph on
9866 -
9867 \begin_inset ERT
9868 status Collapsed
9869
9870 \layout Standard
9871
9872 \backslash
9873 /
9874 \end_inset
9875
9876 -model-large
9877 \emph default
9878  is used
9879 \end_inset
9880 </cell>
9881 </row>
9882 <row topline="true">
9883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9884 \begin_inset Text
9885
9886 \layout Standard
9887
9888 SDCC_USE_XSTACK
9889 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
9890
9891 \end_inset
9892
9893
9894 \end_inset
9895 </cell>
9896 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9897 \begin_inset Text
9898
9899 \layout Standard
9900
9901 when
9902 \emph on
9903 -
9904 \begin_inset ERT
9905 status Collapsed
9906
9907 \layout Standard
9908
9909 \backslash
9910 /
9911 \end_inset
9912
9913 -xstack
9914 \emph default
9915  option is used
9916 \end_inset
9917 </cell>
9918 </row>
9919 <row topline="true">
9920 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9921 \begin_inset Text
9922
9923 \layout Standard
9924
9925 SDCC_STACK_TENBIT
9926 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
9927
9928 \end_inset
9929
9930
9931 \end_inset
9932 </cell>
9933 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9934 \begin_inset Text
9935
9936 \layout Standard
9937
9938 when
9939 \emph on
9940 -mds390
9941 \emph default
9942  is used
9943 \end_inset
9944 </cell>
9945 </row>
9946 <row topline="true" bottomline="true">
9947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9948 \begin_inset Text
9949
9950 \layout Standard
9951
9952 SDCC_MODEL_FLAT24
9953 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
9954
9955 \end_inset
9956
9957
9958 \end_inset
9959 </cell>
9960 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9961 \begin_inset Text
9962
9963 \layout Standard
9964
9965 when
9966 \emph on
9967 -mds390
9968 \emph default
9969  is used
9970 \end_inset
9971 </cell>
9972 </row>
9973 </lyxtabular>
9974
9975 \end_inset
9976
9977
9978 \newline
9979
9980 \layout Subsection
9981
9982 Redirecting output on Windows Shells
9983 \layout Standard
9984
9985 By default SDCC writes it's error messages to
9986 \begin_inset Quotes sld
9987 \end_inset
9988
9989 standard error
9990 \begin_inset Quotes srd
9991 \end_inset
9992
9993 .
9994  To force all messages to
9995 \begin_inset Quotes sld
9996 \end_inset
9997
9998 standard output
9999 \begin_inset Quotes srd
10000 \end_inset
10001
10002  use
10003 \series bold
10004 -
10005 \series default
10006 \emph on
10007
10008 \begin_inset ERT
10009 status Collapsed
10010
10011 \layout Standard
10012
10013 \backslash
10014 /
10015 \end_inset
10016
10017
10018 \series bold
10019 \emph default
10020 -
10021 \series default
10022 use-stdout
10023 \begin_inset LatexCommand \index{-\/-use-stdout}
10024
10025 \end_inset
10026
10027 .
10028  Aditionaly, if you happen to have visual studio installed in your windows
10029  machine, you can use it to compile your sources using a custom build and
10030  the SDCC -
10031 \emph on
10032
10033 \begin_inset ERT
10034 status Collapsed
10035
10036 \layout Standard
10037
10038 \backslash
10039 /
10040 \end_inset
10041
10042
10043 \emph default
10044 -vc
10045 \begin_inset LatexCommand \index{-\/-vc}
10046
10047 \end_inset
10048
10049  option.
10050  Something like this should work:
10051 \newline
10052
10053 \newline
10054
10055 \series bold
10056 c:
10057 \backslash
10058 sdcc
10059 \backslash
10060 bin
10061 \backslash
10062 sdcc.exe -
10063 \series default
10064 \emph on
10065
10066 \begin_inset ERT
10067 status Collapsed
10068
10069 \layout Standard
10070
10071 \backslash
10072 /
10073 \end_inset
10074
10075
10076 \series bold
10077 \emph default
10078 -vc -
10079 \series default
10080 \emph on
10081
10082 \begin_inset ERT
10083 status Collapsed
10084
10085 \layout Standard
10086
10087 \backslash
10088 /
10089 \end_inset
10090
10091
10092 \series bold
10093 \emph default
10094 -model-large -c $(InputPath)
10095 \layout Section
10096 \pagebreak_top
10097 SDCC Technical Data
10098 \layout Subsection
10099
10100 Optimizations
10101 \begin_inset LatexCommand \index{Optimizations}
10102
10103 \end_inset
10104
10105
10106 \layout Standard
10107
10108 SDCC performs a host of standard optimizations in addition to some MCU specific
10109  optimizations.
10110
10111 \layout Subsubsection
10112
10113 Sub-expression Elimination
10114 \begin_inset LatexCommand \index{Subexpression elimination}
10115
10116 \end_inset
10117
10118
10119 \layout Standard
10120
10121 The compiler does local and global common subexpression elimination, e.g.:
10122
10123 \layout Verse
10124
10125
10126 \family typewriter
10127 i = x + y + 1;
10128 \newline
10129 j = x + y;
10130 \layout Standard
10131
10132 will be translated to
10133 \layout Verse
10134
10135
10136 \family typewriter
10137 iTemp = x + y
10138 \newline
10139 i = iTemp + 1
10140 \newline
10141 j = iTemp
10142 \layout Standard
10143
10144 Some subexpressions are not as obvious as the above example, e.g.:
10145 \layout Verse
10146
10147
10148 \family typewriter
10149 a->b[i].c = 10;
10150 \newline
10151 a->b[i].d = 11;
10152 \layout Standard
10153
10154 In this case the address arithmetic a->b[i] will be computed only once;
10155  the equivalent code in C would be.
10156 \layout Verse
10157
10158
10159 \family typewriter
10160 iTemp = a->b[i];
10161 \newline
10162 iTemp.c = 10;
10163 \newline
10164 iTemp.d = 11;
10165 \layout Standard
10166
10167 The compiler will try to keep these temporary variables in registers.
10168 \layout Subsubsection
10169
10170 Dead-Code Elimination
10171 \begin_inset LatexCommand \index{Dead-code elimination}
10172
10173 \end_inset
10174
10175
10176 \layout Verse
10177
10178
10179 \family typewriter
10180 int global;
10181 \newline
10182 void f () {
10183 \newline
10184 \SpecialChar ~
10185 \SpecialChar ~
10186 int i;
10187 \newline
10188 \SpecialChar ~
10189 \SpecialChar ~
10190 i = 1; \SpecialChar ~
10191 /* dead store */
10192 \newline
10193 \SpecialChar ~
10194 \SpecialChar ~
10195 global = 1;\SpecialChar ~
10196 /* dead store */
10197 \newline
10198 \SpecialChar ~
10199 \SpecialChar ~
10200 global = 2;
10201 \newline
10202 \SpecialChar ~
10203 \SpecialChar ~
10204 return;
10205 \newline
10206 \SpecialChar ~
10207 \SpecialChar ~
10208 global = 3;\SpecialChar ~
10209 /* unreachable */
10210 \newline
10211 }
10212 \layout Standard
10213
10214 will be changed to
10215 \layout Verse
10216
10217
10218 \family typewriter
10219 int global; void f ()
10220 \newline
10221 {
10222 \newline
10223 \SpecialChar ~
10224 \SpecialChar ~
10225 global = 2;
10226 \newline
10227 \SpecialChar ~
10228 \SpecialChar ~
10229 return;
10230 \newline
10231 }
10232 \layout Subsubsection
10233
10234 Copy-Propagation
10235 \begin_inset LatexCommand \index{Copy propagation}
10236
10237 \end_inset
10238
10239
10240 \layout Verse
10241
10242
10243 \family typewriter
10244 int f() {
10245 \newline
10246 \SpecialChar ~
10247 \SpecialChar ~
10248 int i, j;
10249 \newline
10250 \SpecialChar ~
10251 \SpecialChar ~
10252 i = 10;
10253 \newline
10254 \SpecialChar ~
10255 \SpecialChar ~
10256 j = i;
10257 \newline
10258 \SpecialChar ~
10259 \SpecialChar ~
10260 return j;
10261 \newline
10262 }
10263 \layout Standard
10264
10265 will be changed to
10266 \layout Verse
10267
10268
10269 \family typewriter
10270 int f() {
10271 \newline
10272 \SpecialChar ~
10273 \SpecialChar ~
10274 int i, j;
10275 \newline
10276 \SpecialChar ~
10277 \SpecialChar ~
10278 i = 10;
10279 \newline
10280 \SpecialChar ~
10281 \SpecialChar ~
10282 j = 10;
10283 \newline
10284 \SpecialChar ~
10285 \SpecialChar ~
10286 return 10;
10287 \newline
10288 }
10289 \layout Standard
10290
10291 Note: the dead stores created by this copy propagation will be eliminated
10292  by dead-code elimination.
10293 \layout Subsubsection
10294
10295 Loop Optimizations
10296 \begin_inset LatexCommand \index{Loop optimization}
10297
10298 \end_inset
10299
10300
10301 \layout Standard
10302
10303 Two types of loop optimizations are done by SDCC loop invariant lifting
10304  and strength reduction of loop induction variables.
10305  In addition to the strength reduction the optimizer marks the induction
10306  variables and the register allocator tries to keep the induction variables
10307  in registers for the duration of the loop.
10308  Because of this preference of the register allocator
10309 \begin_inset LatexCommand \index{Register allocation}
10310
10311 \end_inset
10312
10313 , loop induction optimization causes an increase in register pressure, which
10314  may cause unwanted spilling of other temporary variables into the stack
10315 \begin_inset LatexCommand \index{stack}
10316
10317 \end_inset
10318
10319  / data space.
10320  The compiler will generate a warning message when it is forced to allocate
10321  extra space either on the stack or data space.
10322  If this extra space allocation is undesirable then induction optimization
10323  can be eliminated either for the entire source file (with -
10324 \begin_inset ERT
10325 status Collapsed
10326
10327 \layout Standard
10328
10329 \backslash
10330 /
10331 \end_inset
10332
10333 -noinduction option) or for a given function only using #pragma\SpecialChar ~
10334 NOINDUCTION
10335 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
10336
10337 \end_inset
10338
10339 .
10340 \newline
10341
10342 \newline
10343 Loop Invariant:
10344 \layout Verse
10345
10346
10347 \family typewriter
10348 for (i = 0 ; i < 100 ; i ++)
10349 \newline
10350 \SpecialChar ~
10351 \SpecialChar ~
10352 f += k + l;
10353 \layout Standard
10354
10355 changed to
10356 \layout Verse
10357
10358
10359 \family typewriter
10360 itemp = k + l;
10361 \newline
10362 for (i = 0; i < 100; i++)
10363 \newline
10364 \SpecialChar ~
10365 \SpecialChar ~
10366 f += itemp;
10367 \layout Standard
10368
10369 As mentioned previously some loop invariants are not as apparent, all static
10370  address computations are also moved out of the loop.
10371 \newline
10372
10373 \newline
10374 Strength Reduction
10375 \begin_inset LatexCommand \index{Strength reduction}
10376
10377 \end_inset
10378
10379 , this optimization substitutes an expression by a cheaper expression:
10380 \layout Verse
10381
10382
10383 \family typewriter
10384 for (i=0;i < 100; i++)
10385 \newline
10386 \SpecialChar ~
10387 \SpecialChar ~
10388 ar[i*5] = i*3;
10389 \layout Standard
10390
10391 changed to
10392 \layout Verse
10393
10394
10395 \family typewriter
10396 itemp1 = 0;
10397 \newline
10398 itemp2 = 0;
10399 \newline
10400 for (i=0;i< 100;i++) {
10401 \newline
10402 \SpecialChar ~
10403 \SpecialChar ~
10404 \SpecialChar ~
10405 \SpecialChar ~
10406 ar[itemp1] = itemp2;
10407 \newline
10408 \SpecialChar ~
10409 \SpecialChar ~
10410 \SpecialChar ~
10411 \SpecialChar ~
10412 itemp1 += 5;
10413 \newline
10414 \SpecialChar ~
10415 \SpecialChar ~
10416 \SpecialChar ~
10417 \SpecialChar ~
10418 itemp2 += 3;
10419 \newline
10420 }
10421 \layout Standard
10422
10423 The more expensive multiplication
10424 \begin_inset LatexCommand \index{Multiplication}
10425
10426 \end_inset
10427
10428  is changed to a less expensive addition.
10429 \layout Subsubsection
10430
10431 Loop Reversing
10432 \begin_inset LatexCommand \index{Loop reversing}
10433
10434 \end_inset
10435
10436
10437 \layout Standard
10438
10439 This optimization is done to reduce the overhead of checking loop boundaries
10440  for every iteration.
10441  Some simple loops can be reversed and implemented using a
10442 \begin_inset Quotes eld
10443 \end_inset
10444
10445 decrement and jump if not zero
10446 \begin_inset Quotes erd
10447 \end_inset
10448
10449  instruction.
10450  SDCC checks for the following criterion to determine if a loop is reversible
10451  (note: more sophisticated compilers use data-dependency analysis to make
10452  this determination, SDCC uses a more simple minded analysis).
10453 \layout Itemize
10454
10455 The 'for' loop is of the form
10456 \newline
10457
10458 \newline
10459
10460 \family typewriter
10461 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
10462  += 1])
10463 \newline
10464 \SpecialChar ~
10465 \SpecialChar ~
10466 \SpecialChar ~
10467 \SpecialChar ~
10468 <for body>
10469 \layout Itemize
10470
10471 The <for body> does not contain
10472 \begin_inset Quotes eld
10473 \end_inset
10474
10475 continue
10476 \begin_inset Quotes erd
10477 \end_inset
10478
10479  or 'break
10480 \begin_inset Quotes erd
10481 \end_inset
10482
10483 .
10484 \layout Itemize
10485
10486 All goto's are contained within the loop.
10487 \layout Itemize
10488
10489 No function calls within the loop.
10490 \layout Itemize
10491
10492 The loop control variable <sym> is not assigned any value within the loop
10493 \layout Itemize
10494
10495 The loop control variable does NOT participate in any arithmetic operation
10496  within the loop.
10497 \layout Itemize
10498
10499 There are NO switch statements in the loop.
10500 \layout Subsubsection
10501
10502 Algebraic Simplifications
10503 \layout Standard
10504
10505 SDCC does numerous algebraic simplifications, the following is a small sub-set
10506  of these optimizations.
10507 \layout Verse
10508
10509
10510 \family typewriter
10511 i = j + 0 ; /* changed to */ i = j;
10512 \newline
10513 i /= 2; /* changed to */ i >>= 1;
10514 \newline
10515 i = j - j ; /* changed to */ i = 0;
10516 \newline
10517 i = j / 1 ; /* changed to */ i = j;
10518 \layout Standard
10519
10520 Note the subexpressions
10521 \begin_inset LatexCommand \index{Subexpression}
10522
10523 \end_inset
10524
10525  given above are generally introduced by macro expansions or as a result
10526  of copy/constant propagation.
10527 \layout Subsubsection
10528
10529 'switch' Statements
10530 \begin_inset LatexCommand \index{switch statement}
10531
10532 \end_inset
10533
10534
10535 \layout Standard
10536
10537 SDCC changes switch statements to jump tables
10538 \begin_inset LatexCommand \index{jump tables}
10539
10540 \end_inset
10541
10542  when the following conditions are true.
10543
10544 \layout Itemize
10545
10546 The case labels are in numerical sequence, the labels need not be in order,
10547  and the starting number need not be one or zero.
10548 \begin_deeper
10549 \layout Verse
10550
10551
10552 \family typewriter
10553 switch(i) {\SpecialChar ~
10554 \SpecialChar ~
10555 \SpecialChar ~
10556 \SpecialChar ~
10557 \SpecialChar ~
10558 \SpecialChar ~
10559 \SpecialChar ~
10560 \SpecialChar ~
10561 \SpecialChar ~
10562 \SpecialChar ~
10563 \SpecialChar ~
10564 \SpecialChar ~
10565 \SpecialChar ~
10566 \SpecialChar ~
10567 \SpecialChar ~
10568 \SpecialChar ~
10569 \SpecialChar ~
10570 \SpecialChar ~
10571 \SpecialChar ~
10572 \SpecialChar ~
10573 \SpecialChar ~
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 switch (i) {
10580 \newline
10581 \SpecialChar ~
10582 \SpecialChar ~
10583 \SpecialChar ~
10584 case 4: ...\SpecialChar ~
10585 \SpecialChar ~
10586 \SpecialChar ~
10587 \SpecialChar ~
10588 \SpecialChar ~
10589 \SpecialChar ~
10590 \SpecialChar ~
10591 \SpecialChar ~
10592 \SpecialChar ~
10593 \SpecialChar ~
10594 \SpecialChar ~
10595 \SpecialChar ~
10596 \SpecialChar ~
10597 \SpecialChar ~
10598 \SpecialChar ~
10599 \SpecialChar ~
10600 \SpecialChar ~
10601 \SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 \SpecialChar ~
10605 \SpecialChar ~
10606 \SpecialChar ~
10607 \SpecialChar ~
10608 \SpecialChar ~
10609 \SpecialChar ~
10610 case 1: ...
10611
10612 \newline
10613 \SpecialChar ~
10614 \SpecialChar ~
10615 \SpecialChar ~
10616 case 5: ...\SpecialChar ~
10617 \SpecialChar ~
10618 \SpecialChar ~
10619 \SpecialChar ~
10620 \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 case 2: ...
10643
10644 \newline
10645 \SpecialChar ~
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 case 3: ...\SpecialChar ~
10649 \SpecialChar ~
10650 \SpecialChar ~
10651 \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 case 3: ...
10675
10676 \newline
10677 \SpecialChar ~
10678 \SpecialChar ~
10679 \SpecialChar ~
10680 case 6: ...\SpecialChar ~
10681 \SpecialChar ~
10682 \SpecialChar ~
10683 \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 case 4: ...
10707
10708 \newline
10709 }\SpecialChar ~
10710 \SpecialChar ~
10711 \SpecialChar ~
10712 \SpecialChar ~
10713 \SpecialChar ~
10714 \SpecialChar ~
10715 \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 \SpecialChar ~
10742 \SpecialChar ~
10743 \SpecialChar ~
10744 \SpecialChar ~
10745 }
10746 \layout Standard
10747
10748 Both the above switch statements will be implemented using a jump-table.
10749 \end_deeper
10750 \layout Itemize
10751
10752 The number of case labels is at least three, since it takes two conditional
10753  statements to handle the boundary conditions.
10754 \layout Itemize
10755
10756 The number of case labels is less than 84, since each label takes 3 bytes
10757  and a jump-table can be utmost 256 bytes long.
10758
10759 \layout Standard
10760
10761 Switch statements which have gaps in the numeric sequence or those that
10762  have more that 84 case labels can be split into more than one switch statement
10763  for efficient code generation, e.g.:
10764 \layout Verse
10765
10766
10767 \family typewriter
10768 switch (i) {
10769 \newline
10770 \SpecialChar ~
10771 \SpecialChar ~
10772 case 1: ...
10773
10774 \newline
10775 \SpecialChar ~
10776 \SpecialChar ~
10777 case 2: ...
10778
10779 \newline
10780 \SpecialChar ~
10781 \SpecialChar ~
10782 case 3: ...
10783
10784 \newline
10785 \SpecialChar ~
10786 \SpecialChar ~
10787 case 4: ...
10788
10789 \newline
10790 \SpecialChar ~
10791 \SpecialChar ~
10792 case 9: ...
10793
10794 \newline
10795 \SpecialChar ~
10796 \SpecialChar ~
10797 case 10: ...
10798
10799 \newline
10800 \SpecialChar ~
10801 \SpecialChar ~
10802 case 11: ...
10803
10804 \newline
10805 \SpecialChar ~
10806 \SpecialChar ~
10807 case 12: ...
10808
10809 \newline
10810 }
10811 \layout Standard
10812
10813 If the above switch statement is broken down into two switch statements
10814 \layout Verse
10815
10816
10817 \family typewriter
10818 switch (i) {
10819 \newline
10820 \SpecialChar ~
10821 \SpecialChar ~
10822 case 1: ...
10823
10824 \newline
10825 \SpecialChar ~
10826 \SpecialChar ~
10827 case 2: ...
10828
10829 \newline
10830 \SpecialChar ~
10831 \SpecialChar ~
10832 case 3: ...
10833
10834 \newline
10835 \SpecialChar ~
10836 \SpecialChar ~
10837 case 4: ...
10838
10839 \newline
10840 }
10841 \layout Standard
10842
10843 and
10844 \layout Verse
10845
10846
10847 \family typewriter
10848 switch (i) {
10849 \newline
10850 \SpecialChar ~
10851 \SpecialChar ~
10852 case 9: \SpecialChar ~
10853 ...
10854
10855 \newline
10856 \SpecialChar ~
10857 \SpecialChar ~
10858 case 10: ...
10859
10860 \newline
10861 \SpecialChar ~
10862 \SpecialChar ~
10863 case 11: ...
10864
10865 \newline
10866 \SpecialChar ~
10867 \SpecialChar ~
10868 case 12:\SpecialChar ~
10869 ...
10870
10871 \newline
10872 }
10873 \layout Standard
10874
10875 then both the switch statements will be implemented using jump-tables whereas
10876  the unmodified switch statement will not be.
10877 \layout Subsubsection
10878
10879 Bit-shifting Operations
10880 \begin_inset LatexCommand \index{Bit shifting}
10881
10882 \end_inset
10883
10884 .
10885 \layout Standard
10886
10887 Bit shifting is one of the most frequently used operation in embedded programmin
10888 g.
10889  SDCC tries to implement bit-shift operations in the most efficient way
10890  possible, e.g.:
10891 \layout Verse
10892
10893
10894 \family typewriter
10895 unsigned char i;
10896 \newline
10897 ...
10898
10899 \newline
10900 i>>= 4;
10901 \newline
10902 ...
10903 \layout Standard
10904
10905 generates the following code:
10906 \layout Verse
10907
10908
10909 \family typewriter
10910 mov a,_i
10911 \newline
10912 swap a
10913 \newline
10914 anl a,#0x0f
10915 \newline
10916 mov _i,a
10917 \layout Standard
10918
10919 In general SDCC will never setup a loop if the shift count is known.
10920  Another example:
10921 \layout Verse
10922
10923
10924 \family typewriter
10925 unsigned int i;
10926 \newline
10927 ...
10928
10929 \newline
10930 i >>= 9;
10931 \newline
10932 ...
10933 \layout Standard
10934
10935 will generate:
10936 \layout Verse
10937
10938
10939 \family typewriter
10940 mov a,(_i + 1)
10941 \newline
10942 mov (_i + 1),#0x00
10943 \newline
10944 clr c
10945 \newline
10946 rrc a
10947 \newline
10948 mov _i,a
10949 \layout Standard
10950
10951 Note that SDCC stores numbers in little-endian format (i.e.
10952  lowest order first).
10953 \layout Subsubsection
10954
10955 Bit-rotation
10956 \begin_inset LatexCommand \index{Bit rotation}
10957
10958 \end_inset
10959
10960
10961 \layout Standard
10962
10963 A special case of the bit-shift operation is bit rotation, SDCC recognizes
10964  the following expression to be a left bit-rotation:
10965 \layout Verse
10966
10967
10968 \family typewriter
10969 unsigned char i;
10970 \newline
10971 ...
10972
10973 \newline
10974 i = ((i << 1) | (i >> 7));
10975 \family default
10976
10977 \newline
10978
10979 \family typewriter
10980 ...
10981 \layout Standard
10982
10983 will generate the following code:
10984 \layout Verse
10985
10986
10987 \family typewriter
10988 mov a,_i
10989 \newline
10990 rl a
10991 \newline
10992 mov _i,a
10993 \layout Standard
10994
10995 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
10996 ns of this case will also be recognized as bit-rotation, i.e.:
10997 \layout Verse
10998
10999
11000 \family typewriter
11001 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
11002 \layout Subsubsection
11003
11004 Highest Order Bit
11005 \begin_inset LatexCommand \index{Highest Order Bit}
11006
11007 \end_inset
11008
11009
11010 \layout Standard
11011
11012 It is frequently required to obtain the highest order bit of an integral
11013  type (long, int, short or char types).
11014  SDCC recognizes the following expression to yield the highest order bit
11015  and generates optimized code for it, e.g.:
11016 \layout Verse
11017
11018
11019 \family typewriter
11020 unsigned int gint;
11021 \newline
11022
11023 \newline
11024 foo () {
11025 \newline
11026 unsigned char hob;
11027 \newline
11028 \SpecialChar ~
11029 \SpecialChar ~
11030 ...
11031
11032 \newline
11033 \SpecialChar ~
11034 \SpecialChar ~
11035 hob = (gint >> 15) & 1;
11036 \newline
11037 \SpecialChar ~
11038 \SpecialChar ~
11039 ..
11040
11041 \newline
11042 }
11043 \layout Standard
11044
11045 will generate the following code:
11046 \layout Verse
11047
11048
11049 \family typewriter
11050 \SpecialChar ~
11051 \SpecialChar ~
11052 \SpecialChar ~
11053 \SpecialChar ~
11054 \SpecialChar ~
11055 \SpecialChar ~
11056 \SpecialChar ~
11057 \SpecialChar ~
11058 \SpecialChar ~
11059 \SpecialChar ~
11060 \SpecialChar ~
11061 \SpecialChar ~
11062 \SpecialChar ~
11063 \SpecialChar ~
11064 \SpecialChar ~
11065 \SpecialChar ~
11066 \SpecialChar ~
11067 \SpecialChar ~
11068 \SpecialChar ~
11069 \SpecialChar ~
11070 \SpecialChar ~
11071 \SpecialChar ~
11072 \SpecialChar ~
11073 \SpecialChar ~
11074 \SpecialChar ~
11075  61 ;\SpecialChar ~
11076  hob.c 7
11077 \newline
11078 000A E5*01\SpecialChar ~
11079 \SpecialChar ~
11080 \SpecialChar ~
11081 \SpecialChar ~
11082 \SpecialChar ~
11083 \SpecialChar ~
11084 \SpecialChar ~
11085 \SpecialChar ~
11086 \SpecialChar ~
11087 \SpecialChar ~
11088 \SpecialChar ~
11089 \SpecialChar ~
11090 \SpecialChar ~
11091 \SpecialChar ~
11092 \SpecialChar ~
11093  62\SpecialChar ~
11094 \SpecialChar ~
11095 \SpecialChar ~
11096 \SpecialChar ~
11097 \SpecialChar ~
11098 \SpecialChar ~
11099 \SpecialChar ~
11100 \SpecialChar ~
11101  mov\SpecialChar ~
11102  a,(_gint + 1)
11103 \newline
11104 000C 33\SpecialChar ~
11105 \SpecialChar ~
11106 \SpecialChar ~
11107 \SpecialChar ~
11108 \SpecialChar ~
11109 \SpecialChar ~
11110 \SpecialChar ~
11111 \SpecialChar ~
11112 \SpecialChar ~
11113 \SpecialChar ~
11114 \SpecialChar ~
11115 \SpecialChar ~
11116 \SpecialChar ~
11117 \SpecialChar ~
11118 \SpecialChar ~
11119 \SpecialChar ~
11120 \SpecialChar ~
11121 \SpecialChar ~
11122  63\SpecialChar ~
11123 \SpecialChar ~
11124 \SpecialChar ~
11125 \SpecialChar ~
11126 \SpecialChar ~
11127 \SpecialChar ~
11128 \SpecialChar ~
11129 \SpecialChar ~
11130  rlc\SpecialChar ~
11131  a
11132 \newline
11133 000D E4\SpecialChar ~
11134 \SpecialChar ~
11135 \SpecialChar ~
11136 \SpecialChar ~
11137 \SpecialChar ~
11138 \SpecialChar ~
11139 \SpecialChar ~
11140 \SpecialChar ~
11141 \SpecialChar ~
11142 \SpecialChar ~
11143 \SpecialChar ~
11144 \SpecialChar ~
11145 \SpecialChar ~
11146 \SpecialChar ~
11147 \SpecialChar ~
11148 \SpecialChar ~
11149 \SpecialChar ~
11150 \SpecialChar ~
11151  64\SpecialChar ~
11152 \SpecialChar ~
11153 \SpecialChar ~
11154 \SpecialChar ~
11155 \SpecialChar ~
11156 \SpecialChar ~
11157 \SpecialChar ~
11158 \SpecialChar ~
11159  clr\SpecialChar ~
11160  a
11161 \newline
11162 000E 13\SpecialChar ~
11163 \SpecialChar ~
11164 \SpecialChar ~
11165 \SpecialChar ~
11166 \SpecialChar ~
11167 \SpecialChar ~
11168 \SpecialChar ~
11169 \SpecialChar ~
11170 \SpecialChar ~
11171 \SpecialChar ~
11172 \SpecialChar ~
11173 \SpecialChar ~
11174 \SpecialChar ~
11175 \SpecialChar ~
11176 \SpecialChar ~
11177 \SpecialChar ~
11178 \SpecialChar ~
11179 \SpecialChar ~
11180  65\SpecialChar ~
11181 \SpecialChar ~
11182 \SpecialChar ~
11183 \SpecialChar ~
11184 \SpecialChar ~
11185 \SpecialChar ~
11186 \SpecialChar ~
11187 \SpecialChar ~
11188  rrc\SpecialChar ~
11189  a
11190 \newline
11191 000F F5*02\SpecialChar ~
11192 \SpecialChar ~
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 \SpecialChar ~
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 \SpecialChar ~
11200 \SpecialChar ~
11201 \SpecialChar ~
11202 \SpecialChar ~
11203 \SpecialChar ~
11204 \SpecialChar ~
11205 \SpecialChar ~
11206  66\SpecialChar ~
11207 \SpecialChar ~
11208 \SpecialChar ~
11209 \SpecialChar ~
11210 \SpecialChar ~
11211 \SpecialChar ~
11212 \SpecialChar ~
11213 \SpecialChar ~
11214  mov\SpecialChar ~
11215  _foo_hob_1_1,a
11216 \layout Standard
11217
11218 Variations of this case however will
11219 \emph on
11220 not
11221 \emph default
11222  be recognized.
11223  It is a standard C expression, so I heartily recommend this be the only
11224  way to get the highest order bit, (it is portable).
11225  Of course it will be recognized even if it is embedded in other expressions,
11226  e.g.:
11227 \layout Verse
11228
11229
11230 \family typewriter
11231 xyz = gint + ((gint >> 15) & 1);
11232 \layout Standard
11233
11234 will still be recognized.
11235 \layout Subsubsection
11236
11237 Peephole Optimizer
11238 \begin_inset LatexCommand \index{Peephole optimizer}
11239
11240 \end_inset
11241
11242
11243 \layout Standard
11244
11245 The compiler uses a rule based, pattern matching and re-writing mechanism
11246  for peep-hole optimization.
11247  It is inspired by
11248 \emph on
11249 copt
11250 \emph default
11251  a peep-hole optimizer by Christopher W.
11252  Fraser (cwfraser@microsoft.com).
11253  A default set of rules are compiled into the compiler, additional rules
11254  may be added with the
11255 \emph on
11256 -
11257 \begin_inset ERT
11258 status Collapsed
11259
11260 \layout Standard
11261
11262 \backslash
11263 /
11264 \end_inset
11265
11266 -peep-file
11267 \begin_inset LatexCommand \index{-\/-peep-file}
11268
11269 \end_inset
11270
11271  <filename>
11272 \emph default
11273  option.
11274  The rule language is best illustrated with examples.
11275 \layout Verse
11276
11277
11278 \family typewriter
11279 replace {
11280 \newline
11281 \SpecialChar ~
11282 \SpecialChar ~
11283 mov %1,a
11284 \newline
11285 \SpecialChar ~
11286 \SpecialChar ~
11287 mov a,%1
11288 \newline
11289 } by {
11290 \newline
11291 \SpecialChar ~
11292 \SpecialChar ~
11293 mov %1,a
11294 \newline
11295 }
11296 \layout Standard
11297
11298 The above rule will change the following assembly
11299 \begin_inset LatexCommand \index{Assembler routines}
11300
11301 \end_inset
11302
11303  sequence:
11304 \layout Verse
11305
11306
11307 \family typewriter
11308 mov r1,a
11309 \newline
11310 mov a,r1
11311 \layout Standard
11312
11313 to
11314 \layout Verse
11315
11316
11317 \family typewriter
11318 mov r1,a
11319 \layout Standard
11320
11321 Note: All occurrences of a
11322 \emph on
11323 %n
11324 \emph default
11325  (pattern variable) must denote the same string.
11326  With the above rule, the assembly sequence:
11327 \layout Verse
11328
11329
11330 \family typewriter
11331 mov r1,a
11332 \newline
11333 mov a,r2
11334 \layout Standard
11335
11336 will remain unmodified.
11337 \newline
11338
11339 \newline
11340 Other special case optimizations may be added by the user (via
11341 \emph on
11342 -
11343 \begin_inset ERT
11344 status Collapsed
11345
11346 \layout Standard
11347
11348 \backslash
11349 /
11350 \end_inset
11351
11352 -peep-file option
11353 \emph default
11354 ).
11355  E.g.
11356  some variants of the 8051 MCU allow only
11357 \family typewriter
11358 ajmp
11359 \family default
11360  and
11361 \family typewriter
11362 acall
11363 \family default
11364 .
11365  The following two rules will change all
11366 \family typewriter
11367 ljmp
11368 \family default
11369  and
11370 \family typewriter
11371 lcall
11372 \family default
11373  to
11374 \family typewriter
11375 ajmp
11376 \family default
11377  and
11378 \family typewriter
11379 acall
11380 \layout Verse
11381
11382
11383 \family typewriter
11384 replace { lcall %1 } by { acall %1 }
11385 \newline
11386 replace { ljmp %1 } by { ajmp %1 }
11387 \layout Standard
11388
11389 The
11390 \emph on
11391 inline-assembler code
11392 \emph default
11393  is also passed through the peep hole optimizer, thus the peephole optimizer
11394  can also be used as an assembly level macro expander.
11395  The rules themselves are MCU dependent whereas the rule language infra-structur
11396 e is MCU independent.
11397  Peephole optimization rules for other MCU can be easily programmed using
11398  the rule language.
11399 \newline
11400
11401 \newline
11402 The syntax for a rule is as follows:
11403 \layout Verse
11404
11405
11406 \family typewriter
11407 rule := replace [ restart ] '{' <assembly sequence> '
11408 \backslash
11409 n'
11410 \newline
11411 \SpecialChar ~
11412  \SpecialChar ~
11413  \SpecialChar ~
11414  \SpecialChar ~
11415  \SpecialChar ~
11416  \SpecialChar ~
11417  \SpecialChar ~
11418  \SpecialChar ~
11419  \SpecialChar ~
11420  \SpecialChar ~
11421  \SpecialChar ~
11422  \SpecialChar ~
11423  \SpecialChar ~
11424  \SpecialChar ~
11425  '}' by '{' '
11426 \backslash
11427 n'
11428 \newline
11429 \SpecialChar ~
11430  \SpecialChar ~
11431  \SpecialChar ~
11432  \SpecialChar ~
11433  \SpecialChar ~
11434  \SpecialChar ~
11435  \SpecialChar ~
11436  \SpecialChar ~
11437  \SpecialChar ~
11438  \SpecialChar ~
11439  \SpecialChar ~
11440  \SpecialChar ~
11441  \SpecialChar ~
11442  \SpecialChar ~
11443  \SpecialChar ~
11444  \SpecialChar ~
11445  <assembly sequence> '
11446 \backslash
11447 n'
11448 \newline
11449 \SpecialChar ~
11450  \SpecialChar ~
11451  \SpecialChar ~
11452  \SpecialChar ~
11453  \SpecialChar ~
11454  \SpecialChar ~
11455  \SpecialChar ~
11456  \SpecialChar ~
11457  \SpecialChar ~
11458  \SpecialChar ~
11459  \SpecialChar ~
11460  \SpecialChar ~
11461  \SpecialChar ~
11462  \SpecialChar ~
11463  '}' [if <functionName> ] '
11464 \backslash
11465 n'
11466 \layout Standard
11467
11468 <assembly sequence> := assembly instruction (each instruction including
11469  labels must be on a separate line).
11470 \newline
11471
11472 \newline
11473 The optimizer will apply to the rules one by one from the top in the sequence
11474  of their appearance, it will terminate when all rules are exhausted.
11475  If the 'restart' option is specified, then the optimizer will start matching
11476  the rules again from the top, this option for a rule is expensive (performance)
11477 , it is intended to be used in situations where a transformation will trigger
11478  the same rule again.
11479  An example of this (not a good one, it has side effects) is the following
11480  rule:
11481 \layout Verse
11482
11483
11484 \family typewriter
11485 replace restart {
11486 \newline
11487 \SpecialChar ~
11488 \SpecialChar ~
11489 pop %1
11490 \newline
11491 \SpecialChar ~
11492 \SpecialChar ~
11493 push %1 } by {
11494 \newline
11495 \SpecialChar ~
11496 \SpecialChar ~
11497 ; nop
11498 \newline
11499 }
11500 \layout Standard
11501
11502 Note that the replace pattern cannot be a blank, but can be a comment line.
11503  Without the 'restart' option only the inner most 'pop' 'push' pair would
11504  be eliminated, i.e.:
11505 \layout Verse
11506
11507
11508 \family typewriter
11509 pop ar1
11510 \newline
11511 pop ar2
11512 \newline
11513 push ar2
11514 \newline
11515 push ar1
11516 \layout Standard
11517
11518 would result in:
11519 \layout Verse
11520
11521
11522 \family typewriter
11523 pop ar1
11524 \newline
11525 ; nop
11526 \newline
11527 push ar1
11528 \layout Standard
11529
11530
11531 \emph on
11532 with
11533 \emph default
11534  the restart option the rule will be applied again to the resulting code
11535  and then all the pop-push pairs will be eliminated to yield:
11536 \layout Verse
11537
11538
11539 \family typewriter
11540 ; nop
11541 \newline
11542 ; nop
11543 \layout Standard
11544
11545 A conditional function can be attached to a rule.
11546  Attaching rules are somewhat more involved, let me illustrate this with
11547  an example.
11548 \layout Verse
11549
11550
11551 \family typewriter
11552 replace {
11553 \newline
11554 \SpecialChar ~
11555  \SpecialChar ~
11556  \SpecialChar ~
11557 ljmp %5
11558 \newline
11559 %2:
11560 \newline
11561 } by {
11562 \newline
11563 \SpecialChar ~
11564  \SpecialChar ~
11565  \SpecialChar ~
11566 sjmp %5
11567 \newline
11568 %2:
11569 \newline
11570 } if labelInRange
11571 \layout Standard
11572
11573 The optimizer does a look-up of a function name table defined in function
11574
11575 \emph on
11576 callFuncByName
11577 \emph default
11578  in the source file SDCCpeeph.c, with the name
11579 \emph on
11580 labelInRange
11581 \emph default
11582 .
11583  If it finds a corresponding entry the function is called.
11584  Note there can be no parameters specified for these functions, in this
11585  case the use of
11586 \emph on
11587 %5
11588 \emph default
11589  is crucial, since the function
11590 \emph on
11591 labelInRange
11592 \emph default
11593  expects to find the label in that particular variable (the hash table containin
11594 g the variable bindings is passed as a parameter).
11595  If you want to code more such functions, take a close look at the function
11596  labelInRange and the calling mechanism in source file SDCCpeeph.c.
11597  I know this whole thing is a little kludgey, but maybe some day we will
11598  have some better means.
11599  If you are looking at this file, you will also see the default rules that
11600  are compiled into the compiler, you can add your own rules in the default
11601  set there if you get tired of specifying the -
11602 \begin_inset ERT
11603 status Collapsed
11604
11605 \layout Standard
11606
11607 \backslash
11608 /
11609 \end_inset
11610
11611 -peep-file option.
11612 \layout Subsection
11613
11614 Pragmas
11615 \begin_inset LatexCommand \index{Pragmas}
11616
11617 \end_inset
11618
11619
11620 \layout Standard
11621
11622 SDCC supports the following #pragma directives.
11623 \layout Itemize
11624
11625 SAVE
11626 \begin_inset LatexCommand \index{\#pragma SAVE}
11627
11628 \end_inset
11629
11630  - this will save all current options to the SAVE/RESTORE stack.
11631  See RESTORE.
11632 \layout Itemize
11633
11634 RESTORE
11635 \begin_inset LatexCommand \index{\#pragma RESTORE}
11636
11637 \end_inset
11638
11639  - will restore saved options from the last save.
11640  SAVEs & RESTOREs can be nested.
11641  SDCC uses a SAVE/RESTORE stack: SAVE pushes current options to the stack,
11642  RESTORE pulls current options from the stack.
11643  See SAVE.
11644 \layout Itemize
11645
11646 NOGCSE
11647 \begin_inset LatexCommand \index{\#pragma NOGCSE}
11648
11649 \end_inset
11650
11651  - will stop global subexpression elimination.
11652 \layout Itemize
11653
11654 NOINDUCTION
11655 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
11656
11657 \end_inset
11658
11659  - will stop loop induction optimizations.
11660 \layout Itemize
11661
11662 NOJTBOUND
11663 \begin_inset LatexCommand \index{\#pragma NOJTBOUND}
11664
11665 \end_inset
11666
11667  - will not generate code for boundary value checking, when switch statements
11668  are turned into jump-tables.
11669 \layout Itemize
11670
11671 NOOVERLAY
11672 \begin_inset LatexCommand \index{\#pragma NOOVERLAY}
11673
11674 \end_inset
11675
11676  - the compiler will not overlay the parameters and local variables of a
11677  function.
11678 \layout Itemize
11679
11680 LESS_PEDANTIC
11681 \begin_inset LatexCommand \index{\#pragma LESS\_PEDANTIC}
11682
11683 \end_inset
11684
11685  - the compiler will not warn you anymore for obvious mistakes, you'r on
11686  your own now ;-(
11687 \layout Itemize
11688
11689 NOLOOPREVERSE
11690 \begin_inset LatexCommand \index{\#pragma NOLOOPREVERSE}
11691
11692 \end_inset
11693
11694  - Will not do loop reversal optimization
11695 \layout Itemize
11696
11697 EXCLUDE
11698 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
11699
11700 \end_inset
11701
11702  NONE | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
11703  pair of push/pop
11704 \begin_inset LatexCommand \index{push/pop}
11705
11706 \end_inset
11707
11708  instruction in ISR function (using interrupt
11709 \begin_inset LatexCommand \index{interrupt}
11710
11711 \end_inset
11712
11713  keyword).
11714  The directive should be placed immediately before the ISR function definition
11715  and it affects ALL ISR functions following it.
11716  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
11717 EXCLUDE\SpecialChar ~
11718 none
11719 \begin_inset LatexCommand \index{\#pragma EXCLUDE}
11720
11721 \end_inset
11722
11723 .
11724 \layout Itemize
11725
11726 NOIV
11727 \begin_inset LatexCommand \index{\#pragma NOIV}
11728
11729 \end_inset
11730
11731  - Do not generate interrupt vector table entries for all ISR functions
11732  defined after the pragma.
11733  This is useful in cases where the interrupt vector table must be defined
11734  manually, or when there is a secondary, manually defined interrupt vector
11735  table (e.g.
11736  for the autovector feature of the Cypress EZ-USB FX2).
11737 \layout Itemize
11738
11739 CALLEE-SAVES
11740 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
11741
11742 \end_inset
11743
11744
11745 \begin_inset LatexCommand \index{function prologue}
11746
11747 \end_inset
11748
11749  function1[,function2[,function3...]] - The compiler by default uses a caller
11750  saves convention for register saving across function calls, however this
11751  can cause unnecessary register pushing & popping when calling small functions
11752  from larger functions.
11753  This option can be used to switch off the register saving convention for
11754  the function names specified.
11755  The compiler will not save registers when calling these functions, extra
11756  code need to be manually inserted at the entry & exit for these functions
11757  to save & restore the registers used by these functions, this can SUBSTANTIALLY
11758  reduce code & improve run time performance of the generated code.
11759  In the future the compiler (with inter procedural analysis) may be able
11760  to determine the appropriate scheme to use for each function call.
11761  If -
11762 \begin_inset ERT
11763 status Collapsed
11764
11765 \layout Standard
11766
11767 \backslash
11768 /
11769 \end_inset
11770
11771 -callee-saves command line option is used, the function names specified
11772  in #pragma\SpecialChar ~
11773 CALLEE-SAVES
11774 \begin_inset LatexCommand \index{\#pragma CALLEE-SAVES}
11775
11776 \end_inset
11777
11778  is appended to the list of functions specified in the command line.
11779 \layout Standard
11780
11781 The pragma's are intended to be used to turn-off certain optimizations which
11782  might cause the compiler to generate extra stack / data space to store
11783  compiler generated temporary variables.
11784  This usually happens in large functions.
11785  Pragma directives should be used as shown in the following example, they
11786  are used to control options & optimizations for a given function; pragmas
11787  should be placed before and/or after a function, placing pragma's inside
11788  a function body could have unpredictable results.
11789 \layout Verse
11790
11791
11792 \family typewriter
11793 #pragma SAVE
11794 \begin_inset LatexCommand \index{\#pragma SAVE}
11795
11796 \end_inset
11797
11798  /* save the current settings */
11799 \newline
11800 #pragma NOGCSE
11801 \begin_inset LatexCommand \index{\#pragma NOGCSE}
11802
11803 \end_inset
11804
11805  /* turnoff global subexpression elimination */
11806 \newline
11807 #pragma NOINDUCTION
11808 \begin_inset LatexCommand \index{\#pragma NOINDUCTION}
11809
11810 \end_inset
11811
11812  /* turn off induction optimizations */
11813 \newline
11814 int foo ()
11815 \newline
11816 {
11817 \newline
11818 \SpecialChar ~
11819  \SpecialChar ~
11820  ...
11821
11822 \newline
11823 \SpecialChar ~
11824  \SpecialChar ~
11825  /* large code */
11826 \newline
11827 \SpecialChar ~
11828  \SpecialChar ~
11829  ...
11830
11831 \newline
11832 }
11833 \newline
11834 #pragma RESTORE
11835 \begin_inset LatexCommand \index{\#pragma RESTORE}
11836
11837 \end_inset
11838
11839  /* turn the optimizations back on */
11840 \layout Standard
11841
11842 The compiler will generate a warning message when extra space is allocated.
11843  It is strongly recommended that the SAVE and RESTORE pragma's be used when
11844  changing options for a function.
11845 \layout Subsection
11846
11847 Library Routines
11848 \emph on
11849  <pending: this is messy and incomplete>
11850 \emph default
11851
11852 \layout Enumerate
11853
11854 Compiler support routines (_gptrget, _mulint etc)
11855 \layout Enumerate
11856
11857 Stdclib functions (puts, printf, strcat etc)
11858 \layout Enumerate
11859
11860 Math functions (sin, pow, sqrt etc)
11861 \layout Comment
11862
11863 license statements for the libraries are missing
11864 \layout Subsection
11865
11866 Interfacing with Assembly Routines
11867 \begin_inset LatexCommand \index{Assembler routines}
11868
11869 \end_inset
11870
11871
11872 \layout Subsubsection
11873
11874 Global Registers used for Parameter Passing
11875 \begin_inset LatexCommand \index{Parameter passing}
11876
11877 \end_inset
11878
11879
11880 \layout Standard
11881
11882 The compiler always uses the global registers
11883 \emph on
11884 DPL, DPH
11885 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
11886
11887 \end_inset
11888
11889 , B
11890 \begin_inset LatexCommand \index{B (register)}
11891
11892 \end_inset
11893
11894
11895 \emph default
11896 and
11897 \emph on
11898  ACC
11899 \begin_inset LatexCommand \index{ACC}
11900
11901 \end_inset
11902
11903
11904 \emph default
11905  to pass the first parameter to a routine.
11906  The second parameter onwards is either allocated on the stack (for reentrant
11907  routines or if -
11908 \begin_inset ERT
11909 status Collapsed
11910
11911 \layout Standard
11912
11913 \backslash
11914 /
11915 \end_inset
11916
11917 -stack-auto is used) or in the internal / external ram (depending on the
11918  memory model).
11919
11920 \layout Subsubsection
11921
11922 Assembler Routine(non-reentrant
11923 \begin_inset LatexCommand \index{reentrant}
11924
11925 \end_inset
11926
11927 )
11928 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
11929
11930 \end_inset
11931
11932
11933 \layout Standard
11934
11935 In the following example the function c_func calls an assembler routine
11936  asm_func, which takes two parameters.
11937 \layout Verse
11938
11939
11940 \family typewriter
11941 extern int asm_func(unsigned char, unsigned char);
11942 \newline
11943
11944 \newline
11945 int c_func (unsigned char i, unsigned char j)
11946 \newline
11947 {
11948 \newline
11949 \SpecialChar ~
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 return asm_func(i,j);
11954 \newline
11955 }
11956 \newline
11957
11958 \newline
11959 int main()
11960 \newline
11961 {
11962 \newline
11963 \SpecialChar ~
11964 \SpecialChar ~
11965 \SpecialChar ~
11966 \SpecialChar ~
11967 return c_func(10,9);
11968 \newline
11969 }
11970 \layout Standard
11971
11972 The corresponding assembler function is:
11973 \layout Verse
11974
11975
11976 \family typewriter
11977 .globl _asm_func_PARM_2
11978 \newline
11979 \SpecialChar ~
11980 \SpecialChar ~
11981 \SpecialChar ~
11982 \SpecialChar ~
11983 \SpecialChar ~
11984 \SpecialChar ~
11985 \SpecialChar ~
11986 \SpecialChar ~
11987 .globl _asm_func
11988 \newline
11989 \SpecialChar ~
11990 \SpecialChar ~
11991 \SpecialChar ~
11992 \SpecialChar ~
11993 \SpecialChar ~
11994 \SpecialChar ~
11995 \SpecialChar ~
11996 \SpecialChar ~
11997 .area OSEG
11998 \newline
11999 _asm_func_PARM_2:
12000 \newline
12001 \SpecialChar ~
12002 \SpecialChar ~
12003 \SpecialChar ~
12004 \SpecialChar ~
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 \SpecialChar ~
12009 .ds      1
12010 \newline
12011 \SpecialChar ~
12012 \SpecialChar ~
12013 \SpecialChar ~
12014 \SpecialChar ~
12015 \SpecialChar ~
12016 \SpecialChar ~
12017 \SpecialChar ~
12018 \SpecialChar ~
12019 .area CSEG
12020 \newline
12021 _asm_func:
12022 \newline
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 \SpecialChar ~
12026 \SpecialChar ~
12027 \SpecialChar ~
12028 \SpecialChar ~
12029 \SpecialChar ~
12030 \SpecialChar ~
12031 mov    a,dpl
12032 \newline
12033 \SpecialChar ~
12034 \SpecialChar ~
12035 \SpecialChar ~
12036 \SpecialChar ~
12037 \SpecialChar ~
12038 \SpecialChar ~
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 add    a,_asm_func_PARM_2
12042 \newline
12043 \SpecialChar ~
12044 \SpecialChar ~
12045 \SpecialChar ~
12046 \SpecialChar ~
12047 \SpecialChar ~
12048 \SpecialChar ~
12049 \SpecialChar ~
12050 \SpecialChar ~
12051 mov    dpl,a
12052 \newline
12053 \SpecialChar ~
12054 \SpecialChar ~
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 \SpecialChar ~
12060 \SpecialChar ~
12061 mov\SpecialChar ~
12062 \SpecialChar ~
12063 \SpecialChar ~
12064 \SpecialChar ~
12065 dpl
12066 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12067
12068 \end_inset
12069
12070 ,#0x00
12071 \newline
12072 \SpecialChar ~
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 \SpecialChar ~
12076 \SpecialChar ~
12077 \SpecialChar ~
12078 \SpecialChar ~
12079 \SpecialChar ~
12080 ret
12081 \layout Standard
12082
12083 Note here that the return values are placed in 'dpl' - One byte return value,
12084  'dpl' LSB & 'dph' MSB for two byte values.
12085  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12086 b' & 'acc' for four byte values.
12087 \layout Standard
12088
12089 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12090  the parameter number starting from 1, and counting from the left.
12091  The first parameter is passed in
12092 \begin_inset Quotes eld
12093 \end_inset
12094
12095 dpl
12096 \begin_inset Quotes erd
12097 \end_inset
12098
12099  for One bye parameter,
12100 \begin_inset Quotes eld
12101 \end_inset
12102
12103 dptr
12104 \begin_inset Quotes erd
12105 \end_inset
12106
12107  if two bytes,
12108 \begin_inset Quotes eld
12109 \end_inset
12110
12111 b,dptr
12112 \begin_inset Quotes erd
12113 \end_inset
12114
12115  for three bytes and
12116 \begin_inset Quotes eld
12117 \end_inset
12118
12119 acc,b,dptr
12120 \begin_inset Quotes erd
12121 \end_inset
12122
12123  for four bytes, the variable name for the second parameter will be _<function_n
12124 ame>_PARM_2.
12125 \newline
12126
12127 \newline
12128 Assemble the assembler routine with the following command:
12129 \newline
12130
12131 \newline
12132
12133 \family sans
12134 \series bold
12135 asx8051 -losg asmfunc.asm
12136 \newline
12137
12138 \newline
12139
12140 \family default
12141 \series default
12142 Then compile and link the assembler routine to the C source file with the
12143  following command:
12144 \newline
12145
12146 \newline
12147
12148 \family sans
12149 \series bold
12150 sdcc cfunc.c asmfunc.rel
12151 \layout Subsubsection
12152
12153 Assembler Routine(reentrant
12154 \begin_inset LatexCommand \index{reentrant}
12155
12156 \end_inset
12157
12158 )
12159 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12160
12161 \end_inset
12162
12163
12164 \layout Standard
12165
12166 In this case the second parameter onwards will be passed on the stack, the
12167  parameters are pushed from right to left i.e.
12168  after the call the left most parameter will be on the top of the stack.
12169  Here is an example:
12170 \layout Verse
12171
12172
12173 \family typewriter
12174 extern int asm_func(unsigned char, unsigned char);
12175 \newline
12176
12177 \newline
12178 int c_func (unsigned char i, unsigned char j) reentrant
12179 \newline
12180 {
12181 \newline
12182 \SpecialChar ~
12183 \SpecialChar ~
12184 \SpecialChar ~
12185 \SpecialChar ~
12186 return asm_func(i,j);
12187 \newline
12188 }
12189 \newline
12190
12191 \newline
12192 int main()
12193 \newline
12194 {
12195 \newline
12196 \SpecialChar ~
12197 \SpecialChar ~
12198 \SpecialChar ~
12199 \SpecialChar ~
12200 return c_func(10,9);
12201 \newline
12202 }
12203 \layout Standard
12204
12205 The corresponding assembler routine is:
12206 \layout Verse
12207
12208
12209 \family typewriter
12210 .globl _asm_func
12211 \newline
12212 _asm_func:
12213 \newline
12214 \SpecialChar ~
12215 \SpecialChar ~
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 push  _bp
12219 \newline
12220 \SpecialChar ~
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 \SpecialChar ~
12224 mov _bp,sp
12225 \newline
12226 \SpecialChar ~
12227 \SpecialChar ~
12228 \SpecialChar ~
12229 \SpecialChar ~
12230 mov  r2,dpl
12231 \newline
12232 \SpecialChar ~
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 mov  a,_bp
12237 \newline
12238 \SpecialChar ~
12239 \SpecialChar ~
12240 \SpecialChar ~
12241 \SpecialChar ~
12242 clr  c
12243 \newline
12244 \SpecialChar ~
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 add  a,#0xfd
12249 \newline
12250 \SpecialChar ~
12251 \SpecialChar ~
12252 \SpecialChar ~
12253 \SpecialChar ~
12254 mov  r0,a
12255 \newline
12256 \SpecialChar ~
12257 \SpecialChar ~
12258 \SpecialChar ~
12259 \SpecialChar ~
12260 add  a,#0xfc
12261 \newline
12262 \SpecialChar ~
12263 \SpecialChar ~
12264 \SpecialChar ~
12265 \SpecialChar ~
12266 mov  r1,a
12267 \newline
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 mov  a,@r0
12273 \newline
12274 \SpecialChar ~
12275 \SpecialChar ~
12276 \SpecialChar ~
12277 \SpecialChar ~
12278 add  a,r2
12279 \newline
12280 \SpecialChar ~
12281 \SpecialChar ~
12282 \SpecialChar ~
12283 \SpecialChar ~
12284 mov  dpl,a
12285 \newline
12286 \SpecialChar ~
12287 \SpecialChar ~
12288 \SpecialChar ~
12289 \SpecialChar ~
12290 mov  dph,#0x00
12291 \newline
12292 \SpecialChar ~
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 mov  sp,_bp
12297 \newline
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 \SpecialChar ~
12302 pop  _bp
12303 \newline
12304 \SpecialChar ~
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 \SpecialChar ~
12308 ret
12309 \layout Standard
12310
12311 The compiling and linking procedure remains the same, however note the extra
12312  entry & exit linkage required for the assembler code, _bp is the stack
12313  frame pointer and is used to compute the offset into the stack for parameters
12314  and local variables.
12315 \layout Subsection
12316
12317 External Stack
12318 \begin_inset LatexCommand \index{stack}
12319
12320 \end_inset
12321
12322
12323 \begin_inset LatexCommand \index{External stack}
12324
12325 \end_inset
12326
12327
12328 \layout Standard
12329
12330 The external stack is located at the start of the external ram segment,
12331  and is 256 bytes in size.
12332  When -
12333 \begin_inset ERT
12334 status Collapsed
12335
12336 \layout Standard
12337
12338 \backslash
12339 /
12340 \end_inset
12341
12342 -xstack option is used to compile the program, the parameters and local
12343  variables of all reentrant functions are allocated in this area.
12344  This option is provided for programs with large stack space requirements.
12345  When used with the -
12346 \begin_inset ERT
12347 status Collapsed
12348
12349 \layout Standard
12350
12351 \backslash
12352 /
12353 \end_inset
12354
12355 -stack-auto option, all parameters and local variables are allocated on
12356  the external stack (note support libraries will need to be recompiled with
12357  the same options).
12358 \layout Standard
12359
12360 The compiler outputs the higher order address byte of the external ram segment
12361  into PORT P2, therefore when using the External Stack option, this port
12362  MAY NOT be used by the application program.
12363 \layout Subsection
12364
12365 ANSI-Compliance
12366 \begin_inset LatexCommand \index{ANSI-compliance}
12367
12368 \end_inset
12369
12370
12371 \layout Standard
12372
12373 Deviations from the compliance:
12374 \layout Itemize
12375
12376 functions are not always reentrant.
12377 \layout Itemize
12378
12379 structures cannot be assigned values directly, cannot be passed as function
12380  parameters or assigned to each other and cannot be a return value from
12381  a function, e.g.:
12382 \begin_deeper
12383 \layout Verse
12384
12385
12386 \family typewriter
12387 struct s { ...
12388  };
12389 \newline
12390 struct s s1, s2;
12391 \newline
12392 foo()
12393 \newline
12394 {
12395 \newline
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 ...
12401
12402 \newline
12403 \SpecialChar ~
12404 \SpecialChar ~
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
12408 \newline
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 ...
12414
12415 \newline
12416 }
12417 \newline
12418 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
12419  */
12420 \newline
12421 {
12422 \newline
12423 \SpecialChar ~
12424 \SpecialChar ~
12425 \SpecialChar ~
12426 \SpecialChar ~
12427 struct s rets;
12428 \newline
12429 \SpecialChar ~
12430 \SpecialChar ~
12431 \SpecialChar ~
12432 \SpecialChar ~
12433 ...
12434
12435 \newline
12436 \SpecialChar ~
12437 \SpecialChar ~
12438 \SpecialChar ~
12439 \SpecialChar ~
12440 return rets;/* is invalid in SDCC although allowed in ANSI */
12441 \newline
12442 }
12443 \end_deeper
12444 \layout Itemize
12445
12446 'long long
12447 \begin_inset LatexCommand \index{long long (not supported)}
12448
12449 \end_inset
12450
12451 ' (64 bit integers
12452 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
12453
12454 \end_inset
12455
12456 ) not supported.
12457 \layout Itemize
12458
12459 'double
12460 \begin_inset LatexCommand \index{double (not supported)}
12461
12462 \end_inset
12463
12464 ' precision floating point
12465 \begin_inset LatexCommand \index{Floating point support}
12466
12467 \end_inset
12468
12469 not supported.
12470 \layout Itemize
12471
12472 No support for setjmp and longjmp (for now).
12473 \layout Itemize
12474
12475 Old K&R style
12476 \begin_inset LatexCommand \index{K\&R style}
12477
12478 \end_inset
12479
12480  function declarations are NOT allowed.
12481 \begin_deeper
12482 \layout Verse
12483
12484
12485 \family typewriter
12486 foo(i,j) /* this old style of function declarations */
12487 \newline
12488 int i,j; /* are valid in ANSI but not valid in SDCC */
12489 \newline
12490 {
12491 \newline
12492 \SpecialChar ~
12493 \SpecialChar ~
12494 \SpecialChar ~
12495 \SpecialChar ~
12496 ...
12497
12498 \newline
12499 }
12500 \end_deeper
12501 \layout Itemize
12502
12503 functions declared as pointers must be dereferenced during the call.
12504 \begin_deeper
12505 \layout Verse
12506
12507
12508 \family typewriter
12509 int (*foo)();
12510 \newline
12511 ...
12512
12513 \newline
12514 /* has to be called like this */
12515 \newline
12516 (*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
12517 \end_deeper
12518 \layout Subsection
12519
12520 Cyclomatic Complexity
12521 \begin_inset LatexCommand \index{Cyclomatic complexity}
12522
12523 \end_inset
12524
12525
12526 \layout Standard
12527
12528 Cyclomatic complexity of a function is defined as the number of independent
12529  paths the program can take during execution of the function.
12530  This is an important number since it defines the number test cases you
12531  have to generate to validate the function.
12532  The accepted industry standard for complexity number is 10, if the cyclomatic
12533  complexity reported by SDCC exceeds 10 you should think about simplification
12534  of the function logic.
12535  Note that the complexity level is not related to the number of lines of
12536  code in a function.
12537  Large functions can have low complexity, and small functions can have large
12538  complexity levels.
12539
12540 \newline
12541
12542 \newline
12543 SDCC uses the following formula to compute the complexity:
12544 \newline
12545
12546 \layout Standard
12547
12548 complexity = (number of edges in control flow graph) - (number of nodes
12549  in control flow graph) + 2;
12550 \newline
12551
12552 \newline
12553 Having said that the industry standard is 10, you should be aware that in
12554  some cases it be may unavoidable to have a complexity level of less than
12555  10.
12556  For example if you have switch statement with more than 10 case labels,
12557  each case label adds one to the complexity level.
12558  The complexity level is by no means an absolute measure of the algorithmic
12559  complexity of the function, it does however provide a good starting point
12560  for which functions you might look at for further optimization.
12561 \layout Section
12562 \pagebreak_top
12563 TIPS
12564 \layout Standard
12565
12566 Here are a few guidelines that will help the compiler generate more efficient
12567  code, some of the tips are specific to this compiler others are generally
12568  good programming practice.
12569 \layout Itemize
12570
12571 Use the smallest data type to represent your data-value.
12572  If it is known in advance that the value is going to be less than 256 then
12573  use an 'unsigned char' instead of a 'short' or 'int'.
12574 \layout Itemize
12575
12576 Use unsigned when it is known in advance that the value is not going to
12577  be negative.
12578  This helps especially if you are doing division or multiplication.
12579 \layout Itemize
12580
12581 NEVER jump into a LOOP.
12582 \layout Itemize
12583
12584 Declare the variables to be local whenever possible, especially loop control
12585  variables (induction).
12586 \layout Itemize
12587
12588 Since the compiler does not always do implicit integral promotion, the programme
12589 r should do an explicit cast when integral promotion is required.
12590 \layout Itemize
12591
12592 Reducing the size of division, multiplication & modulus operations can reduce
12593  code size substantially.
12594  Take the following code for example.
12595 \begin_deeper
12596 \layout Verse
12597
12598
12599 \family typewriter
12600 foobar(unsigned int p1, unsigned char ch)
12601 \newline
12602 {
12603 \newline
12604 \SpecialChar ~
12605 \SpecialChar ~
12606 \SpecialChar ~
12607 \SpecialChar ~
12608 unsigned char ch1 = p1 % ch ;
12609 \newline
12610 \SpecialChar ~
12611 \SpecialChar ~
12612 \SpecialChar ~
12613 \SpecialChar ~
12614 ....
12615 \newline
12616 }
12617 \layout Standard
12618
12619 For the modulus operation the variable ch will be promoted to unsigned int
12620  first then the modulus operation will be performed (this will lead to a
12621  call to support routine _moduint()), and the result will be casted to a
12622  char.
12623  If the code is changed to
12624 \layout Verse
12625
12626
12627 \family typewriter
12628 foobar(unsigned int p1, unsigned char ch)
12629 \newline
12630 {
12631 \newline
12632 \SpecialChar ~
12633 \SpecialChar ~
12634 \SpecialChar ~
12635 \SpecialChar ~
12636 unsigned char ch1 = (unsigned char)p1 % ch ;
12637 \newline
12638 \SpecialChar ~
12639 \SpecialChar ~
12640 \SpecialChar ~
12641 \SpecialChar ~
12642 ....
12643 \newline
12644 }
12645 \layout Standard
12646
12647 It would substantially reduce the code generated (future versions of the
12648  compiler will be smart enough to detect such optimization opportunities).
12649 \end_deeper
12650 \layout Subsection
12651
12652 Notes on MCS51 memory
12653 \begin_inset LatexCommand \index{MCS51 memory}
12654
12655 \end_inset
12656
12657  layout
12658 \layout Standard
12659
12660 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
12661  RAM memory which is structured as follows
12662 \newline
12663
12664 \newline
12665 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
12666
12667 \newline
12668 - Bytes 20-2F - 16 bytes to hold 128 bit variables and,
12669 \newline
12670 - Bytes 30-7F - 80 bytes for general purpose use.
12671 \newline
12672
12673 \layout Standard
12674
12675 Additionally some members of the MCS51 family may have up to 128 bytes of
12676  additional, indirectly addressable, internal RAM memory (
12677 \emph on
12678 idata
12679 \emph default
12680 ).
12681  Furthermore, some chips may have some built in external memory (
12682 \emph on
12683 xdata
12684 \emph default
12685 ) which should not be confused with the internal, directly addressable RAM
12686  memory (
12687 \emph on
12688 data
12689 \emph default
12690 ).
12691  Usually this built in
12692 \emph on
12693 xdata
12694 \emph default
12695  memory has to be activated before using it (you can probably find this
12696  information on the datasheet of the microcontroller your are using).
12697 \layout Standard
12698
12699 Normally SDCC will only use the first bank
12700 \begin_inset LatexCommand \index{bank}
12701
12702 \end_inset
12703
12704  of registers (register bank 0), but it is possible to specify that other
12705  banks of registers should be used in interrupt
12706 \begin_inset LatexCommand \index{interrupt}
12707
12708 \end_inset
12709
12710  routines.
12711  By default, the compiler will place the stack after the last byte of allocated
12712  memory for variables.
12713  For example, if the first 2 banks of registers are used, and only four
12714  bytes are used for
12715 \emph on
12716 data
12717 \emph default
12718  variables, it will position the base of the internal stack at address 20
12719  (0x14).
12720  This implies that as the stack
12721 \begin_inset LatexCommand \index{stack}
12722
12723 \end_inset
12724
12725  grows, it will use up the remaining register banks, and the 16 bytes used
12726  by the 128 bit variables, and 80 bytes for general purpose use.
12727  If any bit variables are used, the data variables will be placed after
12728  the byte holding the last bit variable.
12729  For example, if register banks 0 and 1 are used, and there are 9 bit variables
12730  (two bytes used),
12731 \emph on
12732 data
12733 \emph default
12734  variables will be placed starting at address 0x22.
12735  You can also use -
12736 \begin_inset ERT
12737 status Collapsed
12738
12739 \layout Standard
12740
12741 \backslash
12742 /
12743 \end_inset
12744
12745 -data-loc
12746 \begin_inset LatexCommand \index{-\/-data-loc}
12747
12748 \end_inset
12749
12750  to specify the start address of the
12751 \emph on
12752 data
12753 \emph default
12754  and -
12755 \begin_inset ERT
12756 status Collapsed
12757
12758 \layout Standard
12759
12760 \backslash
12761 /
12762 \end_inset
12763
12764 -iram-size to specify the size of the total internal RAM (
12765 \emph on
12766 data
12767 \emph default
12768 +
12769 \emph on
12770 idata
12771 \emph default
12772 ).
12773
12774 \layout Standard
12775
12776 By default the 8051 linker will place the stack after the last byte of data
12777  variables.
12778  Option -
12779 \begin_inset ERT
12780 status Collapsed
12781
12782 \layout Standard
12783
12784 \backslash
12785 /
12786 \end_inset
12787
12788 -stack-loc
12789 \begin_inset LatexCommand \index{-\/-stack-loc}
12790
12791 \end_inset
12792
12793  allows you to specify the start of the stack, i.e.
12794  you could start it after any data in the general purpose area.
12795  If your microcontroller has additional indirectly addressable internal
12796  RAM (
12797 \emph on
12798 idata
12799 \emph default
12800 ) you can place the stack on it.
12801  You may also need to use -
12802 \begin_inset ERT
12803 status Collapsed
12804
12805 \layout Standard
12806
12807 \backslash
12808 /
12809 \end_inset
12810
12811 -xdata-loc
12812 \begin_inset LatexCommand \index{-\/-data-loc}
12813
12814 \end_inset
12815
12816  to set the start address of the external RAM (
12817 \emph on
12818 xdata
12819 \emph default
12820 ) and -
12821 \begin_inset ERT
12822 status Collapsed
12823
12824 \layout Standard
12825
12826 \backslash
12827 /
12828 \end_inset
12829
12830 -xram-size
12831 \begin_inset LatexCommand \index{-\/-data-loc}
12832
12833 \end_inset
12834
12835  to specify its size.
12836  Same goes for the code memory, using -
12837 \begin_inset ERT
12838 status Collapsed
12839
12840 \layout Standard
12841
12842 \backslash
12843 /
12844 \end_inset
12845
12846 -code-loc
12847 \begin_inset LatexCommand \index{-\/-data-loc}
12848
12849 \end_inset
12850
12851  and -
12852 \begin_inset ERT
12853 status Collapsed
12854
12855 \layout Standard
12856
12857 \backslash
12858 /
12859 \end_inset
12860
12861 -code-size
12862 \begin_inset LatexCommand \index{-\/-data-loc}
12863
12864 \end_inset
12865
12866 .
12867  If in doubt, don't specify any options and see if the resulting memory
12868  layout is appropriate, then you can adjust it.
12869 \layout Standard
12870
12871 The 8051 linker generates two files with memory allocation information.
12872  The first, with extension .map shows all the variables and segments.
12873  The second with extension .mem shows the final memory layout.
12874  The linker will complaint either if memory segments overlap, there is not
12875  enough memory, or there is not enough space for stack.
12876  If you get any linking warnings and/or errors related to stack or segments
12877  allocation, take a look at either the .map or .mem files to find out what
12878  the problem is.
12879  The .mem file may even suggest a solution to the problem.
12880 \layout Subsection
12881
12882 Tools
12883 \begin_inset LatexCommand \index{Tools}
12884
12885 \end_inset
12886
12887  included in the distribution
12888 \newline
12889
12890 \layout Standard
12891 \align center
12892
12893 \begin_inset  Tabular
12894 <lyxtabular version="3" rows="12" columns="3">
12895 <features>
12896 <column alignment="center" valignment="top" leftline="true" width="0pt">
12897 <column alignment="center" valignment="top" leftline="true" width="0pt">
12898 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
12899 <row topline="true" bottomline="true">
12900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12901 \begin_inset Text
12902
12903 \layout Standard
12904
12905 Name
12906 \end_inset
12907 </cell>
12908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12909 \begin_inset Text
12910
12911 \layout Standard
12912
12913 Purpose
12914 \end_inset
12915 </cell>
12916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12917 \begin_inset Text
12918
12919 \layout Standard
12920
12921 Directory
12922 \end_inset
12923 </cell>
12924 </row>
12925 <row topline="true">
12926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12927 \begin_inset Text
12928
12929 \layout Standard
12930
12931 uCsim
12932 \end_inset
12933 </cell>
12934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12935 \begin_inset Text
12936
12937 \layout Standard
12938
12939 Simulator for various architectures
12940 \end_inset
12941 </cell>
12942 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12943 \begin_inset Text
12944
12945 \layout Standard
12946
12947 sdcc/sim/ucsim
12948 \end_inset
12949 </cell>
12950 </row>
12951 <row topline="true">
12952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12953 \begin_inset Text
12954
12955 \layout Standard
12956
12957 keil2sdcc.pl
12958 \end_inset
12959 </cell>
12960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12961 \begin_inset Text
12962
12963 \layout Standard
12964
12965 header file conversion
12966 \end_inset
12967 </cell>
12968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12969 \begin_inset Text
12970
12971 \layout Standard
12972
12973 sdcc/support/scripts
12974 \end_inset
12975 </cell>
12976 </row>
12977 <row topline="true">
12978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12979 \begin_inset Text
12980
12981 \layout Standard
12982
12983 mh2h.c
12984 \end_inset
12985 </cell>
12986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12987 \begin_inset Text
12988
12989 \layout Standard
12990
12991 header file conversion
12992 \end_inset
12993 </cell>
12994 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12995 \begin_inset Text
12996
12997 \layout Standard
12998
12999 sdcc/support/scripts
13000 \end_inset
13001 </cell>
13002 </row>
13003 <row topline="true">
13004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13005 \begin_inset Text
13006
13007 \layout Standard
13008
13009 as-gbz80
13010 \end_inset
13011 </cell>
13012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13013 \begin_inset Text
13014
13015 \layout Standard
13016
13017 Assembler
13018 \end_inset
13019 </cell>
13020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13021 \begin_inset Text
13022
13023 \layout Standard
13024
13025
13026 \family roman
13027 \series medium
13028 \shape up
13029 \size normal
13030 \emph off
13031 \bar no
13032 \noun off
13033 \color none
13034 sdcc/bin
13035 \end_inset
13036 </cell>
13037 </row>
13038 <row topline="true">
13039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13040 \begin_inset Text
13041
13042 \layout Standard
13043
13044 as-z80
13045 \end_inset
13046 </cell>
13047 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13048 \begin_inset Text
13049
13050 \layout Standard
13051
13052 Assembler
13053 \end_inset
13054 </cell>
13055 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13056 \begin_inset Text
13057
13058 \layout Standard
13059
13060
13061 \family roman
13062 \series medium
13063 \shape up
13064 \size normal
13065 \emph off
13066 \bar no
13067 \noun off
13068 \color none
13069 sdcc/bin
13070 \end_inset
13071 </cell>
13072 </row>
13073 <row topline="true">
13074 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13075 \begin_inset Text
13076
13077 \layout Standard
13078
13079 asx8051
13080 \end_inset
13081 </cell>
13082 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13083 \begin_inset Text
13084
13085 \layout Standard
13086
13087 Assembler
13088 \end_inset
13089 </cell>
13090 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13091 \begin_inset Text
13092
13093 \layout Standard
13094
13095
13096 \family roman
13097 \series medium
13098 \shape up
13099 \size normal
13100 \emph off
13101 \bar no
13102 \noun off
13103 \color none
13104 sdcc/bin
13105 \end_inset
13106 </cell>
13107 </row>
13108 <row topline="true">
13109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13110 \begin_inset Text
13111
13112 \layout Standard
13113
13114 sdcdb
13115 \end_inset
13116 </cell>
13117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13118 \begin_inset Text
13119
13120 \layout Standard
13121
13122 Simulator
13123 \end_inset
13124 </cell>
13125 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13126 \begin_inset Text
13127
13128 \layout Standard
13129
13130
13131 \family roman
13132 \series medium
13133 \shape up
13134 \size normal
13135 \emph off
13136 \bar no
13137 \noun off
13138 \color none
13139 sdcc/bin
13140 \end_inset
13141 </cell>
13142 </row>
13143 <row topline="true">
13144 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13145 \begin_inset Text
13146
13147 \layout Standard
13148
13149 aslink
13150 \end_inset
13151 </cell>
13152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13153 \begin_inset Text
13154
13155 \layout Standard
13156
13157 Linker
13158 \end_inset
13159 </cell>
13160 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13161 \begin_inset Text
13162
13163 \layout Standard
13164
13165
13166 \family roman
13167 \series medium
13168 \shape up
13169 \size normal
13170 \emph off
13171 \bar no
13172 \noun off
13173 \color none
13174 sdcc/bin
13175 \end_inset
13176 </cell>
13177 </row>
13178 <row topline="true">
13179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13180 \begin_inset Text
13181
13182 \layout Standard
13183
13184 link-z80
13185 \end_inset
13186 </cell>
13187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13188 \begin_inset Text
13189
13190 \layout Standard
13191
13192 Linker
13193 \end_inset
13194 </cell>
13195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13196 \begin_inset Text
13197
13198 \layout Standard
13199
13200
13201 \family roman
13202 \series medium
13203 \shape up
13204 \size normal
13205 \emph off
13206 \bar no
13207 \noun off
13208 \color none
13209 sdcc/bin
13210 \end_inset
13211 </cell>
13212 </row>
13213 <row topline="true">
13214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13215 \begin_inset Text
13216
13217 \layout Standard
13218
13219 link-gbz80
13220 \end_inset
13221 </cell>
13222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13223 \begin_inset Text
13224
13225 \layout Standard
13226
13227 Linker
13228 \end_inset
13229 </cell>
13230 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13231 \begin_inset Text
13232
13233 \layout Standard
13234
13235
13236 \family roman
13237 \series medium
13238 \shape up
13239 \size normal
13240 \emph off
13241 \bar no
13242 \noun off
13243 \color none
13244 sdcc/bin
13245 \end_inset
13246 </cell>
13247 </row>
13248 <row topline="true" bottomline="true">
13249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13250 \begin_inset Text
13251
13252 \layout Standard
13253
13254 packihx
13255 \end_inset
13256 </cell>
13257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13258 \begin_inset Text
13259
13260 \layout Standard
13261
13262 ihx packer
13263 \end_inset
13264 </cell>
13265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13266 \begin_inset Text
13267
13268 \layout Standard
13269
13270
13271 \family roman
13272 \series medium
13273 \shape up
13274 \size normal
13275 \emph off
13276 \bar no
13277 \noun off
13278 \color none
13279 sdcc/bin
13280 \end_inset
13281 </cell>
13282 </row>
13283 </lyxtabular>
13284
13285 \end_inset
13286
13287
13288 \newline
13289
13290 \layout Subsection
13291
13292 Related open source tools
13293 \begin_inset LatexCommand \index{Related tools}
13294
13295 \end_inset
13296
13297
13298 \newline
13299
13300 \layout Standard
13301 \align center
13302
13303 \begin_inset  Tabular
13304 <lyxtabular version="3" rows="7" columns="3">
13305 <features>
13306 <column alignment="center" valignment="top" leftline="true" width="0pt">
13307 <column alignment="center" valignment="top" leftline="true" width="0pt">
13308 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
13309 <row topline="true" bottomline="true">
13310 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13311 \begin_inset Text
13312
13313 \layout Standard
13314
13315 Name
13316 \end_inset
13317 </cell>
13318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13319 \begin_inset Text
13320
13321 \layout Standard
13322
13323 Purpose
13324 \end_inset
13325 </cell>
13326 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13327 \begin_inset Text
13328
13329 \layout Standard
13330
13331 Where to get
13332 \end_inset
13333 </cell>
13334 </row>
13335 <row topline="true">
13336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13337 \begin_inset Text
13338
13339 \layout Standard
13340
13341 gpsim
13342 \begin_inset LatexCommand \index{gpsim}
13343
13344 \end_inset
13345
13346
13347 \end_inset
13348 </cell>
13349 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13350 \begin_inset Text
13351
13352 \layout Standard
13353
13354 PIC simulator
13355 \end_inset
13356 </cell>
13357 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13358 \begin_inset Text
13359
13360 \layout Standard
13361
13362
13363 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
13364
13365 \end_inset
13366
13367
13368 \end_inset
13369 </cell>
13370 </row>
13371 <row topline="true">
13372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13373 \begin_inset Text
13374
13375 \layout Standard
13376
13377 srecord
13378 \begin_inset LatexCommand \index{srecord}
13379
13380 \end_inset
13381
13382
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 Object file conversion, checksumming, ...
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
13399 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
13400
13401 \end_inset
13402
13403
13404 \end_inset
13405 </cell>
13406 </row>
13407 <row topline="true">
13408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13409 \begin_inset Text
13410
13411 \layout Standard
13412
13413 objdump
13414 \begin_inset LatexCommand \index{objdump}
13415
13416 \end_inset
13417
13418
13419 \end_inset
13420 </cell>
13421 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13422 \begin_inset Text
13423
13424 \layout Standard
13425
13426 Object file conversion, ...
13427 \end_inset
13428 </cell>
13429 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13430 \begin_inset Text
13431
13432 \layout Standard
13433
13434 Part of binutils (should be there anyway)
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 doxygen
13445 \begin_inset LatexCommand \index{doxygen}
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 Source code documentation system
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://www.doxygen.org}
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 splint
13481 \begin_inset LatexCommand \index{splint}
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 Statically checks c sources
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
13502 \begin_inset LatexCommand \url{http://www.splint.org}
13503
13504 \end_inset
13505
13506
13507 \end_inset
13508 </cell>
13509 </row>
13510 <row topline="true" bottomline="true">
13511 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13512 \begin_inset Text
13513
13514 \layout Standard
13515
13516 ddd
13517 \begin_inset LatexCommand \index{ddd}
13518
13519 \end_inset
13520
13521
13522 \end_inset
13523 </cell>
13524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13525 \begin_inset Text
13526
13527 \layout Standard
13528
13529 Debugger, serves nicely as GUI to sdcdb
13530 \begin_inset LatexCommand \index{sdcdb}
13531
13532 \end_inset
13533
13534
13535 \end_inset
13536 </cell>
13537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13538 \begin_inset Text
13539
13540 \layout Standard
13541
13542
13543 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
13544
13545 \end_inset
13546
13547
13548 \end_inset
13549 </cell>
13550 </row>
13551 </lyxtabular>
13552
13553 \end_inset
13554
13555
13556 \newline
13557
13558 \layout Subsection
13559
13560 Related documentation / recommended reading
13561 \newline
13562
13563 \layout Standard
13564 \align center
13565
13566 \begin_inset  Tabular
13567 <lyxtabular version="3" rows="5" columns="3">
13568 <features>
13569 <column alignment="center" valignment="top" leftline="true" width="0pt">
13570 <column alignment="center" valignment="top" leftline="true" width="0pt">
13571 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
13572 <row topline="true" bottomline="true">
13573 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13574 \begin_inset Text
13575
13576 \layout Standard
13577
13578 Name
13579 \end_inset
13580 </cell>
13581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13582 \begin_inset Text
13583
13584 \layout Standard
13585
13586 Subject / Title
13587 \end_inset
13588 </cell>
13589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13590 \begin_inset Text
13591
13592 \layout Standard
13593
13594 Where to get
13595 \end_inset
13596 </cell>
13597 </row>
13598 <row topline="true">
13599 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13600 \begin_inset Text
13601
13602 \layout Standard
13603
13604 S.
13605  S.
13606  Muchnick
13607 \end_inset
13608 </cell>
13609 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13610 \begin_inset Text
13611
13612 \layout Standard
13613
13614 Advanced Compiler Design and Implementation
13615 \end_inset
13616 </cell>
13617 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13618 \begin_inset Text
13619
13620 \layout Standard
13621
13622 bookstore
13623 \end_inset
13624 </cell>
13625 </row>
13626 <row topline="true">
13627 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13628 \begin_inset Text
13629
13630 \layout Standard
13631
13632
13633 \family roman
13634 \series medium
13635 \shape up
13636 \size normal
13637 \emph off
13638 \bar no
13639 \noun off
13640 \color none
13641 c-refcard.pdf
13642 \end_inset
13643 </cell>
13644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13645 \begin_inset Text
13646
13647 \layout Standard
13648
13649 C Reference Card
13650 \begin_inset LatexCommand \index{C Reference card}
13651
13652 \end_inset
13653
13654 , 2 pages
13655 \end_inset
13656 </cell>
13657 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13658 \begin_inset Text
13659
13660 \layout Standard
13661
13662
13663 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
13664
13665 \end_inset
13666
13667
13668 \end_inset
13669 </cell>
13670 </row>
13671 <row topline="true">
13672 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13673 \begin_inset Text
13674
13675 \layout Standard
13676
13677 test_suite_spec.pdf
13678 \end_inset
13679 </cell>
13680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13681 \begin_inset Text
13682
13683 \layout Standard
13684
13685 sdcc regression test
13686 \begin_inset LatexCommand \index{Regression test}
13687
13688 \end_inset
13689
13690
13691 \end_inset
13692 </cell>
13693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13694 \begin_inset Text
13695
13696 \layout Standard
13697
13698 sdcc/doc
13699 \end_inset
13700 </cell>
13701 </row>
13702 <row topline="true" bottomline="true">
13703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13704 \begin_inset Text
13705
13706 \layout Standard
13707
13708
13709 \family roman
13710 \series medium
13711 \shape up
13712 \size normal
13713 \emph off
13714 \bar no
13715 \noun off
13716 \color none
13717 cdbfileformat.pd
13718 \family default
13719 \series default
13720 \shape default
13721 \size default
13722 \emph default
13723 \bar default
13724 \noun default
13725 \color default
13726 f
13727 \end_inset
13728 </cell>
13729 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13730 \begin_inset Text
13731
13732 \layout Standard
13733
13734 sdcc internal documentation
13735 \end_inset
13736 </cell>
13737 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13738 \begin_inset Text
13739
13740 \layout Standard
13741
13742 sdcc/doc
13743 \end_inset
13744 </cell>
13745 </row>
13746 </lyxtabular>
13747
13748 \end_inset
13749
13750
13751 \newline
13752
13753 \layout Section
13754 \pagebreak_top
13755 Retargetting for other MCUs.
13756 \layout Standard
13757
13758 The issues for retargetting the compiler are far too numerous to be covered
13759  by this document.
13760  What follows is a brief description of each of the seven phases of the
13761  compiler and its MCU dependency.
13762 \layout Itemize
13763
13764 Parsing the source and building the annotated parse tree.
13765  This phase is largely MCU independent (except for the language extensions).
13766  Syntax & semantic checks are also done in this phase, along with some initial
13767  optimizations like back patching labels and the pattern matching optimizations
13768  like bit-rotation etc.
13769 \layout Itemize
13770
13771 The second phase involves generating an intermediate code which can be easy
13772  manipulated during the later phases.
13773  This phase is entirely MCU independent.
13774  The intermediate code generation assumes the target machine has unlimited
13775  number of registers, and designates them with the name iTemp.
13776  The compiler can be made to dump a human readable form of the code generated
13777  by using the -
13778 \begin_inset ERT
13779 status Collapsed
13780
13781 \layout Standard
13782
13783 \backslash
13784 /
13785 \end_inset
13786
13787 -dumpraw option.
13788 \layout Itemize
13789
13790 This phase does the bulk of the standard optimizations and is also MCU independe
13791 nt.
13792  This phase can be broken down into several sub-phases:
13793 \newline
13794
13795 \newline
13796 Break down intermediate code (iCode) into basic blocks.
13797 \newline
13798 Do control flow & data flow analysis on the basic blocks.
13799 \newline
13800 Do local common subexpression elimination, then global subexpression elimination
13801 \newline
13802 Dead code elimination
13803 \newline
13804 Loop optimizations
13805 \newline
13806 If loop optimizations caused any changes then do 'global subexpression eliminati
13807 on' and 'dead code elimination' again.
13808 \layout Itemize
13809
13810 This phase determines the live-ranges; by live range I mean those iTemp
13811  variables defined by the compiler that still survive after all the optimization
13812 s.
13813  Live range analysis
13814 \begin_inset LatexCommand \index{Live range analysis}
13815
13816 \end_inset
13817
13818  is essential for register allocation, since these computation determines
13819  which of these iTemps will be assigned to registers, and for how long.
13820 \layout Itemize
13821
13822 Phase five is register allocation.
13823  There are two parts to this process.
13824 \newline
13825
13826 \newline
13827 The first part I call 'register packing' (for lack of a better term).
13828  In this case several MCU specific expression folding is done to reduce
13829  register pressure.
13830 \newline
13831
13832 \newline
13833 The second part is more MCU independent and deals with allocating registers
13834  to the remaining live ranges.
13835  A lot of MCU specific code does creep into this phase because of the limited
13836  number of index registers available in the 8051.
13837 \layout Itemize
13838
13839 The Code generation phase is (unhappily), entirely MCU dependent and very
13840  little (if any at all) of this code can be reused for other MCU.
13841  However the scheme for allocating a homogenized assembler operand for each
13842  iCode operand may be reused.
13843 \layout Itemize
13844
13845 As mentioned in the optimization section the peep-hole optimizer is rule
13846  based system, which can reprogrammed for other MCUs.
13847 \layout Section
13848 \pagebreak_top
13849 SDCDB
13850 \begin_inset LatexCommand \index{sdcdb}
13851
13852 \end_inset
13853
13854  - Source Level Debugger
13855 \begin_inset LatexCommand \index{Debugger}
13856
13857 \end_inset
13858
13859
13860 \layout Standard
13861
13862 SDCC is distributed with a source level debugger.
13863  The debugger uses a command line interface, the command repertoire of the
13864  debugger has been kept as close to gdb
13865 \begin_inset LatexCommand \index{gdb}
13866
13867 \end_inset
13868
13869  (the GNU debugger) as possible.
13870  The configuration and build process is part of the standard compiler installati
13871 on, which also builds and installs the debugger in the target directory
13872  specified during configuration.
13873  The debugger allows you debug BOTH at the C source and at the ASM source
13874  level.
13875 \layout Subsection
13876
13877 Compiling for Debugging
13878 \layout Standard
13879
13880 The \SpecialChar \-
13881 \SpecialChar \-
13882 debug option must be specified for all files for which debug information
13883  is to be generated.
13884  The complier generates a .adb file for each of these files.
13885  The linker creates the .cdb file from the .adb files and the address information.
13886  This .cdb is used by the debugger.
13887 \layout Subsection
13888
13889 How the Debugger Works
13890 \layout Standard
13891
13892 When the -
13893 \begin_inset ERT
13894 status Collapsed
13895
13896 \layout Standard
13897
13898 \backslash
13899 /
13900 \end_inset
13901
13902 -debug option is specified the compiler generates extra symbol information
13903  some of which are put into the the assembler source and some are put into
13904  the .adb file.
13905   Then the linker creates the .cdb file from the individual .adb files with
13906  the address information for the symbols.
13907  The debugger reads the symbolic information generated by the compiler &
13908  the address information generated by the linker.
13909  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
13910  execution is controlled by the debugger.
13911  When a command is issued for the debugger, it translates it into appropriate
13912  commands for the simulator.
13913 \layout Subsection
13914
13915 Starting the Debugger
13916 \layout Standard
13917
13918 The debugger can be started using the following command line.
13919  (Assume the file you are debugging has the file name foo).
13920 \newline
13921
13922 \newline
13923
13924 \family sans
13925 \series bold
13926 sdcdb foo
13927 \newline
13928
13929 \family default
13930 \series default
13931
13932 \newline
13933 The debugger will look for the following files.
13934 \layout Itemize
13935
13936 foo.c - the source file.
13937 \layout Itemize
13938
13939 foo.cdb - the debugger symbol information file.
13940 \layout Itemize
13941
13942 foo.ihx - the Intel hex format
13943 \begin_inset LatexCommand \index{Intel hex format}
13944
13945 \end_inset
13946
13947  object file.
13948 \layout Subsection
13949
13950 Command Line Options.
13951 \layout Itemize
13952
13953 -
13954 \begin_inset ERT
13955 status Collapsed
13956
13957 \layout Standard
13958
13959 \backslash
13960 /
13961 \end_inset
13962
13963 -directory=<source file directory> this option can used to specify the directory
13964  search list.
13965  The debugger will look into the directory list specified for source, cdb
13966  & ihx files.
13967  The items in the directory list must be separated by ':', e.g.
13968  if the source files can be in the directories /home/src1 and /home/src2,
13969  the -
13970 \begin_inset ERT
13971 status Collapsed
13972
13973 \layout Standard
13974
13975 \backslash
13976 /
13977 \end_inset
13978
13979 -directory option should be -
13980 \begin_inset ERT
13981 status Collapsed
13982
13983 \layout Standard
13984
13985 \backslash
13986 /
13987 \end_inset
13988
13989 -directory=/home/src1:/home/src2.
13990  Note there can be no spaces in the option.
13991
13992 \layout Itemize
13993
13994 -cd <directory> - change to the <directory>.
13995 \layout Itemize
13996
13997 -fullname - used by GUI front ends.
13998 \layout Itemize
13999
14000 -cpu <cpu-type> - this argument is passed to the simulator please see the
14001  simulator docs for details.
14002 \layout Itemize
14003
14004 -X <Clock frequency > this options is passed to the simulator please see
14005  the simulator docs for details.
14006 \layout Itemize
14007
14008 -s <serial port file> passed to simulator see the simulator docs for details.
14009 \layout Itemize
14010
14011 -S <serial in,out> passed to simulator see the simulator docs for details.
14012 \layout Subsection
14013
14014 Debugger Commands.
14015 \layout Standard
14016
14017 As mention earlier the command interface for the debugger has been deliberately
14018  kept as close the GNU debugger gdb, as possible.
14019  This will help the integration with existing graphical user interfaces
14020  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
14021 \layout Subsubsection
14022
14023 break [line | file:line | function | file:function]
14024 \layout Standard
14025
14026 Set breakpoint at specified line or function:
14027 \newline
14028
14029 \newline
14030
14031 \family sans
14032 \series bold
14033 sdcdb>break 100
14034 \newline
14035 sdcdb>break foo.c:100
14036 \newline
14037 sdcdb>break funcfoo
14038 \newline
14039 sdcdb>break foo.c:funcfoo
14040 \layout Subsubsection
14041
14042 clear [line | file:line | function | file:function ]
14043 \layout Standard
14044
14045 Clear breakpoint at specified line or function:
14046 \newline
14047
14048 \newline
14049
14050 \family sans
14051 \series bold
14052 sdcdb>clear 100
14053 \newline
14054 sdcdb>clear foo.c:100
14055 \newline
14056 sdcdb>clear funcfoo
14057 \newline
14058 sdcdb>clear foo.c:funcfoo
14059 \layout Subsubsection
14060
14061 continue
14062 \layout Standard
14063
14064 Continue program being debugged, after breakpoint.
14065 \layout Subsubsection
14066
14067 finish
14068 \layout Standard
14069
14070 Execute till the end of the current function.
14071 \layout Subsubsection
14072
14073 delete [n]
14074 \layout Standard
14075
14076 Delete breakpoint number 'n'.
14077  If used without any option clear ALL user defined break points.
14078 \layout Subsubsection
14079
14080 info [break | stack | frame | registers ]
14081 \layout Itemize
14082
14083 info break - list all breakpoints
14084 \layout Itemize
14085
14086 info stack - show the function call stack.
14087 \layout Itemize
14088
14089 info frame - show information about the current execution frame.
14090 \layout Itemize
14091
14092 info registers - show content of all registers.
14093 \layout Subsubsection
14094
14095 step
14096 \layout Standard
14097
14098 Step program until it reaches a different source line.
14099 \layout Subsubsection
14100
14101 next
14102 \layout Standard
14103
14104 Step program, proceeding through subroutine calls.
14105 \layout Subsubsection
14106
14107 run
14108 \layout Standard
14109
14110 Start debugged program.
14111 \layout Subsubsection
14112
14113 ptype variable
14114 \layout Standard
14115
14116 Print type information of the variable.
14117 \layout Subsubsection
14118
14119 print variable
14120 \layout Standard
14121
14122 print value of variable.
14123 \layout Subsubsection
14124
14125 file filename
14126 \layout Standard
14127
14128 load the given file name.
14129  Note this is an alternate method of loading file for debugging.
14130 \layout Subsubsection
14131
14132 frame
14133 \layout Standard
14134
14135 print information about current frame.
14136 \layout Subsubsection
14137
14138 set srcmode
14139 \layout Standard
14140
14141 Toggle between C source & assembly source.
14142 \layout Subsubsection
14143
14144 ! simulator command
14145 \layout Standard
14146
14147 Send the string following '!' to the simulator, the simulator response is
14148  displayed.
14149  Note the debugger does not interpret the command being sent to the simulator,
14150  so if a command like 'go' is sent the debugger can loose its execution
14151  context and may display incorrect values.
14152 \layout Subsubsection
14153
14154 quit.
14155 \layout Standard
14156
14157 "Watch me now.
14158  Iam going Down.
14159  My name is Bobby Brown"
14160 \layout Subsection
14161
14162 Interfacing with XEmacs
14163 \begin_inset LatexCommand \index{XEmacs}
14164
14165 \end_inset
14166
14167
14168 \begin_inset LatexCommand \index{Emacs}
14169
14170 \end_inset
14171
14172 .
14173 \layout Standard
14174
14175 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
14176  sdcdb.el and sdcdbsrc.el.
14177  These two files can be found in the $(prefix)/bin directory after the installat
14178 ion is complete.
14179  These files need to be loaded into XEmacs for the interface to work.
14180  This can be done at XEmacs startup time by inserting the following into
14181  your '.xemacs' file (which can be found in your HOME directory):
14182 \newline
14183
14184 \newline
14185
14186 \family typewriter
14187 (load-file sdcdbsrc.el)
14188 \family default
14189
14190 \newline
14191
14192 \newline
14193 .xemacs is a lisp file so the () around the command is REQUIRED.
14194  The files can also be loaded dynamically while XEmacs is running, set the
14195  environment variable 'EMACSLOADPATH' to the installation bin directory
14196  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
14197  To start the interface enter the following command:
14198 \newline
14199
14200 \newline
14201
14202 \family sans
14203 \series bold
14204 ESC-x sdcdbsrc
14205 \family default
14206 \series default
14207
14208 \newline
14209
14210 \newline
14211 You will prompted to enter the file name to be debugged.
14212
14213 \newline
14214
14215 \newline
14216 The command line options that are passed to the simulator directly are bound
14217  to default values in the file sdcdbsrc.el.
14218  The variables are listed below, these values maybe changed as required.
14219 \layout Itemize
14220
14221 sdcdbsrc-cpu-type '51
14222 \layout Itemize
14223
14224 sdcdbsrc-frequency '11059200
14225 \layout Itemize
14226
14227 sdcdbsrc-serial nil
14228 \layout Standard
14229
14230 The following is a list of key mapping for the debugger interface.
14231 \layout Standard
14232
14233 \SpecialChar ~
14234
14235 \family typewriter
14236
14237 \newline
14238 ;; Current Listing ::
14239 \newline
14240 ;;key\SpecialChar ~
14241 \SpecialChar ~
14242 \SpecialChar ~
14243 \SpecialChar ~
14244 \SpecialChar ~
14245 \SpecialChar ~
14246 \SpecialChar ~
14247 \SpecialChar ~
14248 \SpecialChar ~
14249 \SpecialChar ~
14250 \SpecialChar ~
14251 \SpecialChar ~
14252 \SpecialChar ~
14253 \SpecialChar ~
14254 \SpecialChar ~
14255 binding\SpecialChar ~
14256 \SpecialChar ~
14257 \SpecialChar ~
14258 \SpecialChar ~
14259 \SpecialChar ~
14260 \SpecialChar ~
14261 \SpecialChar ~
14262 \SpecialChar ~
14263 \SpecialChar ~
14264 \SpecialChar ~
14265 \SpecialChar ~
14266 \SpecialChar ~
14267 \SpecialChar ~
14268 \SpecialChar ~
14269 \SpecialChar ~
14270 \SpecialChar ~
14271 \SpecialChar ~
14272 \SpecialChar ~
14273 \SpecialChar ~
14274 \SpecialChar ~
14275 \SpecialChar ~
14276 \SpecialChar ~
14277 Comment
14278 \newline
14279 ;;---\SpecialChar ~
14280 \SpecialChar ~
14281 \SpecialChar ~
14282 \SpecialChar ~
14283 \SpecialChar ~
14284 \SpecialChar ~
14285 \SpecialChar ~
14286 \SpecialChar ~
14287 \SpecialChar ~
14288 \SpecialChar ~
14289 \SpecialChar ~
14290 \SpecialChar ~
14291 \SpecialChar ~
14292 \SpecialChar ~
14293 \SpecialChar ~
14294 ------\SpecialChar ~
14295 \SpecialChar ~
14296 \SpecialChar ~
14297 \SpecialChar ~
14298 \SpecialChar ~
14299 \SpecialChar ~
14300 \SpecialChar ~
14301 \SpecialChar ~
14302 \SpecialChar ~
14303 \SpecialChar ~
14304 \SpecialChar ~
14305 \SpecialChar ~
14306 \SpecialChar ~
14307 \SpecialChar ~
14308 \SpecialChar ~
14309 \SpecialChar ~
14310 \SpecialChar ~
14311 \SpecialChar ~
14312 \SpecialChar ~
14313 \SpecialChar ~
14314 \SpecialChar ~
14315 \SpecialChar ~
14316 --------
14317 \newline
14318 ;;
14319 \newline
14320 ;; n\SpecialChar ~
14321 \SpecialChar ~
14322 \SpecialChar ~
14323 \SpecialChar ~
14324 \SpecialChar ~
14325 \SpecialChar ~
14326 \SpecialChar ~
14327 \SpecialChar ~
14328 \SpecialChar ~
14329 \SpecialChar ~
14330 \SpecialChar ~
14331 \SpecialChar ~
14332 \SpecialChar ~
14333 \SpecialChar ~
14334  sdcdb-next-from-src\SpecialChar ~
14335 \SpecialChar ~
14336 \SpecialChar ~
14337 \SpecialChar ~
14338 \SpecialChar ~
14339 \SpecialChar ~
14340 \SpecialChar ~
14341 \SpecialChar ~
14342 \SpecialChar ~
14343 \SpecialChar ~
14344 SDCDB next command
14345 \newline
14346 ;; b\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  sdcdb-back-from-src\SpecialChar ~
14361 \SpecialChar ~
14362 \SpecialChar ~
14363 \SpecialChar ~
14364 \SpecialChar ~
14365 \SpecialChar ~
14366 \SpecialChar ~
14367 \SpecialChar ~
14368 \SpecialChar ~
14369 \SpecialChar ~
14370 SDCDB back command
14371 \newline
14372 ;; c\SpecialChar ~
14373 \SpecialChar ~
14374 \SpecialChar ~
14375 \SpecialChar ~
14376 \SpecialChar ~
14377 \SpecialChar ~
14378 \SpecialChar ~
14379 \SpecialChar ~
14380 \SpecialChar ~
14381 \SpecialChar ~
14382 \SpecialChar ~
14383 \SpecialChar ~
14384 \SpecialChar ~
14385 \SpecialChar ~
14386  sdcdb-cont-from-src\SpecialChar ~
14387 \SpecialChar ~
14388 \SpecialChar ~
14389 \SpecialChar ~
14390 \SpecialChar ~
14391 \SpecialChar ~
14392 \SpecialChar ~
14393 \SpecialChar ~
14394 \SpecialChar ~
14395 \SpecialChar ~
14396 SDCDB continue command
14397 \newline
14398 ;; s\SpecialChar ~
14399 \SpecialChar ~
14400 \SpecialChar ~
14401 \SpecialChar ~
14402 \SpecialChar ~
14403 \SpecialChar ~
14404 \SpecialChar ~
14405 \SpecialChar ~
14406 \SpecialChar ~
14407 \SpecialChar ~
14408 \SpecialChar ~
14409 \SpecialChar ~
14410 \SpecialChar ~
14411 \SpecialChar ~
14412  sdcdb-step-from-src\SpecialChar ~
14413 \SpecialChar ~
14414 \SpecialChar ~
14415 \SpecialChar ~
14416 \SpecialChar ~
14417 \SpecialChar ~
14418 \SpecialChar ~
14419 \SpecialChar ~
14420 \SpecialChar ~
14421 \SpecialChar ~
14422 SDCDB step command
14423 \newline
14424 ;; ?\SpecialChar ~
14425 \SpecialChar ~
14426 \SpecialChar ~
14427 \SpecialChar ~
14428 \SpecialChar ~
14429 \SpecialChar ~
14430 \SpecialChar ~
14431 \SpecialChar ~
14432 \SpecialChar ~
14433 \SpecialChar ~
14434 \SpecialChar ~
14435 \SpecialChar ~
14436 \SpecialChar ~
14437 \SpecialChar ~
14438  sdcdb-whatis-c-sexp\SpecialChar ~
14439 \SpecialChar ~
14440 \SpecialChar ~
14441 \SpecialChar ~
14442 \SpecialChar ~
14443 \SpecialChar ~
14444 \SpecialChar ~
14445 \SpecialChar ~
14446 \SpecialChar ~
14447 \SpecialChar ~
14448 SDCDB ptypecommand for data at
14449 \newline
14450 ;;\SpecialChar ~
14451 \SpecialChar ~
14452 \SpecialChar ~
14453 \SpecialChar ~
14454 \SpecialChar ~
14455 \SpecialChar ~
14456 \SpecialChar ~
14457 \SpecialChar ~
14458 \SpecialChar ~
14459 \SpecialChar ~
14460 \SpecialChar ~
14461 \SpecialChar ~
14462 \SpecialChar ~
14463 \SpecialChar ~
14464 \SpecialChar ~
14465 \SpecialChar ~
14466 \SpecialChar ~
14467 \SpecialChar ~
14468 \SpecialChar ~
14469 \SpecialChar ~
14470 \SpecialChar ~
14471 \SpecialChar ~
14472 \SpecialChar ~
14473 \SpecialChar ~
14474 \SpecialChar ~
14475 \SpecialChar ~
14476 \SpecialChar ~
14477 \SpecialChar ~
14478 \SpecialChar ~
14479 \SpecialChar ~
14480 \SpecialChar ~
14481 \SpecialChar ~
14482 \SpecialChar ~
14483 \SpecialChar ~
14484 \SpecialChar ~
14485 \SpecialChar ~
14486 \SpecialChar ~
14487 \SpecialChar ~
14488 \SpecialChar ~
14489 \SpecialChar ~
14490 \SpecialChar ~
14491 \SpecialChar ~
14492 \SpecialChar ~
14493 \SpecialChar ~
14494 \SpecialChar ~
14495 \SpecialChar ~
14496  buffer point
14497 \newline
14498 ;; x\SpecialChar ~
14499 \SpecialChar ~
14500 \SpecialChar ~
14501 \SpecialChar ~
14502 \SpecialChar ~
14503 \SpecialChar ~
14504 \SpecialChar ~
14505 \SpecialChar ~
14506 \SpecialChar ~
14507 \SpecialChar ~
14508 \SpecialChar ~
14509 \SpecialChar ~
14510 \SpecialChar ~
14511 \SpecialChar ~
14512  sdcdbsrc-delete\SpecialChar ~
14513 \SpecialChar ~
14514 \SpecialChar ~
14515 \SpecialChar ~
14516 \SpecialChar ~
14517 \SpecialChar ~
14518 \SpecialChar ~
14519 \SpecialChar ~
14520 \SpecialChar ~
14521 \SpecialChar ~
14522 \SpecialChar ~
14523 \SpecialChar ~
14524 \SpecialChar ~
14525 \SpecialChar ~
14526 SDCDB Delete all breakpoints if no arg
14527 \newline
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 \SpecialChar ~
14564 \SpecialChar ~
14565 \SpecialChar ~
14566 \SpecialChar ~
14567 \SpecialChar ~
14568 \SpecialChar ~
14569 \SpecialChar ~
14570 \SpecialChar ~
14571 \SpecialChar ~
14572 \SpecialChar ~
14573 \SpecialChar ~
14574 given or delete arg (C-u arg x)
14575 \newline
14576 ;; m\SpecialChar ~
14577 \SpecialChar ~
14578 \SpecialChar ~
14579 \SpecialChar ~
14580 \SpecialChar ~
14581 \SpecialChar ~
14582 \SpecialChar ~
14583 \SpecialChar ~
14584 \SpecialChar ~
14585 \SpecialChar ~
14586 \SpecialChar ~
14587 \SpecialChar ~
14588 \SpecialChar ~
14589 \SpecialChar ~
14590  sdcdbsrc-frame\SpecialChar ~
14591 \SpecialChar ~
14592 \SpecialChar ~
14593 \SpecialChar ~
14594 \SpecialChar ~
14595 \SpecialChar ~
14596 \SpecialChar ~
14597 \SpecialChar ~
14598 \SpecialChar ~
14599 \SpecialChar ~
14600 \SpecialChar ~
14601 \SpecialChar ~
14602 \SpecialChar ~
14603 \SpecialChar ~
14604 \SpecialChar ~
14605 SDCDB Display current frame if no arg,
14606 \newline
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 \SpecialChar ~
14642 \SpecialChar ~
14643 \SpecialChar ~
14644 \SpecialChar ~
14645 \SpecialChar ~
14646 \SpecialChar ~
14647 \SpecialChar ~
14648 \SpecialChar ~
14649 \SpecialChar ~
14650 \SpecialChar ~
14651 \SpecialChar ~
14652 \SpecialChar ~
14653 \SpecialChar ~
14654 given or display frame arg
14655 \newline
14656 ;;\SpecialChar ~
14657 \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 \SpecialChar ~
14673 \SpecialChar ~
14674 \SpecialChar ~
14675 \SpecialChar ~
14676 \SpecialChar ~
14677 \SpecialChar ~
14678 \SpecialChar ~
14679 \SpecialChar ~
14680 \SpecialChar ~
14681 \SpecialChar ~
14682 \SpecialChar ~
14683 \SpecialChar ~
14684 \SpecialChar ~
14685 \SpecialChar ~
14686 \SpecialChar ~
14687 \SpecialChar ~
14688 \SpecialChar ~
14689 \SpecialChar ~
14690 \SpecialChar ~
14691 \SpecialChar ~
14692 \SpecialChar ~
14693 \SpecialChar ~
14694 \SpecialChar ~
14695 \SpecialChar ~
14696 \SpecialChar ~
14697 \SpecialChar ~
14698 \SpecialChar ~
14699 \SpecialChar ~
14700 \SpecialChar ~
14701 \SpecialChar ~
14702 \SpecialChar ~
14703 buffer point
14704 \newline
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  sdcdbsrc-goto-sdcdb\SpecialChar ~
14720 \SpecialChar ~
14721 \SpecialChar ~
14722 \SpecialChar ~
14723 \SpecialChar ~
14724 \SpecialChar ~
14725 \SpecialChar ~
14726 \SpecialChar ~
14727 \SpecialChar ~
14728 \SpecialChar ~
14729 Goto the SDCDB output buffer
14730 \newline
14731 ;; p\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  sdcdb-print-c-sexp\SpecialChar ~
14746 \SpecialChar ~
14747 \SpecialChar ~
14748 \SpecialChar ~
14749 \SpecialChar ~
14750 \SpecialChar ~
14751 \SpecialChar ~
14752 \SpecialChar ~
14753 \SpecialChar ~
14754 \SpecialChar ~
14755 \SpecialChar ~
14756 SDCDB print command for data at
14757 \newline
14758 ;;\SpecialChar ~
14759 \SpecialChar ~
14760 \SpecialChar ~
14761 \SpecialChar ~
14762 \SpecialChar ~
14763 \SpecialChar ~
14764 \SpecialChar ~
14765 \SpecialChar ~
14766 \SpecialChar ~
14767 \SpecialChar ~
14768 \SpecialChar ~
14769 \SpecialChar ~
14770 \SpecialChar ~
14771 \SpecialChar ~
14772 \SpecialChar ~
14773 \SpecialChar ~
14774 \SpecialChar ~
14775 \SpecialChar ~
14776 \SpecialChar ~
14777 \SpecialChar ~
14778 \SpecialChar ~
14779 \SpecialChar ~
14780 \SpecialChar ~
14781 \SpecialChar ~
14782 \SpecialChar ~
14783 \SpecialChar ~
14784 \SpecialChar ~
14785 \SpecialChar ~
14786 \SpecialChar ~
14787 \SpecialChar ~
14788 \SpecialChar ~
14789 \SpecialChar ~
14790 \SpecialChar ~
14791 \SpecialChar ~
14792 \SpecialChar ~
14793 \SpecialChar ~
14794 \SpecialChar ~
14795 \SpecialChar ~
14796 \SpecialChar ~
14797 \SpecialChar ~
14798 \SpecialChar ~
14799 \SpecialChar ~
14800 \SpecialChar ~
14801 \SpecialChar ~
14802 \SpecialChar ~
14803 \SpecialChar ~
14804  buffer point
14805 \newline
14806 ;; g\SpecialChar ~
14807 \SpecialChar ~
14808 \SpecialChar ~
14809 \SpecialChar ~
14810 \SpecialChar ~
14811 \SpecialChar ~
14812 \SpecialChar ~
14813 \SpecialChar ~
14814 \SpecialChar ~
14815 \SpecialChar ~
14816 \SpecialChar ~
14817 \SpecialChar ~
14818 \SpecialChar ~
14819 \SpecialChar ~
14820  sdcdbsrc-goto-sdcdb\SpecialChar ~
14821 \SpecialChar ~
14822 \SpecialChar ~
14823 \SpecialChar ~
14824 \SpecialChar ~
14825 \SpecialChar ~
14826 \SpecialChar ~
14827 \SpecialChar ~
14828 \SpecialChar ~
14829 \SpecialChar ~
14830 Goto the SDCDB output buffer
14831 \newline
14832 ;; t\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  sdcdbsrc-mode\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 Toggles Sdcdbsrc mode (turns it off)
14863 \newline
14864 ;;
14865 \newline
14866 ;; C-c C-f\SpecialChar ~
14867 \SpecialChar ~
14868 \SpecialChar ~
14869 \SpecialChar ~
14870 \SpecialChar ~
14871 \SpecialChar ~
14872 \SpecialChar ~
14873 \SpecialChar ~
14874  sdcdb-finish-from-src\SpecialChar ~
14875 \SpecialChar ~
14876 \SpecialChar ~
14877 \SpecialChar ~
14878 \SpecialChar ~
14879 \SpecialChar ~
14880 \SpecialChar ~
14881 \SpecialChar ~
14882 SDCDB finish command
14883 \newline
14884 ;;
14885 \newline
14886 ;; C-x SPC\SpecialChar ~
14887 \SpecialChar ~
14888 \SpecialChar ~
14889 \SpecialChar ~
14890 \SpecialChar ~
14891 \SpecialChar ~
14892 \SpecialChar ~
14893 \SpecialChar ~
14894  sdcdb-break\SpecialChar ~
14895 \SpecialChar ~
14896 \SpecialChar ~
14897 \SpecialChar ~
14898 \SpecialChar ~
14899 \SpecialChar ~
14900 \SpecialChar ~
14901 \SpecialChar ~
14902 \SpecialChar ~
14903 \SpecialChar ~
14904 \SpecialChar ~
14905 \SpecialChar ~
14906 \SpecialChar ~
14907 \SpecialChar ~
14908 \SpecialChar ~
14909 \SpecialChar ~
14910 \SpecialChar ~
14911 \SpecialChar ~
14912 Set break for line with point
14913 \newline
14914 ;; ESC t\SpecialChar ~
14915 \SpecialChar ~
14916 \SpecialChar ~
14917 \SpecialChar ~
14918 \SpecialChar ~
14919 \SpecialChar ~
14920 \SpecialChar ~
14921 \SpecialChar ~
14922 \SpecialChar ~
14923 \SpecialChar ~
14924  sdcdbsrc-mode\SpecialChar ~
14925 \SpecialChar ~
14926 \SpecialChar ~
14927 \SpecialChar ~
14928 \SpecialChar ~
14929 \SpecialChar ~
14930 \SpecialChar ~
14931 \SpecialChar ~
14932 \SpecialChar ~
14933 \SpecialChar ~
14934 \SpecialChar ~
14935 \SpecialChar ~
14936 \SpecialChar ~
14937 \SpecialChar ~
14938 \SpecialChar ~
14939 \SpecialChar ~
14940 Toggle Sdcdbsrc mode
14941 \newline
14942 ;; ESC m\SpecialChar ~
14943 \SpecialChar ~
14944 \SpecialChar ~
14945 \SpecialChar ~
14946 \SpecialChar ~
14947 \SpecialChar ~
14948 \SpecialChar ~
14949 \SpecialChar ~
14950 \SpecialChar ~
14951 \SpecialChar ~
14952  sdcdbsrc-srcmode\SpecialChar ~
14953 \SpecialChar ~
14954 \SpecialChar ~
14955 \SpecialChar ~
14956 \SpecialChar ~
14957 \SpecialChar ~
14958 \SpecialChar ~
14959 \SpecialChar ~
14960 \SpecialChar ~
14961 \SpecialChar ~
14962 \SpecialChar ~
14963 \SpecialChar ~
14964  Toggle list mode
14965 \newline
14966 ;;
14967 \family default
14968
14969 \newline
14970
14971 \layout Section
14972
14973 Other Processors
14974 \layout Subsection
14975
14976 The Z80 and gbz80 port
14977 \layout Standard
14978
14979 SDCC can target both the Zilog Z80 and the Nintendo Gameboy's Z80-like gbz80.
14980  The port is incomplete - long support is incomplete (mul, div and mod are
14981  unimplemented), and both float and bitfield support is missing.
14982  Apart from that the code generated is correct.
14983 \layout Standard
14984
14985 As always, the code is the authoritave reference - see z80/ralloc.c and z80/gen.c.
14986  The stack frame is similar to that generated by the IAR Z80 compiler.
14987  IX is used as the base pointer, HL is used as a temporary register, and
14988  BC and DE are available for holding variables.
14989  IY is currently unused.
14990  Return values are stored in HL.
14991  One bad side effect of using IX as the base pointer is that a functions
14992  stack frame is limited to 127 bytes - this will be fixed in a later version.
14993 \layout Section
14994 \pagebreak_top
14995 Support
14996 \begin_inset LatexCommand \index{Support}
14997
14998 \end_inset
14999
15000
15001 \layout Standard
15002
15003 SDCC has grown to be a large project.
15004  The compiler alone (without the preprocessor, assembler and linker) is
15005  about 40,000 lines of code (blank stripped).
15006  The open source nature of this project is a key to its continued growth
15007  and support.
15008  You gain the benefit and support of many active software developers and
15009  end users.
15010  Is SDCC perfect? No, that's why we need your help.
15011  The developers take pride in fixing reported bugs.
15012  You can help by reporting the bugs and helping other SDCC users.
15013  There are lots of ways to contribute, and we encourage you to take part
15014  in making SDCC a great software package.
15015
15016 \layout Standard
15017
15018 The SDCC project is hosted on the sdcc sourceforge site at
15019 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
15020
15021 \end_inset
15022
15023 .
15024  You'll find the complete set of mailing lists
15025 \begin_inset LatexCommand \index{Mailing list}
15026
15027 \end_inset
15028
15029 , forums, bug reporting system, patch submission
15030 \begin_inset LatexCommand \index{Patch submission}
15031
15032 \end_inset
15033
15034  system, download
15035 \begin_inset LatexCommand \index{download}
15036
15037 \end_inset
15038
15039  area and cvs code repository
15040 \begin_inset LatexCommand \index{cvs code repository}
15041
15042 \end_inset
15043
15044  there.
15045 \layout Subsection
15046
15047 Reporting Bugs
15048 \begin_inset LatexCommand \index{Bugs}
15049
15050 \end_inset
15051
15052
15053 \begin_inset LatexCommand \index{Reporting bugs}
15054
15055 \end_inset
15056
15057
15058 \layout Standard
15059
15060 The recommended way of reporting bugs is using the infrastructure of the
15061  sourceforge site.
15062  You can follow the status of bug reports there and have an overview about
15063  the known bugs.
15064 \layout Standard
15065
15066 Bug reports are automatically forwarded to the developer mailing list and
15067  will be fixed ASAP.
15068  When reporting a bug, it is very useful to include a small test program
15069  (the smaller the better) which reproduces the problem.
15070  If you can isolate the problem by looking at the generated assembly code,
15071  this can be very helpful.
15072  Compiling your program with the -
15073 \begin_inset ERT
15074 status Collapsed
15075
15076 \layout Standard
15077
15078 \backslash
15079 /
15080 \end_inset
15081
15082 -dumpall
15083 \begin_inset LatexCommand \index{-\/-dumpall}
15084
15085 \end_inset
15086
15087  option can sometimes be useful in locating optimization problems.
15088  When reporting a bug please maker sure you:
15089 \layout Enumerate
15090
15091 Attach the code you are compiling with SDCC.
15092
15093 \layout Enumerate
15094
15095 Specify the exact command you use to run SDCC, or attach your Makefile.
15096
15097 \layout Enumerate
15098
15099 Specify the SDCC version (type "sdcc -v"), your platform, and operating
15100  system.
15101
15102 \layout Enumerate
15103
15104 Provide an exact copy of any error message or incorrect output.
15105
15106 \layout Enumerate
15107
15108 Put something meaningful in the subject of your message.
15109 \layout Standard
15110
15111 Please attempt to include these 5 important parts, as applicable, in all
15112  requests for support or when reporting any problems or bugs with SDCC.
15113  Though this will make your message lengthy, it will greatly improve your
15114  chance that SDCC users and developers will be able to help you.
15115  Some SDCC developers are frustrated by bug reports without code provided
15116  that they can use to reproduce and ultimately fix the problem, so please
15117  be sure to provide sample code if you are reporting a bug!
15118 \layout Standard
15119
15120 Please have a short check that you are using a recent version of SDCC and
15121  the bug is not yet known.
15122  This is the link for reporting bugs:
15123 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
15124
15125 \end_inset
15126
15127 .
15128 \layout Subsection
15129
15130 Requesting Features
15131 \begin_inset LatexCommand \index{Feature request}
15132
15133 \end_inset
15134
15135
15136 \begin_inset LatexCommand \index{Requesting features}
15137
15138 \end_inset
15139
15140
15141 \layout Standard
15142
15143 Like bug reports feature requests are forwarded to the developer mailing
15144  list.
15145  This is the link for requesting features:
15146 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
15147
15148 \end_inset
15149
15150 .
15151 \layout Subsection
15152
15153 Getting Help
15154 \layout Standard
15155
15156 These links should take you directly to the
15157 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
15158
15159 \end_inset
15160
15161
15162 \begin_inset Foot
15163 collapsed false
15164
15165 \layout Standard
15166
15167 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
15168  automated messages (mid 2003)
15169 \end_inset
15170
15171  and the
15172 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
15173
15174 \end_inset
15175
15176 , lists and forums are archived so if you are lucky someone already had
15177  a similar problem.
15178 \layout Subsection
15179
15180 ChangeLog
15181 \begin_inset LatexCommand \index{Changelog}
15182
15183 \end_inset
15184
15185
15186 \layout Standard
15187
15188 You can follow the status of the cvs version
15189 \begin_inset LatexCommand \index{version}
15190
15191 \end_inset
15192
15193  of SDCC by watching the file
15194 \begin_inset LatexCommand \htmlurl[ChangeLog]{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
15195
15196 \end_inset
15197
15198  in the cvs-repository.
15199 \layout Subsection
15200
15201 Release policy
15202 \begin_inset LatexCommand \index{Release policy}
15203
15204 \end_inset
15205
15206
15207 \layout Standard
15208
15209 Historically there often were long delays between official releases and
15210  the sourceforge download area tends to get not updated at all.
15211  Current excuses might refer to problems with live range analysis, but if
15212  this is fixed, the next problem rising is that another excuse will have
15213  to be found.
15214  Kidding aside, we have to get better there! On the other hand there are
15215  daily snapshots available at
15216 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
15217
15218 \end_inset
15219
15220 , and you can always built the very last version (hopefully with many bugs
15221  fixed, and features added) from the source code available at
15222 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
15223
15224 \end_inset
15225
15226 .
15227 \layout Subsection
15228
15229 Examples
15230 \begin_inset LatexCommand \index{Examples}
15231
15232 \end_inset
15233
15234
15235 \layout Standard
15236
15237 You'll find some small examples in the directory sdcc/device/examples/
15238 \layout Comment
15239
15240 Maybe we should include some links to real world applications.
15241  Preferably pointer to pointers (one for each architecture) so this stays
15242  manageable here?
15243 \layout Subsection
15244
15245 Quality control
15246 \begin_inset LatexCommand \index{Quality control}
15247
15248 \end_inset
15249
15250
15251 \layout Standard
15252
15253 The compiler is passed through nightly compile and build checks.
15254  The so called
15255 \shape italic
15256 regression tests
15257 \shape default
15258
15259 \begin_inset LatexCommand \index{Regression test}
15260
15261 \end_inset
15262
15263  check that SDCC itself compiles flawlessly on several platforms and checks
15264  the quality of the code generated by SDCC by running the code through simulator
15265 s.
15266  There is a separate document
15267 \shape italic
15268 test_suite.pdf
15269 \begin_inset LatexCommand \index{Test suite}
15270
15271 \end_inset
15272
15273
15274 \shape default
15275  about this.
15276 \layout Standard
15277
15278 You'll find the test code in the directory
15279 \shape italic
15280 sdcc/support/regression
15281 \shape default
15282 .
15283  You can run these tests manually by running
15284 \family sans
15285 make
15286 \family default
15287  in this directory (or f.e.
15288
15289 \family sans
15290 make test-mcs51
15291 \family default
15292  if you don't want to run the complete tests).
15293  The test code might also be interesting if you want to look for examples
15294 \begin_inset LatexCommand \index{Examples}
15295
15296 \end_inset
15297
15298  checking corner cases of SDCC or if you plan to submit patches
15299 \begin_inset LatexCommand \index{Patch submission}
15300
15301 \end_inset
15302
15303 .
15304 \layout Standard
15305
15306 The pic port uses a different set of regression tests, you'll find them
15307  in the directory
15308 \shape italic
15309 sdcc/src/regression
15310 \shape default
15311 .
15312 \layout Section
15313 \pagebreak_top
15314 Compiler internals
15315 \begin_inset LatexCommand \index{Compiler internals}
15316
15317 \end_inset
15318
15319
15320 \layout Subsection
15321
15322 The anatomy of the compiler
15323 \layout Standard
15324
15325
15326 \shape italic
15327 This is an excerpt from an article published in Circuit Cellar Magazine
15328  in august 2000.
15329  It's a little outdated (the compiler is much more efficient now and user/develo
15330 per friendly), but pretty well exposes the guts of it all.
15331 \shape default
15332
15333 \newline
15334
15335 \newline
15336 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
15337  It is fairly easy to retarget for other 8-bit MCU.
15338  Here we take a look at some of the internals of the compiler.
15339
15340 \layout Paragraph*
15341
15342 Parsing
15343 \begin_inset LatexCommand \index{Parsing}
15344
15345 \end_inset
15346
15347
15348 \layout Standard
15349
15350 Parsing the input source file and creating an AST (Annotated Syntax Tree
15351 \begin_inset LatexCommand \index{Annotated syntax tree}
15352
15353 \end_inset
15354
15355 ).
15356  This phase also involves propagating types (annotating each node of the
15357  parse tree with type information) and semantic analysis.
15358  There are some MCU specific parsing rules.
15359  For example the storage classes, the extended storage classes are MCU specific
15360  while there may be a xdata storage class for 8051 there is no such storage
15361  class for z80 or Atmel AVR.
15362  SDCC allows MCU specific storage class extensions, i.e.
15363  xdata will be treated as a storage class specifier when parsing 8051 C
15364  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
15365  C code.
15366 \layout Paragraph*
15367
15368 Generating iCode
15369 \begin_inset LatexCommand \index{iCode}
15370
15371 \end_inset
15372
15373
15374 \layout Standard
15375
15376 Intermediate code generation.
15377  In this phase the AST is broken down into three-operand form (iCode).
15378  These three operand forms are represented as doubly linked lists.
15379  ICode is the term given to the intermediate form generated by the compiler.
15380  ICode example section shows some examples of iCode generated for some simple
15381  C source functions.
15382 \layout Paragraph*
15383
15384 Optimizations
15385 \begin_inset LatexCommand \index{Optimizations}
15386
15387 \end_inset
15388
15389 .
15390 \layout Standard
15391
15392 Bulk of the target independent optimizations is performed in this phase.
15393  The optimizations include constant propagation, common sub-expression eliminati
15394 on, loop invariant code movement, strength reduction of loop induction variables
15395  and dead-code elimination.
15396 \layout Paragraph*
15397
15398 Live range analysis
15399 \begin_inset LatexCommand \index{Live range analysis}
15400
15401 \end_inset
15402
15403
15404 \layout Standard
15405
15406 During intermediate code generation phase, the compiler assumes the target
15407  machine has infinite number of registers and generates a lot of temporary
15408  variables.
15409  The live range computation determines the lifetime of each of these compiler-ge
15410 nerated temporaries.
15411  A picture speaks a thousand words.
15412  ICode example sections show the live range annotations for each of the
15413  operand.
15414  It is important to note here, each iCode is assigned a number in the order
15415  of its execution in the function.
15416  The live ranges are computed in terms of these numbers.
15417  The from number is the number of the iCode which first defines the operand
15418  and the to number signifies the iCode which uses this operand last.
15419 \layout Paragraph*
15420
15421 Register Allocation
15422 \begin_inset LatexCommand \index{Register allocation}
15423
15424 \end_inset
15425
15426
15427 \layout Standard
15428
15429 The register allocation determines the type and number of registers needed
15430  by each operand.
15431  In most MCUs only a few registers can be used for indirect addressing.
15432  In case of 8051 for example the registers R0 & R1 can be used to indirectly
15433  address the internal ram and DPTR to indirectly address the external ram.
15434  The compiler will try to allocate the appropriate register to pointer variables
15435  if it can.
15436  ICode example section shows the operands annotated with the registers assigned
15437  to them.
15438  The compiler will try to keep operands in registers as much as possible;
15439  there are several schemes the compiler uses to do achieve this.
15440  When the compiler runs out of registers the compiler will check to see
15441  if there are any live operands which is not used or defined in the current
15442  basic block being processed, if there are any found then it will push that
15443  operand and use the registers in this block, the operand will then be popped
15444  at the end of the basic block.
15445
15446 \layout Standard
15447
15448 There are other MCU specific considerations in this phase.
15449  Some MCUs have an accumulator; very short-lived operands could be assigned
15450  to the accumulator instead of general-purpose register.
15451 \layout Paragraph*
15452
15453 Code generation
15454 \layout Standard
15455
15456 Figure II gives a table of iCode operations supported by the compiler.
15457  The code generation involves translating these operations into corresponding
15458  assembly code for the processor.
15459  This sounds overly simple but that is the essence of code generation.
15460  Some of the iCode operations are generated on a MCU specific manner for
15461  example, the z80 port does not use registers to pass parameters so the
15462  SEND and RECV iCode operations will not be generated, and it also does
15463  not support JUMPTABLES.
15464
15465 \newline
15466
15467 \series bold
15468 \shape italic
15469 \color red
15470 <Where is Figure II ?>
15471 \layout Paragraph*
15472
15473 ICode Example
15474 \begin_inset LatexCommand \index{iCode}
15475
15476 \end_inset
15477
15478
15479 \layout Standard
15480
15481 This section shows some details of iCode.
15482  The example C code does not do anything useful; it is used as an example
15483  to illustrate the intermediate code generated by the compiler.
15484 \layout Verse
15485
15486
15487 \family typewriter
15488 1.\SpecialChar ~
15489 xdata int * p;
15490 \newline
15491 2.\SpecialChar ~
15492 int gint;
15493 \newline
15494 3.\SpecialChar ~
15495 /* This function does nothing useful.
15496  It is used
15497 \newline
15498 4.\SpecialChar ~
15499 \SpecialChar ~
15500 \SpecialChar ~
15501 \SpecialChar ~
15502 for the purpose of explaining iCode */
15503 \newline
15504 5.\SpecialChar ~
15505 short function (data int *x)
15506 \newline
15507 6.\SpecialChar ~
15508 {
15509 \newline
15510 7.\SpecialChar ~
15511 \SpecialChar ~
15512 \SpecialChar ~
15513 short i=10; /* dead initialization eliminated */
15514 \newline
15515 8.\SpecialChar ~
15516 \SpecialChar ~
15517 \SpecialChar ~
15518 short sum=10; /* dead initialization eliminated */
15519 \newline
15520 9.\SpecialChar ~
15521 \SpecialChar ~
15522 \SpecialChar ~
15523 short mul;
15524 \newline
15525 10.\SpecialChar ~
15526 \SpecialChar ~
15527 int j ;
15528 \newline
15529 11.\SpecialChar ~
15530 \SpecialChar ~
15531 while (*x) *x++ = *p++;
15532 \newline
15533 12.\SpecialChar ~
15534 \SpecialChar ~
15535 \SpecialChar ~
15536 \SpecialChar ~
15537 sum = 0 ;
15538 \newline
15539 13.\SpecialChar ~
15540 \SpecialChar ~
15541 mul = 0;
15542 \newline
15543 14.\SpecialChar ~
15544 \SpecialChar ~
15545 /* compiler detects i,j to be induction variables */
15546 \newline
15547 15.\SpecialChar ~
15548 \SpecialChar ~
15549 for (i = 0, j = 10 ; i < 10 ; i++, j
15550 \family default
15551 -
15552 \begin_inset ERT
15553 status Collapsed
15554
15555 \layout Standard
15556
15557 \backslash
15558 /
15559 \end_inset
15560
15561 -
15562 \family typewriter
15563 ) {
15564 \newline
15565 16.\SpecialChar ~
15566 \SpecialChar ~
15567 \SpecialChar ~
15568 \SpecialChar ~
15569 sum += i;
15570 \newline
15571 17.\SpecialChar ~
15572 \SpecialChar ~
15573 \SpecialChar ~
15574 \SpecialChar ~
15575 mul += i * 3; /* this multiplication remains */
15576 \newline
15577 18.\SpecialChar ~
15578 \SpecialChar ~
15579 \SpecialChar ~
15580 \SpecialChar ~
15581 gint += j * 3;/* this multiplication changed to addition */
15582 \newline
15583 19.\SpecialChar ~
15584 \SpecialChar ~
15585 }
15586 \newline
15587 20.\SpecialChar ~
15588 \SpecialChar ~
15589 return sum+mul;
15590 \newline
15591 21.\SpecialChar ~
15592 }
15593 \layout Standard
15594
15595 In addition to the operands each iCode contains information about the filename
15596  and line it corresponds to in the source file.
15597  The first field in the listing should be interpreted as follows:
15598 \newline
15599
15600 \shape italic
15601 \size footnotesize
15602 Filename(linenumber: iCode Execution sequence number : ICode hash table
15603  key : loop depth of the iCode).
15604 \shape default
15605 \size default
15606
15607 \newline
15608 Then follows the human readable form of the ICode operation.
15609  Each operand of this triplet form can be of three basic types a) compiler
15610  generated temporary b) user defined variable c) a constant value.
15611  Note that local variables and parameters are replaced by compiler generated
15612  temporaries.
15613  Live ranges
15614 \begin_inset LatexCommand \index{Live range analysis}
15615
15616 \end_inset
15617
15618  are computed only for temporaries (i.e.
15619  live ranges are not computed for global variables).
15620  Registers
15621 \begin_inset LatexCommand \index{Register allocation}
15622
15623 \end_inset
15624
15625  are allocated for temporaries only.
15626  Operands are formatted in the following manner:
15627 \newline
15628
15629 \shape italic
15630 \size footnotesize
15631 Operand Name [lr live-from : live-to ] { type information } [ registers
15632  allocated ].
15633 \shape default
15634 \size default
15635
15636 \newline
15637 As mentioned earlier the live ranges are computed in terms of the execution
15638  sequence number of the iCodes, for example
15639 \newline
15640 the iTemp0 is live from (i.e.
15641  first defined in iCode with execution sequence number 3, and is last used
15642  in the iCode with sequence number 5).
15643  For induction variables such as iTemp21 the live range computation extends
15644  the lifetime from the start to the end of the loop.
15645 \newline
15646 The register allocator used the live range information to allocate registers,
15647  the same registers may be used for different temporaries if their live
15648  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
15649  iTemp17 since their live ranges do not overlap.
15650  In addition the allocator also takes into consideration the type and usage
15651  of a temporary, for example itemp6 is a pointer to near space and is used
15652  as to fetch data from (i.e.
15653  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer registers (r0).
15654  Some short lived temporaries are allocated to special registers which have
15655  meaning to the code generator e.g.
15656  iTemp13 is allocated to a pseudo register CC which tells the back end that
15657  the temporary is used only for a conditional jump the code generation makes
15658  use of this information to optimize a compare and jump ICode.
15659 \newline
15660 There are several loop optimizations
15661 \begin_inset LatexCommand \index{Loop optimization}
15662
15663 \end_inset
15664
15665  performed by the compiler.
15666  It can detect induction variables iTemp21(i) and iTemp23(j).
15667  Also note the compiler does selective strength reduction
15668 \begin_inset LatexCommand \index{Strength reduction}
15669
15670 \end_inset
15671
15672 , i.e.
15673  the multiplication of an induction variable in line 18 (gint = j * 3) is
15674  changed to addition, a new temporary iTemp17 is allocated and assigned
15675  a initial value, a constant 3 is then added for each iteration of the loop.
15676  The compiler does not change the multiplication
15677 \begin_inset LatexCommand \index{Multiplication}
15678
15679 \end_inset
15680
15681  in line 17 however since the processor does support an 8 * 8 bit multiplication.
15682 \newline
15683 Note the dead code elimination
15684 \begin_inset LatexCommand \index{Dead-code elimination}
15685
15686 \end_inset
15687
15688  optimization eliminated the dead assignments in line 7 & 8 to I and sum
15689  respectively.
15690 \newline
15691
15692 \layout Standard
15693
15694
15695 \size footnotesize
15696 Sample.c (5:1:0:0) _entry($9) :
15697 \layout Standard
15698
15699
15700 \size footnotesize
15701 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
15702 \layout Standard
15703
15704
15705 \size footnotesize
15706 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
15707 \layout Standard
15708
15709
15710 \size footnotesize
15711 Sample.c(11:4:53:0) preHeaderLbl0($11) :
15712 \layout Standard
15713
15714
15715 \size footnotesize
15716 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
15717  * int}[r2]
15718 \layout Standard
15719
15720
15721 \size footnotesize
15722 Sample.c(11:6:5:1) _whilecontinue_0($1) :
15723 \layout Standard
15724
15725
15726 \size footnotesize
15727 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
15728  int}[r0]]
15729 \layout Standard
15730
15731
15732 \size footnotesize
15733 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
15734 \layout Standard
15735
15736
15737 \size footnotesize
15738 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
15739  * int}
15740 \layout Standard
15741
15742
15743 \size footnotesize
15744 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
15745  {short}
15746 \layout Standard
15747
15748
15749 \size footnotesize
15750 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
15751  * int}[DPTR]]
15752 \layout Standard
15753
15754
15755 \size footnotesize
15756 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
15757 }[r2 r3]
15758 \layout Standard
15759
15760
15761 \size footnotesize
15762 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
15763  * int}[r0] + 0x2 {short}
15764 \layout Standard
15765
15766
15767 \size footnotesize
15768 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
15769 \layout Standard
15770
15771
15772 \size footnotesize
15773 Sample.c(11:17:21:0)_whilebreak_0($3) :
15774 \layout Standard
15775
15776
15777 \size footnotesize
15778 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
15779 \layout Standard
15780
15781
15782 \size footnotesize
15783 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
15784 \layout Standard
15785
15786
15787 \size footnotesize
15788 Sample.c(15:20:54:0)preHeaderLbl1($13) :
15789 \layout Standard
15790
15791
15792 \size footnotesize
15793 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
15794 \layout Standard
15795
15796
15797 \size footnotesize
15798 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
15799 \layout Standard
15800
15801
15802 \size footnotesize
15803 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
15804 \layout Standard
15805
15806
15807 \size footnotesize
15808 Sample.c(15:24:26:1)_forcond_0($4) :
15809 \layout Standard
15810
15811
15812 \size footnotesize
15813 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
15814  < 0xa {short}
15815 \layout Standard
15816
15817
15818 \size footnotesize
15819 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
15820 \layout Standard
15821
15822
15823 \size footnotesize
15824 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
15825  + ITemp21 [lr21:38]{short}[r4]
15826 \layout Standard
15827
15828
15829 \size footnotesize
15830 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
15831  * 0x3 {short}
15832 \layout Standard
15833
15834
15835 \size footnotesize
15836 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
15837  + iTemp15 [lr29:30]{short}[r1]
15838 \layout Standard
15839
15840
15841 \size footnotesize
15842 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
15843  r0]- 0x3 {short}
15844 \layout Standard
15845
15846
15847 \size footnotesize
15848 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
15849 int}[r7 r0]
15850 \layout Standard
15851
15852
15853 \size footnotesize
15854 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
15855  + 0x1 {short}
15856 \layout Standard
15857
15858
15859 \size footnotesize
15860 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
15861  r6]- 0x1 {short}
15862 \layout Standard
15863
15864
15865 \size footnotesize
15866 Sample.c(19:38:47:1) goto _forcond_0($4)
15867 \layout Standard
15868
15869
15870 \size footnotesize
15871 Sample.c(19:39:48:0)_forbreak_0($7) :
15872 \layout Standard
15873
15874
15875 \size footnotesize
15876 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
15877  + ITemp11 [lr19:40]{short}[r3]
15878 \layout Standard
15879
15880
15881 \size footnotesize
15882 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
15883 \layout Standard
15884
15885
15886 \size footnotesize
15887 Sample.c(20:42:51:0)_return($8) :
15888 \layout Standard
15889
15890
15891 \size footnotesize
15892 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
15893 \size default
15894
15895 \newline
15896
15897 \newline
15898 Finally the code generated for this function:
15899 \newline
15900
15901 \layout Standard
15902
15903
15904 \size footnotesize
15905 .area DSEG (DATA)
15906 \layout Standard
15907
15908
15909 \size footnotesize
15910 _p::
15911 \layout Standard
15912
15913
15914 \size footnotesize
15915 \SpecialChar ~
15916 \SpecialChar ~
15917 .ds 2
15918 \layout Standard
15919
15920
15921 \size footnotesize
15922 _gint::
15923 \layout Standard
15924
15925
15926 \size footnotesize
15927 \SpecialChar ~
15928 \SpecialChar ~
15929 .ds 2
15930 \layout Standard
15931
15932
15933 \size footnotesize
15934 ; sample.c 5
15935 \layout Standard
15936
15937
15938 \size footnotesize
15939 ; ----------------------------------------------
15940 \layout Standard
15941
15942
15943 \size footnotesize
15944 ; function function
15945 \layout Standard
15946
15947
15948 \size footnotesize
15949 ; ----------------------------------------------
15950 \layout Standard
15951
15952
15953 \size footnotesize
15954 _function:
15955 \layout Standard
15956
15957
15958 \size footnotesize
15959 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
15960 \layout Standard
15961
15962
15963 \size footnotesize
15964 \SpecialChar ~
15965 \SpecialChar ~
15966 mov r2,dpl
15967 \layout Standard
15968
15969
15970 \size footnotesize
15971 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
15972 \layout Standard
15973
15974
15975 \size footnotesize
15976 \SpecialChar ~
15977 \SpecialChar ~
15978 mov ar0,r2
15979 \layout Standard
15980
15981
15982 \size footnotesize
15983 ;_whilecontinue_0($1) :
15984 \layout Standard
15985
15986
15987 \size footnotesize
15988 00101$:
15989 \layout Standard
15990
15991
15992 \size footnotesize
15993 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
15994 \layout Standard
15995
15996
15997 \size footnotesize
15998 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
15999 \layout Standard
16000
16001
16002 \size footnotesize
16003 \SpecialChar ~
16004 \SpecialChar ~
16005 mov ar2,@r0
16006 \layout Standard
16007
16008
16009 \size footnotesize
16010 \SpecialChar ~
16011 \SpecialChar ~
16012 inc r0
16013 \layout Standard
16014
16015
16016 \size footnotesize
16017 \SpecialChar ~
16018 \SpecialChar ~
16019 mov ar3,@r0
16020 \layout Standard
16021
16022
16023 \size footnotesize
16024 \SpecialChar ~
16025 \SpecialChar ~
16026 dec r0
16027 \layout Standard
16028
16029
16030 \size footnotesize
16031 \SpecialChar ~
16032 \SpecialChar ~
16033 mov a,r2
16034 \layout Standard
16035
16036
16037 \size footnotesize
16038 \SpecialChar ~
16039 \SpecialChar ~
16040 orl a,r3
16041 \layout Standard
16042
16043
16044 \size footnotesize
16045 \SpecialChar ~
16046 \SpecialChar ~
16047 jz 00103$
16048 \layout Standard
16049
16050
16051 \size footnotesize
16052 00114$:
16053 \layout Standard
16054
16055
16056 \size footnotesize
16057 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
16058 \layout Standard
16059
16060
16061 \size footnotesize
16062 \SpecialChar ~
16063 \SpecialChar ~
16064 mov dpl,_p
16065 \layout Standard
16066
16067
16068 \size footnotesize
16069 \SpecialChar ~
16070 \SpecialChar ~
16071 mov dph,(_p + 1)
16072 \layout Standard
16073
16074
16075 \size footnotesize
16076 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
16077 \layout Standard
16078
16079
16080 \size footnotesize
16081 \SpecialChar ~
16082 \SpecialChar ~
16083 mov a,#0x02
16084 \layout Standard
16085
16086
16087 \size footnotesize
16088 \SpecialChar ~
16089 \SpecialChar ~
16090 add a,_p
16091 \layout Standard
16092
16093
16094 \size footnotesize
16095 \SpecialChar ~
16096 \SpecialChar ~
16097 mov _p,a
16098 \layout Standard
16099
16100
16101 \size footnotesize
16102 \SpecialChar ~
16103 \SpecialChar ~
16104 clr a
16105 \layout Standard
16106
16107
16108 \size footnotesize
16109 \SpecialChar ~
16110 \SpecialChar ~
16111 addc a,(_p + 1)
16112 \layout Standard
16113
16114
16115 \size footnotesize
16116 \SpecialChar ~
16117 \SpecialChar ~
16118 mov (_p + 1),a
16119 \layout Standard
16120
16121
16122 \size footnotesize
16123 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
16124 \layout Standard
16125
16126
16127 \size footnotesize
16128 \SpecialChar ~
16129 \SpecialChar ~
16130 movx a,@dptr
16131 \layout Standard
16132
16133
16134 \size footnotesize
16135 \SpecialChar ~
16136 \SpecialChar ~
16137 mov r2,a
16138 \layout Standard
16139
16140
16141 \size footnotesize
16142 \SpecialChar ~
16143 \SpecialChar ~
16144 inc dptr
16145 \layout Standard
16146
16147
16148 \size footnotesize
16149 \SpecialChar ~
16150 \SpecialChar ~
16151 movx a,@dptr
16152 \layout Standard
16153
16154
16155 \size footnotesize
16156 \SpecialChar ~
16157 \SpecialChar ~
16158 mov r3,a
16159 \layout Standard
16160
16161
16162 \size footnotesize
16163 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
16164 \layout Standard
16165
16166
16167 \size footnotesize
16168 \SpecialChar ~
16169 \SpecialChar ~
16170 mov @r0,ar2
16171 \layout Standard
16172
16173
16174 \size footnotesize
16175 \SpecialChar ~
16176 \SpecialChar ~
16177 inc r0
16178 \layout Standard
16179
16180
16181 \size footnotesize
16182 \SpecialChar ~
16183 \SpecialChar ~
16184 mov @r0,ar3
16185 \layout Standard
16186
16187
16188 \size footnotesize
16189 ; iTemp6 [lr5:16]{_near * int}[r0] =
16190 \layout Standard
16191
16192
16193 \size footnotesize
16194 ; iTemp6 [lr5:16]{_near * int}[r0] +
16195 \layout Standard
16196
16197
16198 \size footnotesize
16199 ; 0x2 {short}
16200 \layout Standard
16201
16202
16203 \size footnotesize
16204 \SpecialChar ~
16205 \SpecialChar ~
16206 inc r0
16207 \layout Standard
16208
16209
16210 \size footnotesize
16211 ; goto _whilecontinue_0($1)
16212 \layout Standard
16213
16214
16215 \size footnotesize
16216 \SpecialChar ~
16217 \SpecialChar ~
16218 sjmp 00101$
16219 \layout Standard
16220
16221
16222 \size footnotesize
16223 ; _whilebreak_0($3) :
16224 \layout Standard
16225
16226
16227 \size footnotesize
16228 00103$:
16229 \layout Standard
16230
16231
16232 \size footnotesize
16233 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
16234 \layout Standard
16235
16236
16237 \size footnotesize
16238 \SpecialChar ~
16239 \SpecialChar ~
16240 mov r2,#0x00
16241 \layout Standard
16242
16243
16244 \size footnotesize
16245 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
16246 \layout Standard
16247
16248
16249 \size footnotesize
16250 \SpecialChar ~
16251 \SpecialChar ~
16252 mov r3,#0x00
16253 \layout Standard
16254
16255
16256 \size footnotesize
16257 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
16258 \layout Standard
16259
16260
16261 \size footnotesize
16262 \SpecialChar ~
16263 \SpecialChar ~
16264 mov r4,#0x00
16265 \layout Standard
16266
16267
16268 \size footnotesize
16269 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
16270 \layout Standard
16271
16272
16273 \size footnotesize
16274 \SpecialChar ~
16275 \SpecialChar ~
16276 mov r5,#0x0A
16277 \layout Standard
16278
16279
16280 \size footnotesize
16281 \SpecialChar ~
16282 \SpecialChar ~
16283 mov r6,#0x00
16284 \layout Standard
16285
16286
16287 \size footnotesize
16288 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
16289 \layout Standard
16290
16291
16292 \size footnotesize
16293 \SpecialChar ~
16294 \SpecialChar ~
16295 mov r7,#0x1E
16296 \layout Standard
16297
16298
16299 \size footnotesize
16300 \SpecialChar ~
16301 \SpecialChar ~
16302 mov r0,#0x00
16303 \layout Standard
16304
16305
16306 \size footnotesize
16307 ; _forcond_0($4) :
16308 \layout Standard
16309
16310
16311 \size footnotesize
16312 00104$:
16313 \layout Standard
16314
16315
16316 \size footnotesize
16317 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
16318 \layout Standard
16319
16320
16321 \size footnotesize
16322 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
16323 \layout Standard
16324
16325
16326 \size footnotesize
16327 \SpecialChar ~
16328 \SpecialChar ~
16329 clr c
16330 \layout Standard
16331
16332
16333 \size footnotesize
16334 \SpecialChar ~
16335 \SpecialChar ~
16336 mov a,r4
16337 \layout Standard
16338
16339
16340 \size footnotesize
16341 \SpecialChar ~
16342 \SpecialChar ~
16343 xrl a,#0x80
16344 \layout Standard
16345
16346
16347 \size footnotesize
16348 \SpecialChar ~
16349 \SpecialChar ~
16350 subb a,#0x8a
16351 \layout Standard
16352
16353
16354 \size footnotesize
16355 \SpecialChar ~
16356 \SpecialChar ~
16357 jnc 00107$
16358 \layout Standard
16359
16360
16361 \size footnotesize
16362 00115$:
16363 \layout Standard
16364
16365
16366 \size footnotesize
16367 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
16368 \layout Standard
16369
16370
16371 \size footnotesize
16372 ; iTemp21 [lr21:38]{short}[r4]
16373 \layout Standard
16374
16375
16376 \size footnotesize
16377 \SpecialChar ~
16378 \SpecialChar ~
16379 mov a,r4
16380 \layout Standard
16381
16382
16383 \size footnotesize
16384 \SpecialChar ~
16385 \SpecialChar ~
16386 add a,r2
16387 \layout Standard
16388
16389
16390 \size footnotesize
16391 \SpecialChar ~
16392 \SpecialChar ~
16393 mov r2,a
16394 \layout Standard
16395
16396
16397 \size footnotesize
16398 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
16399 \layout Standard
16400
16401
16402 \size footnotesize
16403 \SpecialChar ~
16404 \SpecialChar ~
16405 mov b,#0x03
16406 \layout Standard
16407
16408
16409 \size footnotesize
16410 \SpecialChar ~
16411 \SpecialChar ~
16412 mov a,r4
16413 \layout Standard
16414
16415
16416 \size footnotesize
16417 \SpecialChar ~
16418 \SpecialChar ~
16419 mul ab
16420 \layout Standard
16421
16422
16423 \size footnotesize
16424 \SpecialChar ~
16425 \SpecialChar ~
16426 mov r1,a
16427 \layout Standard
16428
16429
16430 \size footnotesize
16431 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
16432 \layout Standard
16433
16434
16435 \size footnotesize
16436 ; iTemp15 [lr29:30]{short}[r1]
16437 \layout Standard
16438
16439
16440 \size footnotesize
16441 \SpecialChar ~
16442 \SpecialChar ~
16443 add a,r3
16444 \layout Standard
16445
16446
16447 \size footnotesize
16448 \SpecialChar ~
16449 \SpecialChar ~
16450 mov r3,a
16451 \layout Standard
16452
16453
16454 \size footnotesize
16455 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
16456 \layout Standard
16457
16458
16459 \size footnotesize
16460 \SpecialChar ~
16461 \SpecialChar ~
16462 mov a,r7
16463 \layout Standard
16464
16465
16466 \size footnotesize
16467 \SpecialChar ~
16468 \SpecialChar ~
16469 add a,#0xfd
16470 \layout Standard
16471
16472
16473 \size footnotesize
16474 \SpecialChar ~
16475 \SpecialChar ~
16476 mov r7,a
16477 \layout Standard
16478
16479
16480 \size footnotesize
16481 \SpecialChar ~
16482 \SpecialChar ~
16483 mov a,r0
16484 \layout Standard
16485
16486
16487 \size footnotesize
16488 \SpecialChar ~
16489 \SpecialChar ~
16490 addc a,#0xff
16491 \layout Standard
16492
16493
16494 \size footnotesize
16495 \SpecialChar ~
16496 \SpecialChar ~
16497 mov r0,a
16498 \layout Standard
16499
16500
16501 \size footnotesize
16502 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
16503 \layout Standard
16504
16505
16506 \size footnotesize
16507 \SpecialChar ~
16508 \SpecialChar ~
16509 mov a,r7
16510 \layout Standard
16511
16512
16513 \size footnotesize
16514 \SpecialChar ~
16515 \SpecialChar ~
16516 add a,_gint
16517 \layout Standard
16518
16519
16520 \size footnotesize
16521 \SpecialChar ~
16522 \SpecialChar ~
16523 mov _gint,a
16524 \layout Standard
16525
16526
16527 \size footnotesize
16528 \SpecialChar ~
16529 \SpecialChar ~
16530 mov a,r0
16531 \layout Standard
16532
16533
16534 \size footnotesize
16535 \SpecialChar ~
16536 \SpecialChar ~
16537 addc a,(_gint + 1)
16538 \layout Standard
16539
16540
16541 \size footnotesize
16542 \SpecialChar ~
16543 \SpecialChar ~
16544 mov (_gint + 1),a
16545 \layout Standard
16546
16547
16548 \size footnotesize
16549 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
16550 \layout Standard
16551
16552
16553 \size footnotesize
16554 \SpecialChar ~
16555 \SpecialChar ~
16556 inc r4
16557 \layout Standard
16558
16559
16560 \size footnotesize
16561 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
16562 \layout Standard
16563
16564
16565 \size footnotesize
16566 \SpecialChar ~
16567 \SpecialChar ~
16568 dec r5
16569 \layout Standard
16570
16571
16572 \size footnotesize
16573 \SpecialChar ~
16574 \SpecialChar ~
16575 cjne r5,#0xff,00104$
16576 \layout Standard
16577
16578
16579 \size footnotesize
16580 \SpecialChar ~
16581 \SpecialChar ~
16582 dec r6
16583 \layout Standard
16584
16585
16586 \size footnotesize
16587 ; goto _forcond_0($4)
16588 \layout Standard
16589
16590
16591 \size footnotesize
16592 \SpecialChar ~
16593 \SpecialChar ~
16594 sjmp 00104$
16595 \layout Standard
16596
16597
16598 \size footnotesize
16599 ; _forbreak_0($7) :
16600 \layout Standard
16601
16602
16603 \size footnotesize
16604 00107$:
16605 \layout Standard
16606
16607
16608 \size footnotesize
16609 ; ret iTemp24 [lr40:41]{short}
16610 \layout Standard
16611
16612
16613 \size footnotesize
16614 \SpecialChar ~
16615 \SpecialChar ~
16616 mov a,r3
16617 \layout Standard
16618
16619
16620 \size footnotesize
16621 \SpecialChar ~
16622 \SpecialChar ~
16623 add a,r2
16624 \layout Standard
16625
16626
16627 \size footnotesize
16628 \SpecialChar ~
16629 \SpecialChar ~
16630 mov dpl,a
16631 \layout Standard
16632
16633
16634 \size footnotesize
16635 ; _return($8) :
16636 \layout Standard
16637
16638
16639 \size footnotesize
16640 00108$:
16641 \layout Standard
16642
16643
16644 \size footnotesize
16645 \SpecialChar ~
16646 \SpecialChar ~
16647 ret
16648 \newline
16649
16650 \layout Subsection
16651
16652 A few words about basic block successors, predecessors and dominators
16653 \layout Standard
16654
16655 Successors are basic blocks
16656 \begin_inset LatexCommand \index{Basic blocks}
16657
16658 \end_inset
16659
16660  that might execute after this basic block.
16661 \newline
16662 Predecessors are basic blocks that might execute before reaching this basic
16663  block.
16664 \newline
16665 Dominators are basic blocks that WILL execute before reaching this basic
16666  block.
16667 \newline
16668
16669 \layout Standard
16670
16671 [basic block 1]
16672 \layout Standard
16673
16674 if (something)
16675 \layout Standard
16676
16677 [basic block 2]
16678 \layout Standard
16679
16680 else
16681 \layout Standard
16682
16683 [basic block 3]
16684 \layout Standard
16685
16686 [basic block 4]
16687 \newline
16688
16689 \layout Standard
16690
16691 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
16692 \layout Standard
16693
16694 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
16695 \layout Standard
16696
16697 c) domVect of [BB4] = BB1 ...
16698  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
16699  was executed.
16700 \layout Section
16701
16702 Acknowledgments
16703 \layout Standard
16704
16705
16706 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
16707
16708 \end_inset
16709
16710
16711 \newline
16712
16713 \newline
16714
16715 \emph on
16716 Thanks to all the other volunteer developers who have helped with coding,
16717  testing, web-page creation, distribution sets, etc.
16718  You know who you are :-)
16719 \emph default
16720
16721 \newline
16722
16723 \layout Standard
16724
16725 This document was initially written by Sandeep Dutta
16726 \layout Standard
16727
16728 All product names mentioned herein may be trademarks
16729 \begin_inset LatexCommand \index{Trademarks}
16730
16731 \end_inset
16732
16733  of their respective companies.
16734
16735 \layout Section
16736
16737 Alphabetical index
16738 \layout Standard
16739
16740 To avoid confusion, the installation and building options for sdcc itself
16741  (chapter 2) are not part of the index.
16742 \layout Standard
16743
16744
16745 \begin_inset LatexCommand \printindex{}
16746
16747 \end_inset
16748
16749
16750 \the_end