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