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.8
  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 section
 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 (sdcc/doc/sdccman.ly
3415 x).
3416  Using LyX
3417 \begin_inset LatexCommand \url{www.lyx.org}
3418
3419 \end_inset
3420
3421  as editor this is straightforward.
3422  If you want to avoid installing the tools you will have some success with
3423  a bootable Knoppix CD
3424 \begin_inset LatexCommand \url{http://www.knoppix.net}
3425
3426 \end_inset
3427
3428 .
3429  Prebuilt documentation in html and pdf format is available from
3430 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3431
3432 \end_inset
3433
3434 .
3435 \layout Section
3436
3437 Reading the Documentation
3438 \layout Standard
3439
3440 Currently reading the document in pdf format is recommended, as for unknown
3441  reason the hyperlinks are working there whereas in the html version they
3442  are not
3443 \begin_inset Foot
3444 collapsed false
3445
3446 \layout Standard
3447
3448 If you should know why please drop us a note
3449 \end_inset
3450
3451 .
3452  You'll find the pdf version at
3453 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
3454
3455 \end_inset
3456
3457 .
3458 \newline
3459 This documentation is in some aspects different from a commercial documentation:
3460
3461 \layout Itemize
3462
3463 It tries to document SDCC for several processor architectures in one document
3464  (commercially these probably would be separate documents/products).
3465  This document
3466 \begin_inset LatexCommand \index{Status of documentation}
3467
3468 \end_inset
3469
3470  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3471 on about f.e.
3472  Z80, PIC and HC08.
3473 \layout Itemize
3474
3475 There are many references pointing away from this documentation.
3476  Don't let this distract you.
3477  If there f.e.
3478  was a reference like
3479 \begin_inset LatexCommand \url{www.opencores.org}
3480
3481 \end_inset
3482
3483  together with a statement
3484 \begin_inset Quotes sld
3485 \end_inset
3486
3487 some processors which are targetted by SDCC can be implemented in a
3488 \emph on
3489 f
3490 \emph default
3491 ield
3492 \emph on
3493 p
3494 \emph default
3495 rogrammable
3496 \emph on
3497 g
3498 \emph default
3499 ate
3500 \emph on
3501 a
3502 \emph default
3503 rray
3504 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3505
3506 \end_inset
3507
3508
3509 \begin_inset Quotes srd
3510 \end_inset
3511
3512  we expect you to have a quick look there and come back.
3513  If you read this you are on the right track.
3514 \layout Itemize
3515
3516 Some sections attribute more space to problems, restrictions and warnings
3517  than to the solution.
3518 \layout Itemize
3519
3520 The installation section and the section about the debugger is intimidating.
3521 \layout Itemize
3522
3523 There are still lots of typos and there are more different writing styles
3524  than pictures.
3525 \layout Section
3526
3527 Testing the SDCC Compiler
3528 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3529
3530 \end_inset
3531
3532
3533 \layout Standard
3534
3535 The first thing you should do after installing your SDCC compiler is to
3536  see if it runs.
3537  Type
3538 \family sans
3539 \series bold
3540 "sdcc -
3541 \begin_inset ERT
3542 status Collapsed
3543
3544 \layout Standard
3545
3546 \backslash
3547 /
3548 \end_inset
3549
3550 -version"
3551 \begin_inset LatexCommand \index{version}
3552
3553 \end_inset
3554
3555
3556 \family default
3557 \series default
3558  at the prompt, and the program should run and tell you the version.
3559  If it doesn't run, or gives a message about not finding sdcc program, then
3560  you need to check over your installation.
3561  Make sure that the sdcc bin directory is in your executable search path
3562  defined by the PATH environment setting (
3563 \series medium
3564 see
3565 \series default
3566 section
3567 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3568
3569 \end_inset
3570
3571 \SpecialChar ~
3572
3573 \series medium
3574 Install trouble-shooting for suggestions
3575 \series default
3576 ).
3577  Make sure that the sdcc program is in the bin folder, if not perhaps something
3578  did not install correctly.
3579 \newline
3580
3581 \newline
3582
3583 \series medium
3584 SDCC
3585 \series default
3586 is commonly installed as described in section
3587 \begin_inset Quotes sld
3588 \end_inset
3589
3590 Install and search paths
3591 \begin_inset Quotes srd
3592 \end_inset
3593
3594 .
3595 \newline
3596
3597 \newline
3598
3599 \series medium
3600 Make sure the compiler works on a very simple example.
3601  Type in the following test.c program using your favorite
3602 \series default
3603 ASCII
3604 \series medium
3605 editor:
3606 \layout Verse
3607
3608
3609 \family typewriter
3610 char test;
3611 \newline
3612
3613 \newline
3614 void main(void) {
3615 \newline
3616 \SpecialChar ~
3617 \SpecialChar ~
3618 \SpecialChar ~
3619 \SpecialChar ~
3620 test=0;
3621 \newline
3622 }
3623 \layout Standard
3624
3625
3626 \series medium
3627 Compile this using the following command:
3628 \family sans
3629 \series bold
3630 "sdcc -c test.c".
3631
3632 \family default
3633 \series default
3634
3635 \series medium
3636 If all goes well, the compiler will generate a test.asm and test.rel file.
3637  Congratulations, you've just compiled your first program with SDCC.
3638  We used the -c option to tell SDCC not to link the generated code, just
3639  to keep things simple for this step.
3640 \series default
3641
3642 \newline
3643
3644 \newline
3645
3646 \series medium
3647 The next step is to try it with the linker.
3648  Type in
3649 \family sans
3650 \series bold
3651 "sdcc test.c
3652 \family default
3653 \series default
3654 "
3655 \series medium
3656 .
3657  If all goes well the compiler will link with the libraries and produce
3658  a test.ihx output file.
3659  If this step fails
3660 \series default
3661
3662 \series medium
3663 (no test.ihx, and the linker generates warnings), then the problem is most
3664  likely that
3665 \series default
3666 SDCC
3667 \series medium
3668  cannot find the
3669 \series default
3670 /
3671 \series medium
3672 usr/local/share/sdcc/lib directory
3673 \series default
3674
3675 \series medium
3676 (see
3677 \series default
3678 section
3679 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3680
3681 \end_inset
3682
3683 \SpecialChar ~
3684
3685 \series medium
3686 Install trouble-shooting for suggestions).
3687 \series default
3688
3689 \newline
3690
3691 \newline
3692
3693 \series medium
3694 The final test is to ensure
3695 \series default
3696 SDCC
3697 \series medium
3698  can use the
3699 \series default
3700 standard
3701 \series medium
3702  header files and libraries.
3703  Edit test.c and change it to the following:
3704 \layout Verse
3705
3706
3707 \family typewriter
3708 #include <string.h>
3709 \newline
3710
3711 \newline
3712 char str1[10];
3713 \newline
3714
3715 \newline
3716 void main(void) {
3717 \newline
3718 \SpecialChar ~
3719 \SpecialChar ~
3720 strcpy(str1, "testing");
3721 \newline
3722 }
3723 \layout Standard
3724
3725
3726 \series medium
3727 Compile this by typing
3728 \family sans
3729 \series bold
3730 "sdcc test.c"
3731 \family default
3732 \series medium
3733 .
3734  This should generate a test.ihx output file, and it should give no warnings
3735  such as not finding the string.h file.
3736  If it cannot find the string.h file, then the problem is that
3737 \series default
3738 SDCC
3739 \series medium
3740  cannot find the /usr/local/share/sdcc/include directory
3741 \series default
3742
3743 \series medium
3744 (see the
3745 \series default
3746 section
3747 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3748
3749 \end_inset
3750
3751 \SpecialChar ~
3752
3753 \series medium
3754 Install trouble-shooting section for suggestions).
3755
3756 \series default
3757  Use option
3758 \series bold
3759 -
3760 \begin_inset ERT
3761 status Collapsed
3762
3763 \layout Standard
3764
3765 \backslash
3766 /
3767 \end_inset
3768
3769 -print-search-dirs
3770 \series default
3771
3772 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3773
3774 \end_inset
3775
3776  to find exactly where SDCC is looking for the include and lib files.
3777 \layout Section
3778
3779 Install Trouble-shooting
3780 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3781
3782 \end_inset
3783
3784
3785 \begin_inset LatexCommand \index{Install trouble-shooting}
3786
3787 \end_inset
3788
3789
3790 \layout Subsection
3791
3792 If SDCC does not build correctly
3793 \layout Standard
3794
3795 A thing to try is starting from scratch by unpacking the .tgz source package
3796  again in an empty directory.
3797  Configure it like:
3798 \newline
3799
3800 \newline
3801
3802 \family sans
3803 \series bold
3804 ./configure 2>&1 | tee configure.log
3805 \family default
3806 \series default
3807
3808 \newline
3809
3810 \newline
3811 and build it like:
3812 \newline
3813
3814 \newline
3815
3816 \family sans
3817 \series bold
3818 make 2>&1 | tee make.log
3819 \family default
3820 \series default
3821
3822 \newline
3823
3824 \newline
3825 If anything goes wrong, you can review the log files to locate the problem.
3826  Or a relevant part of this can be attached to an email that could be helpful
3827  when requesting help from the mailing list.
3828 \layout Subsection
3829
3830 What the
3831 \begin_inset Quotes sld
3832 \end_inset
3833
3834 ./configure
3835 \begin_inset Quotes srd
3836 \end_inset
3837
3838  does
3839 \layout Standard
3840
3841 The
3842 \begin_inset Quotes sld
3843 \end_inset
3844
3845 ./configure
3846 \begin_inset Quotes srd
3847 \end_inset
3848
3849  command is a script that analyzes your system and performs some configuration
3850  to ensure the source package compiles on your system.
3851  It will take a few minutes to run, and will compile a few tests to determine
3852  what compiler features are installed.
3853 \layout Subsection
3854
3855 What the
3856 \begin_inset Quotes sld
3857 \end_inset
3858
3859 make
3860 \begin_inset Quotes srd
3861 \end_inset
3862
3863  does
3864 \layout Standard
3865
3866 This runs the GNU make tool, which automatically compiles all the source
3867  packages into the final installed binary executables.
3868 \layout Subsection
3869
3870 What the
3871 \begin_inset Quotes sld
3872 \end_inset
3873
3874 make install
3875 \begin_inset Quotes erd
3876 \end_inset
3877
3878  command does.
3879 \layout Standard
3880
3881 This will install the compiler, other executables libraries and include
3882  files into the appropriate directories.
3883  See sections
3884 \begin_inset LatexCommand \ref{sub:Install-paths}
3885
3886 \end_inset
3887
3888 ,\SpecialChar ~
3889
3890 \begin_inset LatexCommand \ref{sub:Search-Paths}
3891
3892 \end_inset
3893
3894 \SpecialChar ~
3895 about install and search paths.
3896 \newline
3897 On most systems you will need super-user privileges to do this.
3898 \layout Section
3899
3900 Components of SDCC
3901 \layout Standard
3902
3903 SDCC is not just a compiler, but a collection of tools by various developers.
3904  These include linkers, assemblers, simulators and other components.
3905  Here is a summary of some of the components.
3906  Note that the included simulator and assembler have separate documentation
3907  which you can find in the source package in their respective directories.
3908  As SDCC grows to include support for other processors, other packages from
3909  various developers are included and may have their own sets of documentation.
3910 \newline
3911
3912 \newline
3913 You might want to look at the files which are installed in <installdir>.
3914  At the time of this writing, we find the following programs for gcc-builds:
3915 \newline
3916
3917 \newline
3918 In <installdir>/bin:
3919 \layout Itemize
3920
3921 sdcc - The compiler.
3922 \layout Itemize
3923
3924 sdcpp - The C preprocessor.
3925 \layout Itemize
3926
3927 asx8051 - The assembler for 8051 type processors.
3928 \layout Itemize
3929
3930 as-z80
3931 \series bold
3932 ,
3933 \series default
3934 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
3935 \layout Itemize
3936
3937 aslink -The linker for 8051 type processors.
3938 \layout Itemize
3939
3940 link-z80
3941 \series bold
3942 ,
3943 \series default
3944 link-gbz80 - The Z80 and GameBoy Z80 linkers.
3945 \layout Itemize
3946
3947 s51 - The ucSim 8051 simulator.
3948 \layout Itemize
3949
3950 sdcdb - The source debugger.
3951 \layout Itemize
3952
3953 packihx - A tool to pack (compress) Intel hex files.
3954 \layout Standard
3955
3956 In <installdir>/share/sdcc/include
3957 \layout Itemize
3958
3959 the include files
3960 \layout Standard
3961
3962 In <installdir>/share/sdcc/lib
3963 \layout Itemize
3964
3965 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
3966  relocatables.
3967 \layout Standard
3968
3969 In <installdir>/share/sdcc/doc
3970 \layout Itemize
3971
3972 the documentation
3973 \layout Standard
3974
3975 As development for other processors proceeds, this list will expand to include
3976  executables to support processors like AVR, PIC, etc.
3977 \layout Subsection
3978
3979 sdcc - The Compiler
3980 \layout Standard
3981
3982 This is the actual compiler, it in turn uses the c-preprocessor and invokes
3983  the assembler and linkage editor.
3984 \layout Subsection
3985
3986 sdcpp - The C-Preprocessor
3987 \layout Standard
3988
3989 The preprocessor
3990 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
3991
3992 \end_inset
3993
3994  is a modified version of the GNU preprocessor.
3995  The C preprocessor is used to pull in #include sources, process #ifdef
3996  statements, #defines and so on.
3997 \layout Subsection
3998
3999 as
4000 \emph on
4001 xxxx
4002 \emph default
4003 , aslink, link-
4004 \emph on
4005 xxx
4006 \emph default
4007  - The Assemblers and Linkage Editors
4008 \layout Standard
4009
4010 This is retargettable assembler & linkage editor, it was developed by Alan
4011  Baldwin.
4012  John Hartman created the version for 8051, and I (Sandeep) have made some
4013  enhancements and bug fixes for it to work properly with SDCC.
4014 \layout Subsection
4015
4016 s51 - The Simulator
4017 \layout Standard
4018
4019 S51
4020 \begin_inset LatexCommand \index{s51}
4021
4022 \end_inset
4023
4024  is a freeware, opensource simulator developed by Daniel Drotos (
4025 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
4026
4027 \end_inset
4028
4029 ).
4030  The simulator is built as part of the build process.
4031  For more information visit Daniel's web site at:
4032 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4033
4034 \end_inset
4035
4036 .
4037  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4038  XA51 family.
4039 \layout Subsection
4040
4041 sdcdb - Source Level Debugger
4042 \layout Standard
4043
4044 Sdcdb
4045 \begin_inset LatexCommand \index{sdcdb (debugger)}
4046
4047 \end_inset
4048
4049  is the companion source level debugger.
4050  More about sdcdb in section
4051 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4052
4053 \end_inset
4054
4055 .
4056  The current version of the debugger uses Daniel's Simulator S51
4057 \begin_inset LatexCommand \index{s51}
4058
4059 \end_inset
4060
4061 , but can be easily changed to use other simulators.
4062
4063 \layout Chapter
4064
4065 Using SDCC
4066 \layout Section
4067
4068 Compiling
4069 \layout Subsection
4070
4071 Single Source File Projects
4072 \layout Standard
4073
4074 For single source file 8051 projects the process is very simple.
4075  Compile your programs with the following command
4076 \family sans
4077 \series bold
4078 "sdcc sourcefile.c".
4079
4080 \family default
4081 \series default
4082  This will compile, assemble and link your source file.
4083  Output files are as follows:
4084 \layout Itemize
4085
4086 sourcefile.asm
4087 \begin_inset LatexCommand \index{<file>.asm}
4088
4089 \end_inset
4090
4091  - Assembler source
4092 \begin_inset LatexCommand \index{Assembler source}
4093
4094 \end_inset
4095
4096  file created by the compiler
4097 \layout Itemize
4098
4099 sourcefile.lst
4100 \begin_inset LatexCommand \index{<file>.lst}
4101
4102 \end_inset
4103
4104  - Assembler listing
4105 \begin_inset LatexCommand \index{Assembler listing}
4106
4107 \end_inset
4108
4109  file created by the Assembler
4110 \layout Itemize
4111
4112 sourcefile.rst
4113 \begin_inset LatexCommand \index{<file>.rst}
4114
4115 \end_inset
4116
4117  - Assembler listing
4118 \begin_inset LatexCommand \index{Assembler listing}
4119
4120 \end_inset
4121
4122  file updated with linkedit information, created by linkage editor
4123 \layout Itemize
4124
4125 sourcefile.sym
4126 \begin_inset LatexCommand \index{<file>.sym}
4127
4128 \end_inset
4129
4130  - symbol listing
4131 \begin_inset LatexCommand \index{Symbol listing}
4132
4133 \end_inset
4134
4135  for the sourcefile, created by the assembler
4136 \layout Itemize
4137
4138 sourcefile.rel
4139 \begin_inset LatexCommand \index{<file>.rel}
4140
4141 \end_inset
4142
4143  or sourcefile.o
4144 \begin_inset LatexCommand \index{<file>.o}
4145
4146 \end_inset
4147
4148  - Object file
4149 \begin_inset LatexCommand \index{Object file}
4150
4151 \end_inset
4152
4153  created by the assembler, input to Linkage editor
4154 \layout Itemize
4155
4156 sourcefile.map
4157 \begin_inset LatexCommand \index{<file>.map}
4158
4159 \end_inset
4160
4161  - The memory map
4162 \begin_inset LatexCommand \index{Memory map}
4163
4164 \end_inset
4165
4166  for the load module, created by the Linker
4167 \layout Itemize
4168
4169 sourcefile.mem
4170 \begin_inset LatexCommand \index{<file>.mem}
4171
4172 \end_inset
4173
4174  - A file with a summary of the memory usage
4175 \layout Itemize
4176
4177 sourcefile.ihx
4178 \begin_inset LatexCommand \index{<file>.ihx}
4179
4180 \end_inset
4181
4182  - The load module in Intel hex format
4183 \begin_inset LatexCommand \index{Intel hex format}
4184
4185 \end_inset
4186
4187  (you can select the Motorola S19 format
4188 \begin_inset LatexCommand \index{Motorola S19 format}
4189
4190 \end_inset
4191
4192  with -
4193 \begin_inset ERT
4194 status Collapsed
4195
4196 \layout Standard
4197
4198 \backslash
4199 /
4200 \end_inset
4201
4202 -out-fmt-s19
4203 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4204
4205 \end_inset
4206
4207 .
4208  If you need another format you might want to use
4209 \family sans
4210 \shape italic
4211 objdump
4212 \family default
4213 \shape default
4214
4215 \begin_inset LatexCommand \index{objdump (tool)}
4216
4217 \end_inset
4218
4219  or
4220 \family sans
4221 \shape italic
4222  srecord
4223 \family default
4224 \shape default
4225
4226 \begin_inset LatexCommand \index{srecord (tool)}
4227
4228 \end_inset
4229
4230 ).
4231  Both formats are documented in the the documentation of srecord
4232 \begin_inset LatexCommand \index{srecord (tool)}
4233
4234 \end_inset
4235
4236
4237 \layout Itemize
4238
4239 sourcefile.adb
4240 \begin_inset LatexCommand \index{.adb}
4241
4242 \end_inset
4243
4244  - An intermediate file containing debug information needed to create the
4245  .cdb file (with -
4246 \begin_inset ERT
4247 status Collapsed
4248
4249 \layout Standard
4250
4251 \backslash
4252 /
4253 \end_inset
4254
4255 -debug
4256 \begin_inset LatexCommand \index{-\/-debug}
4257
4258 \end_inset
4259
4260 )
4261 \layout Itemize
4262
4263 sourcefile.cdb
4264 \begin_inset LatexCommand \index{<file>.cdb}
4265
4266 \end_inset
4267
4268  - An optional file (with -
4269 \begin_inset ERT
4270 status Collapsed
4271
4272 \layout Standard
4273
4274 \backslash
4275 /
4276 \end_inset
4277
4278 -debug) containing debug information.
4279  The format is documented in cdbfileformat.pdf.
4280 \layout Itemize
4281
4282 sourcefile.
4283  - (no extension)
4284 \begin_inset LatexCommand \index{<file> (no extension)}
4285
4286 \end_inset
4287
4288  An optional AOMF or AOMF51
4289 \begin_inset LatexCommand \index{AOMF, AOMF51}
4290
4291 \end_inset
4292
4293  file containing debug information (generated with option -
4294 \begin_inset ERT
4295 status Collapsed
4296
4297 \layout Standard
4298
4299 \backslash
4300 /
4301 \end_inset
4302
4303 -debug).
4304  The (Intel)
4305 \emph on
4306  a
4307 \emph default
4308 bsolute
4309 \emph on
4310 o
4311 \emph default
4312 bject
4313 \emph on
4314 m
4315 \emph default
4316 odule
4317 \emph on
4318 f
4319 \emph default
4320 ormat is commonly used by third party tools (debuggers
4321 \begin_inset LatexCommand \index{Debugger}
4322
4323 \end_inset
4324
4325 , simulators, emulators)
4326 \layout Itemize
4327
4328 sourcefile.dump*
4329 \begin_inset LatexCommand \index{<file>.dump*}
4330
4331 \end_inset
4332
4333  - Dump file to debug the compiler it self (generated with option -
4334 \begin_inset ERT
4335 status Collapsed
4336
4337 \layout Standard
4338
4339 \backslash
4340 /
4341 \end_inset
4342
4343 -dumpall) (see section
4344 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4345
4346 \end_inset
4347
4348 \SpecialChar ~
4349  and section
4350 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4351
4352 \end_inset
4353
4354 \SpecialChar ~
4355
4356 \begin_inset Quotes sld
4357 \end_inset
4358
4359 Anatomy of the compiler
4360 \begin_inset Quotes srd
4361 \end_inset
4362
4363 ).
4364 \layout Subsection
4365
4366 Projects with Multiple Source Files
4367 \layout Standard
4368
4369 SDCC can compile only ONE file at a time.
4370  Let us for example assume that you have a project containing the following
4371  files:
4372 \newline
4373
4374 \newline
4375 foo1.c (contains some functions)
4376 \newline
4377 foo2.c (contains some more functions)
4378 \newline
4379 foomain.c (contains more functions and the function main)
4380 \newline
4381
4382 \size footnotesize
4383
4384 \newline
4385
4386 \size default
4387 The first two files will need to be compiled separately with the commands:
4388 \size footnotesize
4389
4390 \size default
4391
4392 \newline
4393
4394 \newline
4395
4396 \family sans
4397 \series bold
4398 sdcc\SpecialChar ~
4399 -c\SpecialChar ~
4400 foo1.c
4401 \family default
4402 \series default
4403 \size footnotesize
4404
4405 \newline
4406
4407 \family sans
4408 \series bold
4409 \size default
4410 sdcc\SpecialChar ~
4411 -c\SpecialChar ~
4412 foo2.c
4413 \family default
4414 \series default
4415
4416 \newline
4417
4418 \newline
4419 Then compile the source file containing the
4420 \emph on
4421 main()
4422 \emph default
4423  function and link
4424 \begin_inset LatexCommand \index{Linker}
4425
4426 \end_inset
4427
4428  the files together with the following command:
4429 \newline
4430
4431 \newline
4432
4433 \family sans
4434 \series bold
4435 sdcc\SpecialChar ~
4436 foomain.c\SpecialChar ~
4437 foo1.rel\SpecialChar ~
4438 foo2.rel
4439 \family default
4440 \series default
4441
4442 \begin_inset LatexCommand \index{<file>.rel}
4443
4444 \end_inset
4445
4446
4447 \newline
4448
4449 \newline
4450 Alternatively,
4451 \emph on
4452 foomain.c
4453 \emph default
4454 can be separately compiled as well:
4455 \family sans
4456 \series bold
4457
4458 \newline
4459
4460 \newline
4461 sdcc\SpecialChar ~
4462 -c\SpecialChar ~
4463 foomain.c
4464 \newline
4465 sdcc foomain.rel foo1.rel foo2.rel
4466 \newline
4467
4468 \newline
4469
4470 \family default
4471 \series default
4472 The file containing the
4473 \emph on
4474 main()
4475 \emph default
4476  function
4477 \emph on
4478
4479 \emph default
4480 \noun on
4481 must
4482 \noun default
4483  be the
4484 \noun on
4485 first
4486 \noun default
4487  file specified in the command line, since the linkage editor processes
4488  file in the order they are presented to it.
4489  The linker is invoked from SDCC using a script file with extension .lnk
4490 \begin_inset LatexCommand \index{.lnk}
4491
4492 \end_inset
4493
4494 .
4495  You can view this file to troubleshoot linking problems such as those arising
4496  from missing libraries.
4497 \layout Subsection
4498
4499 Projects with Additional Libraries
4500 \begin_inset LatexCommand \index{Libraries}
4501
4502 \end_inset
4503
4504
4505 \layout Standard
4506
4507 Some reusable routines may be compiled into a library, see the documentation
4508  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4509  for how to create a
4510 \emph on
4511 .lib
4512 \begin_inset LatexCommand \index{.lib}
4513
4514 \end_inset
4515
4516
4517 \emph default
4518  library file.
4519  Libraries created in this manner can be included in the command line.
4520  Make sure you include the -L <library-path> option to tell the linker where
4521  to look for these files if they are not in the current directory.
4522  Here is an example, assuming you have the source file
4523 \emph on
4524 foomain.c
4525 \emph default
4526  and a library
4527 \emph on
4528  foolib.lib
4529 \emph default
4530  in the directory
4531 \emph on
4532 mylib
4533 \emph default
4534  (if that is not the same as your current project):
4535 \newline
4536
4537 \newline
4538
4539 \family sans
4540 \series bold
4541 sdcc foomain.c foolib.lib -L mylib
4542 \newline
4543
4544 \newline
4545
4546 \family default
4547 \series default
4548 Note here that
4549 \emph on
4550  mylib
4551 \emph default
4552  must be an absolute path name.
4553 \newline
4554
4555 \newline
4556 The most efficient way to use libraries is to keep separate modules in separate
4557  source files.
4558  The lib file now should name all the modules.rel
4559 \begin_inset LatexCommand \index{<file>.rel}
4560
4561 \end_inset
4562
4563  files.
4564  For an example see the standard library file
4565 \emph on
4566 libsdcc.lib
4567 \emph default
4568  in the directory <installdir>/share/lib/small.
4569 \layout Section
4570
4571 Command Line Options
4572 \begin_inset LatexCommand \index{Command Line Options}
4573
4574 \end_inset
4575
4576
4577 \layout Subsection
4578
4579 Processor Selection Options
4580 \begin_inset LatexCommand \index{Options processor selection}
4581
4582 \end_inset
4583
4584
4585 \begin_inset LatexCommand \index{Processor selection options}
4586
4587 \end_inset
4588
4589
4590 \layout List
4591 \labelwidthstring 00.00.0000
4592
4593
4594 \series bold
4595 -mmcs51
4596 \begin_inset LatexCommand \index{-mmcs51}
4597
4598 \end_inset
4599
4600
4601 \series default
4602  Generate code for the Intel MCS51
4603 \begin_inset LatexCommand \index{MCS51}
4604
4605 \end_inset
4606
4607  family of processors.
4608  This is the default processor target.
4609 \layout List
4610 \labelwidthstring 00.00.0000
4611
4612
4613 \series bold
4614 -mds390
4615 \begin_inset LatexCommand \index{-mds390}
4616
4617 \end_inset
4618
4619
4620 \series default
4621  Generate code for the Dallas DS80C390
4622 \begin_inset LatexCommand \index{DS80C390}
4623
4624 \end_inset
4625
4626  processor.
4627 \layout List
4628 \labelwidthstring 00.00.0000
4629
4630
4631 \series bold
4632 -mds400
4633 \begin_inset LatexCommand \index{-mds400}
4634
4635 \end_inset
4636
4637
4638 \series default
4639  Generate code for the Dallas DS80C400
4640 \begin_inset LatexCommand \index{DS80C400}
4641
4642 \end_inset
4643
4644  processor.
4645 \layout List
4646 \labelwidthstring 00.00.0000
4647
4648
4649 \series bold
4650 -mhc08
4651 \begin_inset LatexCommand \index{-mhc08}
4652
4653 \end_inset
4654
4655
4656 \series default
4657  Generate code for the Motorola HC08
4658 \begin_inset LatexCommand \index{HC08}
4659
4660 \end_inset
4661
4662  family of processors (added Oct 2003).
4663 \layout List
4664 \labelwidthstring 00.00.0000
4665
4666
4667 \series bold
4668 -mz80
4669 \begin_inset LatexCommand \index{-mz80}
4670
4671 \end_inset
4672
4673
4674 \series default
4675  Generate code for the Zilog Z80
4676 \begin_inset LatexCommand \index{Z80}
4677
4678 \end_inset
4679
4680  family of processors.
4681 \layout List
4682 \labelwidthstring 00.00.0000
4683
4684
4685 \series bold
4686 -mgbz80
4687 \begin_inset LatexCommand \index{-mgbz80}
4688
4689 \end_inset
4690
4691
4692 \series default
4693  Generate code for the GameBoy Z80
4694 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
4695
4696 \end_inset
4697
4698  processor (Not actively maintained).
4699 \layout List
4700 \labelwidthstring 00.00.0000
4701
4702
4703 \series bold
4704 -mavr
4705 \begin_inset LatexCommand \index{-mavr}
4706
4707 \end_inset
4708
4709
4710 \series default
4711  Generate code for the Atmel AVR
4712 \begin_inset LatexCommand \index{AVR}
4713
4714 \end_inset
4715
4716  processor (In development, not complete).
4717  AVR users should probably have a look at avr-gcc
4718 \begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
4719
4720 \end_inset
4721
4722 .
4723 \layout Comment
4724
4725 I think it is fair to direct users there for now.
4726  Open source is also about avoiding unnecessary work .
4727  But I didn't find the 'official' link.
4728 \layout List
4729 \labelwidthstring 00.00.0000
4730
4731
4732 \series bold
4733 -mpic14
4734 \begin_inset LatexCommand \index{-mpic14}
4735
4736 \end_inset
4737
4738
4739 \series default
4740  Generate code for the Microchip PIC 14
4741 \begin_inset LatexCommand \index{PIC14}
4742
4743 \end_inset
4744
4745 -bit processors (p16f84 and variants.
4746  In development, not complete).
4747 \layout Comment
4748
4749 p16f627 p16f628 p16f84 p16f873 p16f877?
4750 \layout List
4751 \labelwidthstring 00.00.0000
4752
4753
4754 \series bold
4755 -mpic16
4756 \begin_inset LatexCommand \index{-mpic16}
4757
4758 \end_inset
4759
4760
4761 \series default
4762  Generate code for the Microchip PIC 16
4763 \begin_inset LatexCommand \index{PIC16}
4764
4765 \end_inset
4766
4767 -bit processors (p18f452 and variants.
4768  In development, not complete).
4769 \layout List
4770 \labelwidthstring 00.00.0000
4771
4772
4773 \series bold
4774 -mtlcs900h
4775 \series default
4776  Generate code for the Toshiba TLCS-900H
4777 \begin_inset LatexCommand \index{TLCS-900H}
4778
4779 \end_inset
4780
4781  processor (Not maintained, not complete).
4782 \layout List
4783 \labelwidthstring 00.00.0000
4784
4785
4786 \series bold
4787 -mxa51
4788 \begin_inset LatexCommand \index{-mxa51}
4789
4790 \end_inset
4791
4792
4793 \series default
4794  Generate code for the Phillips XA51
4795 \begin_inset LatexCommand \index{XA51}
4796
4797 \end_inset
4798
4799  processor (Not maintained, not complete).
4800 \layout Subsection
4801
4802 Preprocessor Options
4803 \begin_inset LatexCommand \index{Options preprocessor}
4804
4805 \end_inset
4806
4807
4808 \begin_inset LatexCommand \index{Preprocessor options}
4809
4810 \end_inset
4811
4812
4813 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4814
4815 \end_inset
4816
4817
4818 \layout List
4819 \labelwidthstring 00.00.0000
4820
4821
4822 \series bold
4823 -I<path>
4824 \begin_inset LatexCommand \index{-I<path>}
4825
4826 \end_inset
4827
4828
4829 \series default
4830  The additional location where the pre processor will look for <..h> or
4831 \begin_inset Quotes eld
4832 \end_inset
4833
4834 ..h
4835 \begin_inset Quotes erd
4836 \end_inset
4837
4838  files.
4839 \layout List
4840 \labelwidthstring 00.00.0000
4841
4842
4843 \series bold
4844 -D<macro[=value]>
4845 \begin_inset LatexCommand \index{-D<macro[=value]>}
4846
4847 \end_inset
4848
4849
4850 \series default
4851  Command line definition of macros.
4852  Passed to the preprocessor.
4853 \layout List
4854 \labelwidthstring 00.00.0000
4855
4856
4857 \series bold
4858 -M
4859 \begin_inset LatexCommand \index{-M}
4860
4861 \end_inset
4862
4863
4864 \series default
4865  Tell the preprocessor to output a rule suitable for make describing the
4866  dependencies of each object file.
4867  For each source file, the preprocessor outputs one make-rule whose target
4868  is the object file name for that source file and whose dependencies are
4869  all the files `#include'd in it.
4870  This rule may be a single line or may be continued with `
4871 \backslash
4872 '-newline if it is long.
4873  The list of rules is printed on standard output instead of the preprocessed
4874  C program.
4875  `-M' implies `-E
4876 \begin_inset LatexCommand \index{-E}
4877
4878 \end_inset
4879
4880 '.
4881 \layout List
4882 \labelwidthstring 00.00.0000
4883
4884
4885 \series bold
4886 -C
4887 \begin_inset LatexCommand \index{-C}
4888
4889 \end_inset
4890
4891
4892 \series default
4893  Tell the preprocessor not to discard comments.
4894  Used with the `-E' option.
4895 \layout List
4896 \labelwidthstring 00.00.0000
4897
4898
4899 \series bold
4900 -MM
4901 \begin_inset LatexCommand \index{-MM}
4902
4903 \end_inset
4904
4905
4906 \size large
4907 \bar under
4908
4909 \series default
4910 \size default
4911 \bar default
4912 Like `-M' but the output mentions only the user header files included with
4913  `#include
4914 \begin_inset Quotes eld
4915 \end_inset
4916
4917 file"'.
4918  System header files included with `#include <file>' are omitted.
4919 \layout List
4920 \labelwidthstring 00.00.0000
4921
4922
4923 \series bold
4924 -Aquestion(answer)
4925 \begin_inset LatexCommand \index{-Aquestion(answer)}
4926
4927 \end_inset
4928
4929
4930 \series default
4931  Assert the answer answer for question, in case it is tested with a preprocessor
4932  conditional such as `#if #question(answer)'.
4933  `-A-' disables the standard assertions that normally describe the target
4934  machine.
4935 \layout List
4936 \labelwidthstring 00.00.0000
4937
4938
4939 \series bold
4940 -Umacro
4941 \begin_inset LatexCommand \index{-Umacro}
4942
4943 \end_inset
4944
4945
4946 \series default
4947  Undefine macro macro.
4948  `-U' options are evaluated after all `-D' options, but before any `-include'
4949  and `-imacros' options.
4950 \layout List
4951 \labelwidthstring 00.00.0000
4952
4953
4954 \series bold
4955 -dM
4956 \begin_inset LatexCommand \index{-dM}
4957
4958 \end_inset
4959
4960
4961 \series default
4962  Tell the preprocessor to output only a list of the macro definitions that
4963  are in effect at the end of preprocessing.
4964  Used with the `-E' option.
4965 \layout List
4966 \labelwidthstring 00.00.0000
4967
4968
4969 \series bold
4970 -dD
4971 \begin_inset LatexCommand \index{-dD}
4972
4973 \end_inset
4974
4975
4976 \series default
4977  Tell the preprocessor to pass all macro definitions into the output, in
4978  their proper sequence in the rest of the output.
4979 \layout List
4980 \labelwidthstring 00.00.0000
4981
4982
4983 \series bold
4984 -dN
4985 \begin_inset LatexCommand \index{-dN}
4986
4987 \end_inset
4988
4989
4990 \size large
4991 \bar under
4992
4993 \series default
4994 \size default
4995 \bar default
4996 Like `-dD' except that the macro arguments and contents are omitted.
4997  Only `#define name' is included in the output.
4998 \layout List
4999 \labelwidthstring 00.00.0000
5000
5001
5002 \series bold
5003 -Wp\SpecialChar ~
5004 preprocessorOption[,preprocessorOption]
5005 \series default
5006
5007 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5008
5009 \end_inset
5010
5011 ...
5012  Pass the preprocessorOption to the preprocessor
5013 \family typewriter
5014 sdcpp
5015 \family default
5016
5017 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5018
5019 \end_inset
5020
5021 .
5022  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5023  Collection (gcc), if you need more dedicated options please refer to the
5024  documentation at
5025 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5026
5027 \end_inset
5028
5029 .
5030 \layout Subsection
5031
5032 Linker Options
5033 \begin_inset LatexCommand \index{Options linker}
5034
5035 \end_inset
5036
5037
5038 \begin_inset LatexCommand \index{Linker options}
5039
5040 \end_inset
5041
5042
5043 \layout List
5044 \labelwidthstring 00.00.0000
5045
5046
5047 \series bold
5048 -L\SpecialChar ~
5049 -
5050 \series default
5051
5052 \begin_inset ERT
5053 status Collapsed
5054
5055 \layout Standard
5056
5057 \backslash
5058 /
5059 \end_inset
5060
5061
5062 \series bold
5063 -lib-path
5064 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5065
5066 \end_inset
5067
5068
5069 \begin_inset LatexCommand \index{-L -\/-lib-path}
5070
5071 \end_inset
5072
5073
5074 \series default
5075 \SpecialChar ~
5076 <absolute path to additional libraries> This option is passed to the linkage
5077  editor's additional libraries
5078 \begin_inset LatexCommand \index{Libraries}
5079
5080 \end_inset
5081
5082  search path.
5083  The path name must be absolute.
5084  Additional library files may be specified in the command line.
5085  See section Compiling programs for more details.
5086 \layout List
5087 \labelwidthstring 00.00.0000
5088
5089
5090 \series bold
5091 -
5092 \begin_inset ERT
5093 status Collapsed
5094
5095 \layout Standard
5096
5097 \backslash
5098 /
5099 \end_inset
5100
5101 -xram-loc
5102 \series default
5103
5104 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5105
5106 \end_inset
5107
5108 \SpecialChar ~
5109 <Value> The start location of the external ram
5110 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5111
5112 \end_inset
5113
5114 , default value is 0.
5115  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5116 \begin_inset ERT
5117 status Collapsed
5118
5119 \layout Standard
5120
5121 \backslash
5122 /
5123 \end_inset
5124
5125 -xram-loc 0x8000 or -
5126 \begin_inset ERT
5127 status Collapsed
5128
5129 \layout Standard
5130
5131 \backslash
5132 /
5133 \end_inset
5134
5135 -xram-loc 32768.
5136 \layout List
5137 \labelwidthstring 00.00.0000
5138
5139
5140 \series bold
5141 -
5142 \begin_inset ERT
5143 status Collapsed
5144
5145 \layout Standard
5146
5147 \backslash
5148 /
5149 \end_inset
5150
5151 -code-loc
5152 \series default
5153
5154 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5155
5156 \end_inset
5157
5158 \SpecialChar ~
5159 <Value> The start location of the code
5160 \begin_inset LatexCommand \index{code}
5161
5162 \end_inset
5163
5164  segment, default value 0.
5165  Note when this option is used the interrupt vector table is also relocated
5166  to the given address.
5167  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5168 \begin_inset ERT
5169 status Collapsed
5170
5171 \layout Standard
5172
5173 \backslash
5174 /
5175 \end_inset
5176
5177 -code-loc 0x8000 or -
5178 \begin_inset ERT
5179 status Collapsed
5180
5181 \layout Standard
5182
5183 \backslash
5184 /
5185 \end_inset
5186
5187 -code-loc 32768.
5188 \layout List
5189 \labelwidthstring 00.00.0000
5190
5191
5192 \series bold
5193 -
5194 \begin_inset ERT
5195 status Collapsed
5196
5197 \layout Standard
5198
5199 \backslash
5200 /
5201 \end_inset
5202
5203 -stack-loc
5204 \series default
5205
5206 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5207
5208 \end_inset
5209
5210 \SpecialChar ~
5211 <Value> By default the stack
5212 \begin_inset LatexCommand \index{stack}
5213
5214 \end_inset
5215
5216  is placed after the data segment.
5217  Using this option the stack can be placed anywhere in the internal memory
5218  space of the 8051.
5219  The value entered can be in Hexadecimal or Decimal format, e.g.
5220  -
5221 \begin_inset ERT
5222 status Collapsed
5223
5224 \layout Standard
5225
5226 \backslash
5227 /
5228 \end_inset
5229
5230 -stack-loc 0x20 or -
5231 \begin_inset ERT
5232 status Collapsed
5233
5234 \layout Standard
5235
5236 \backslash
5237 /
5238 \end_inset
5239
5240 -stack-loc 32.
5241  Since the sp register is incremented before a push or call, the initial
5242  sp will be set to one byte prior the provided value.
5243  The provided value should not overlap any other memory areas such as used
5244  register banks or the data segment and with enough space for the current
5245  application.
5246 \layout List
5247 \labelwidthstring 00.00.0000
5248
5249
5250 \series bold
5251 -
5252 \begin_inset ERT
5253 status Collapsed
5254
5255 \layout Standard
5256
5257 \backslash
5258 /
5259 \end_inset
5260
5261 -data-loc
5262 \series default
5263
5264 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5265
5266 \end_inset
5267
5268 \SpecialChar ~
5269 <Value> The start location of the internal ram data
5270 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5271
5272 \end_inset
5273
5274  segment.
5275  The value entered can be in Hexadecimal or Decimal format, eg.
5276  -
5277 \begin_inset ERT
5278 status Collapsed
5279
5280 \layout Standard
5281
5282 \backslash
5283 /
5284 \end_inset
5285
5286 -data-loc 0x20 or -
5287 \begin_inset ERT
5288 status Collapsed
5289
5290 \layout Standard
5291
5292 \backslash
5293 /
5294 \end_inset
5295
5296 -data-loc 32.
5297  (By default, the start location of the internal ram data segment  is set
5298  as low as possible in memory, taking into account the used register banks
5299  and the bit segment at address 0x20.
5300  For example if register banks 0 and 1 are used without bit variables, the
5301  data segment will be set, if -
5302 \begin_inset ERT
5303 status Collapsed
5304
5305 \layout Standard
5306
5307 \backslash
5308 /
5309 \end_inset
5310
5311 -data-loc is not used, to location 0x10.)
5312 \layout List
5313 \labelwidthstring 00.00.0000
5314
5315
5316 \series bold
5317 -
5318 \begin_inset ERT
5319 status Collapsed
5320
5321 \layout Standard
5322
5323 \backslash
5324 /
5325 \end_inset
5326
5327 -idata-loc
5328 \series default
5329
5330 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5331
5332 \end_inset
5333
5334 \SpecialChar ~
5335 <Value> The start location of the indirectly addressable internal ram
5336 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5337
5338 \end_inset
5339
5340  of the 8051, default value is 0x80.
5341  The value entered can be in Hexadecimal or Decimal format, eg.
5342  -
5343 \begin_inset ERT
5344 status Collapsed
5345
5346 \layout Standard
5347
5348 \backslash
5349 /
5350 \end_inset
5351
5352 -idata-loc 0x88 or -
5353 \begin_inset ERT
5354 status Collapsed
5355
5356 \layout Standard
5357
5358 \backslash
5359 /
5360 \end_inset
5361
5362 -idata-loc 136.
5363 \layout List
5364 \labelwidthstring 00.00.0000
5365
5366
5367 \series bold
5368 -
5369 \begin_inset ERT
5370 status Collapsed
5371
5372 \layout Standard
5373
5374 \backslash
5375 /
5376 \end_inset
5377
5378 -bit-loc
5379 \series default
5380 \SpecialChar ~
5381 <Value> The start location of the bit
5382 \begin_inset LatexCommand \index{bit}
5383
5384 \end_inset
5385
5386  addressable internal ram of the 8051.
5387  This is
5388 \emph on
5389 not
5390 \emph default
5391  implemented yet.
5392  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5393 -bBSEG=<Value>.
5394 \layout List
5395 \labelwidthstring 00.00.0000
5396
5397
5398 \series bold
5399 -
5400 \begin_inset ERT
5401 status Collapsed
5402
5403 \layout Standard
5404
5405 \backslash
5406 /
5407 \end_inset
5408
5409 -out-fmt-ihx
5410 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5411
5412 \end_inset
5413
5414
5415 \bar under
5416
5417 \series default
5418 \bar default
5419 The linker output (final object code) is in Intel Hex format.
5420 \begin_inset LatexCommand \index{Intel hex format}
5421
5422 \end_inset
5423
5424  This is the default option.
5425  The format itself is documented in the documentation of srecord
5426 \begin_inset LatexCommand \index{srecord (tool)}
5427
5428 \end_inset
5429
5430 .
5431 \layout List
5432 \labelwidthstring 00.00.0000
5433
5434
5435 \series bold
5436 -
5437 \begin_inset ERT
5438 status Collapsed
5439
5440 \layout Standard
5441
5442 \backslash
5443 /
5444 \end_inset
5445
5446 -out-fmt-s19
5447 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5448
5449 \end_inset
5450
5451
5452 \bar under
5453
5454 \series default
5455 \bar default
5456 The linker output (final object code) is in Motorola S19 format
5457 \begin_inset LatexCommand \index{Motorola S19 format}
5458
5459 \end_inset
5460
5461 .
5462  The format itself is documented in the documentation of srecord.
5463 \layout List
5464 \labelwidthstring 00.00.0000
5465
5466
5467 \series bold
5468 -Wl\SpecialChar ~
5469 linkOption[,linkOption]
5470 \series default
5471
5472 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5473
5474 \end_inset
5475
5476 ...
5477  Pass the linkOption to the linker.
5478  See file sdcc/as/doc/asxhtm.html for more on linker options.
5479 \layout Subsection
5480
5481 MCS51 Options
5482 \begin_inset LatexCommand \index{Options MCS51}
5483
5484 \end_inset
5485
5486
5487 \begin_inset LatexCommand \index{MCS51 options}
5488
5489 \end_inset
5490
5491
5492 \layout List
5493 \labelwidthstring 00.00.0000
5494
5495
5496 \series bold
5497 -
5498 \begin_inset ERT
5499 status Collapsed
5500
5501 \layout Standard
5502
5503 \backslash
5504 /
5505 \end_inset
5506
5507 -model-small
5508 \begin_inset LatexCommand \index{-\/-model-small}
5509
5510 \end_inset
5511
5512
5513 \series default
5514 \size large
5515 \emph on
5516
5517 \size default
5518 \emph default
5519 Generate code for Small Model programs, see section Memory Models for more
5520  details.
5521  This is the default model.
5522 \layout List
5523 \labelwidthstring 00.00.0000
5524
5525
5526 \series bold
5527 -
5528 \begin_inset ERT
5529 status Collapsed
5530
5531 \layout Standard
5532
5533 \backslash
5534 /
5535 \end_inset
5536
5537 -model-large
5538 \begin_inset LatexCommand \index{-\/-model-large}
5539
5540 \end_inset
5541
5542
5543 \series default
5544  Generate code for Large model programs, see section Memory Models for more
5545  details.
5546  If this option is used all source files in the project have to be compiled
5547  with this option.
5548 \layout List
5549 \labelwidthstring 00.00.0000
5550
5551
5552 \series bold
5553 -
5554 \begin_inset ERT
5555 status Collapsed
5556
5557 \layout Standard
5558
5559 \backslash
5560 /
5561 \end_inset
5562
5563 -xstack
5564 \begin_inset LatexCommand \index{-\/-xstack}
5565
5566 \end_inset
5567
5568
5569 \series default
5570  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5571  variables and passing parameters.
5572  See section
5573 \begin_inset LatexCommand \ref{sub:External-Stack}
5574
5575 \end_inset
5576
5577 \SpecialChar ~
5578  External Stack for more details.
5579 \layout List
5580 \labelwidthstring 00.00.0000
5581
5582
5583 \series bold
5584 -
5585 \begin_inset ERT
5586 status Collapsed
5587
5588 \layout Standard
5589
5590 \backslash
5591 /
5592 \end_inset
5593
5594 -iram-size
5595 \series default
5596 \SpecialChar ~
5597 <Value>
5598 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
5599
5600 \end_inset
5601
5602  Causes the linker to check if the internal ram usage is within limits of
5603  the given value.
5604 \layout List
5605 \labelwidthstring 00.00.0000
5606
5607
5608 \series bold
5609 -
5610 \begin_inset ERT
5611 status Collapsed
5612
5613 \layout Standard
5614
5615 \backslash
5616 /
5617 \end_inset
5618
5619 -xram-size
5620 \series default
5621 \SpecialChar ~
5622 <Value>
5623 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
5624
5625 \end_inset
5626
5627  Causes the linker to check if the external ram usage is within limits of
5628  the given value.
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 -code-size
5645 \series default
5646 \SpecialChar ~
5647 <Value>
5648 \begin_inset LatexCommand \index{-\/-code-size <Value>}
5649
5650 \end_inset
5651
5652  Causes the linker to check if the code memory usage is within limits of
5653  the given value.
5654 \layout Subsection
5655
5656 DS390 / DS400 Options
5657 \begin_inset LatexCommand \index{Options DS390}
5658
5659 \end_inset
5660
5661
5662 \begin_inset LatexCommand \index{DS390 options}
5663
5664 \end_inset
5665
5666
5667 \layout List
5668 \labelwidthstring 00.00.0000
5669
5670
5671 \series bold
5672 -
5673 \begin_inset ERT
5674 status Collapsed
5675
5676 \layout Standard
5677
5678 \backslash
5679 /
5680 \end_inset
5681
5682 -model-flat24
5683 \series default
5684
5685 \begin_inset LatexCommand \index{-\/-model-flat24}
5686
5687 \end_inset
5688
5689
5690 \size large
5691 \emph on
5692
5693 \size default
5694 \emph default
5695 Generate 24-bit flat mode code.
5696  This is the one and only that the ds390 code generator supports right now
5697  and is default when using
5698 \emph on
5699 -mds390
5700 \emph default
5701 .
5702  See section Memory Models for more details.
5703 \layout List
5704 \labelwidthstring 00.00.0000
5705
5706
5707 \series bold
5708 -
5709 \begin_inset ERT
5710 status Collapsed
5711
5712 \layout Standard
5713
5714 \backslash
5715 /
5716 \end_inset
5717
5718 -protect-sp-update
5719 \begin_inset LatexCommand \index{-\/-protect-sp-update}
5720
5721 \end_inset
5722
5723
5724 \series default
5725  disable interrupts during ESP:SP updates.
5726 \layout List
5727 \labelwidthstring 00.00.0000
5728
5729
5730 \series bold
5731 -
5732 \begin_inset ERT
5733 status Collapsed
5734
5735 \layout Standard
5736
5737 \backslash
5738 /
5739 \end_inset
5740
5741 -stack-10bit
5742 \series default
5743
5744 \begin_inset LatexCommand \index{-\/-stack-10bit}
5745
5746 \end_inset
5747
5748  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
5749  This is the one and only that the ds390 code generator supports right now
5750  and is default when using
5751 \emph on
5752 -mds390
5753 \emph default
5754 .
5755  In this mode, the stack is located in the lower 1K of the internal RAM,
5756  which is mapped to 0x400000.
5757  Note that the support is incomplete, since it still uses a single byte
5758  as the stack pointer.
5759  This means that only the lower 256 bytes of the potential 1K stack space
5760  will actually be used.
5761  However, this does allow you to reclaim the precious 256 bytes of low RAM
5762  for use for the DATA and IDATA segments.
5763  The compiler will not generate any code to put the processor into 10 bit
5764  stack mode.
5765  It is important to ensure that the processor is in this mode before calling
5766  any re-entrant functions compiled with this option.
5767  In principle, this should work with the
5768 \emph on
5769 -
5770 \begin_inset ERT
5771 status Collapsed
5772
5773 \layout Standard
5774
5775 \backslash
5776 /
5777 \end_inset
5778
5779 -stack-auto
5780 \begin_inset LatexCommand \index{-\/-stack-auto}
5781
5782 \end_inset
5783
5784
5785 \emph default
5786  option, but that has not been tested.
5787  It is incompatible with the
5788 \emph on
5789 -
5790 \begin_inset ERT
5791 status Collapsed
5792
5793 \layout Standard
5794
5795 \backslash
5796 /
5797 \end_inset
5798
5799 -xstack
5800 \begin_inset LatexCommand \index{-\/-xstack}
5801
5802 \end_inset
5803
5804
5805 \emph default
5806  option.
5807  It also only makes sense if the processor is in 24 bit contiguous addressing
5808  mode (see the
5809 \emph on
5810 -
5811 \begin_inset ERT
5812 status Collapsed
5813
5814 \layout Standard
5815
5816 \backslash
5817 /
5818 \end_inset
5819
5820 -model-flat24 option
5821 \emph default
5822 ).
5823 \layout List
5824 \labelwidthstring 00.00.0000
5825
5826
5827 \series bold
5828 -
5829 \begin_inset ERT
5830 status Collapsed
5831
5832 \layout Standard
5833
5834 \backslash
5835 /
5836 \end_inset
5837
5838 -stack-probe
5839 \begin_inset LatexCommand \index{-\/-stack-probe}
5840
5841 \end_inset
5842
5843
5844 \series default
5845  insert call to function __stack_probe at each function prologue.
5846 \layout List
5847 \labelwidthstring 00.00.0000
5848
5849
5850 \series bold
5851 -
5852 \begin_inset ERT
5853 status Collapsed
5854
5855 \layout Standard
5856
5857 \backslash
5858 /
5859 \end_inset
5860
5861 -tini-libid
5862 \begin_inset LatexCommand \index{-\/-tini-libid}
5863
5864 \end_inset
5865
5866
5867 \series default
5868  <nnnn> LibraryID used in -mTININative.
5869
5870 \layout List
5871 \labelwidthstring 00.00.0000
5872
5873
5874 \series bold
5875 -
5876 \begin_inset ERT
5877 status Collapsed
5878
5879 \layout Standard
5880
5881 \backslash
5882 /
5883 \end_inset
5884
5885 -use-accelerator
5886 \begin_inset LatexCommand \index{-\/-use-accelerator}
5887
5888 \end_inset
5889
5890
5891 \series default
5892  generate code for DS390 Arithmetic Accelerator.
5893
5894 \layout Subsection
5895
5896 PIC Options
5897 \begin_inset LatexCommand \index{Options PIC}
5898
5899 \end_inset
5900
5901
5902 \begin_inset LatexCommand \index{PIC options}
5903
5904 \end_inset
5905
5906
5907 \layout List
5908 \labelwidthstring 00.00.0000
5909
5910
5911 \series bold
5912 -
5913 \begin_inset ERT
5914 status Collapsed
5915
5916 \layout Standard
5917
5918 \backslash
5919 /
5920 \end_inset
5921
5922 -gen-banksel
5923 \begin_inset LatexCommand \index{-\/-gen-banksel}
5924
5925 \end_inset
5926
5927
5928 \series default
5929  enable the generation of banksel assembler directives in the PIC16
5930 \begin_inset LatexCommand \index{PIC16}
5931
5932 \end_inset
5933
5934  port.
5935 \layout Subsection
5936
5937 Z80 Options
5938 \begin_inset LatexCommand \index{Options Z80}
5939
5940 \end_inset
5941
5942
5943 \begin_inset LatexCommand \index{Z80 options}
5944
5945 \end_inset
5946
5947
5948 \layout List
5949 \labelwidthstring 00.00.0000
5950
5951
5952 \series bold
5953 -
5954 \begin_inset ERT
5955 status Collapsed
5956
5957 \layout Standard
5958
5959 \backslash
5960 /
5961 \end_inset
5962
5963 -callee-saves-bc
5964 \series default
5965
5966 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
5967
5968 \end_inset
5969
5970
5971 \size large
5972 \emph on
5973
5974 \size default
5975 \emph default
5976 Force a called function to always save BC.
5977 \layout List
5978 \labelwidthstring 00.00.0000
5979
5980
5981 \series bold
5982 -
5983 \begin_inset ERT
5984 status Collapsed
5985
5986 \layout Standard
5987
5988 \backslash
5989 /
5990 \end_inset
5991
5992 -no-std-crt0
5993 \series default
5994
5995 \begin_inset LatexCommand \index{-\/-no-std-crt0}
5996
5997 \end_inset
5998
5999  When linking, skip the standard crt0.o object file.
6000  You must provide your own crt0.o for your system when linking.
6001
6002 \layout Subsection
6003
6004 Optimization Options
6005 \begin_inset LatexCommand \index{Options optimization}
6006
6007 \end_inset
6008
6009
6010 \begin_inset LatexCommand \index{Optimization options}
6011
6012 \end_inset
6013
6014
6015 \layout List
6016 \labelwidthstring 00.00.0000
6017
6018
6019 \series bold
6020 -
6021 \begin_inset ERT
6022 status Collapsed
6023
6024 \layout Standard
6025
6026 \backslash
6027 /
6028 \end_inset
6029
6030 -nogcse
6031 \begin_inset LatexCommand \index{-\/-nogcse}
6032
6033 \end_inset
6034
6035
6036 \series default
6037  Will not do global subexpression elimination, this option may be used when
6038  the compiler creates undesirably large stack/data spaces to store compiler
6039  temporaries.
6040  A warning message will be generated when this happens and the compiler
6041  will indicate the number of extra bytes it allocated.
6042  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6043 nogcse
6044 \begin_inset LatexCommand \index{\#pragma nogcse}
6045
6046 \end_inset
6047
6048  can be used to turn off global subexpression elimination
6049 \begin_inset LatexCommand \index{Subexpression elimination}
6050
6051 \end_inset
6052
6053  for a given function only.
6054 \layout List
6055 \labelwidthstring 00.00.0000
6056
6057
6058 \series bold
6059 -
6060 \begin_inset ERT
6061 status Collapsed
6062
6063 \layout Standard
6064
6065 \backslash
6066 /
6067 \end_inset
6068
6069 -noinvariant
6070 \begin_inset LatexCommand \index{-\/-noinvariant}
6071
6072 \end_inset
6073
6074
6075 \series default
6076  Will not do loop invariant optimizations, this may be turned off for reasons
6077  explained for the previous option.
6078  For more details of loop optimizations performed see section Loop Invariants.
6079  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6080 noinvariant
6081 \begin_inset LatexCommand \index{\#pragma noinvariant}
6082
6083 \end_inset
6084
6085  can be used to turn off invariant optimizations for a given function only.
6086 \layout List
6087 \labelwidthstring 00.00.0000
6088
6089
6090 \series bold
6091 -
6092 \begin_inset ERT
6093 status Collapsed
6094
6095 \layout Standard
6096
6097 \backslash
6098 /
6099 \end_inset
6100
6101 -noinduction
6102 \begin_inset LatexCommand \index{-\/-noinduction}
6103
6104 \end_inset
6105
6106
6107 \series default
6108  Will not do loop induction optimizations, see section strength reduction
6109  for more details.
6110  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6111 noinduction
6112 \begin_inset LatexCommand \index{\#pragma noinduction}
6113
6114 \end_inset
6115
6116  can be used to turn off induction optimizations for a given function only.
6117 \layout List
6118 \labelwidthstring 00.00.0000
6119
6120
6121 \series bold
6122 -
6123 \begin_inset ERT
6124 status Collapsed
6125
6126 \layout Standard
6127
6128 \backslash
6129 /
6130 \end_inset
6131
6132 -nojtbound
6133 \begin_inset LatexCommand \index{-\/-nojtbound}
6134
6135 \end_inset
6136
6137
6138 \size large
6139 \bar under
6140
6141 \series default
6142 \size default
6143 \bar default
6144  Will not generate boundary condition check when switch statements
6145 \begin_inset LatexCommand \index{switch statement}
6146
6147 \end_inset
6148
6149  are implemented using jump-tables.
6150  See section
6151 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6152
6153 \end_inset
6154
6155 \SpecialChar ~
6156 Switch Statements for more details.
6157  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6158 nojtbound
6159 \begin_inset LatexCommand \index{\#pragma nojtbound}
6160
6161 \end_inset
6162
6163  can be used to turn off boundary checking for jump tables for a given function
6164  only.
6165 \layout List
6166 \labelwidthstring 00.00.0000
6167
6168
6169 \series bold
6170 -
6171 \begin_inset ERT
6172 status Collapsed
6173
6174 \layout Standard
6175
6176 \backslash
6177 /
6178 \end_inset
6179
6180 -noloopreverse
6181 \begin_inset LatexCommand \index{-\/-noloopreverse}
6182
6183 \end_inset
6184
6185
6186 \series default
6187 \size large
6188
6189 \size default
6190 Will not do loop reversal
6191 \begin_inset LatexCommand \index{Loop reversing}
6192
6193 \end_inset
6194
6195 optimization.
6196 \layout List
6197 \labelwidthstring 00.00.0000
6198
6199 -
6200 \begin_inset ERT
6201 status Collapsed
6202
6203 \layout Standard
6204
6205 \backslash
6206 /
6207 \end_inset
6208
6209 -
6210 \series bold
6211 nolabelopt
6212 \series default
6213
6214 \begin_inset LatexCommand \index{-\/-nolabelopt }
6215
6216 \end_inset
6217
6218 Will not optimize labels (makes the dumpfiles more readable).
6219 \layout List
6220 \labelwidthstring 00.00.0000
6221
6222
6223 \series bold
6224 -
6225 \begin_inset ERT
6226 status Collapsed
6227
6228 \layout Standard
6229
6230 \backslash
6231 /
6232 \end_inset
6233
6234 -no-xinit-opt
6235 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6236
6237 \end_inset
6238
6239
6240 \series default
6241  Will not memcpy initialized data from code space into xdata space.
6242  This saves a few bytes in code space if you don't have initialized data.
6243 \layout List
6244 \labelwidthstring 00.00.0000
6245
6246
6247 \series bold
6248 -
6249 \begin_inset ERT
6250 status Collapsed
6251
6252 \layout Standard
6253
6254 \backslash
6255 /
6256 \end_inset
6257
6258 -nooverlay
6259 \begin_inset LatexCommand \index{-\/-nooverlay}
6260
6261 \end_inset
6262
6263
6264 \series default
6265   The compiler will not overlay parameters and local variables of any function,
6266  see section Parameters and local variables for more details.
6267 \layout List
6268 \labelwidthstring 00.00.0000
6269
6270
6271 \series bold
6272 -
6273 \begin_inset ERT
6274 status Collapsed
6275
6276 \layout Standard
6277
6278 \backslash
6279 /
6280 \end_inset
6281
6282 -no-peep
6283 \begin_inset LatexCommand \index{-\/-no-peep}
6284
6285 \end_inset
6286
6287
6288 \series default
6289  Disable peep-hole optimization.
6290 \layout List
6291 \labelwidthstring 00.00.0000
6292
6293
6294 \series bold
6295 -
6296 \begin_inset ERT
6297 status Collapsed
6298
6299 \layout Standard
6300
6301 \backslash
6302 /
6303 \end_inset
6304
6305 -peep-file
6306 \series default
6307
6308 \begin_inset LatexCommand \index{-\/-peep-file}
6309
6310 \end_inset
6311
6312 \SpecialChar ~
6313 <filename> This option can be used to use additional rules to be used by
6314  the peep hole optimizer.
6315  See section
6316 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6317
6318 \end_inset
6319
6320 \SpecialChar ~
6321 Peep Hole optimizations for details on how to write these rules.
6322 \layout List
6323 \labelwidthstring 00.00.0000
6324
6325
6326 \series bold
6327 -
6328 \begin_inset ERT
6329 status Collapsed
6330
6331 \layout Standard
6332
6333 \backslash
6334 /
6335 \end_inset
6336
6337 -peep-asm
6338 \begin_inset LatexCommand \index{-\/-peep-asm}
6339
6340 \end_inset
6341
6342
6343 \series default
6344   Pass the inline assembler code through the peep hole optimizer.
6345  This can cause unexpected changes to inline assembler code, please go through
6346  the peephole optimizer
6347 \begin_inset LatexCommand \index{Peephole optimizer}
6348
6349 \end_inset
6350
6351  rules defined in the source file tree '<target>/peeph.def' before using
6352  this option.
6353 \layout Subsection
6354
6355 Other Options
6356 \begin_inset LatexCommand \index{Options other}
6357
6358 \end_inset
6359
6360
6361 \layout List
6362 \labelwidthstring 00.00.0000
6363
6364
6365 \series bold
6366 -c\SpecialChar ~
6367 -
6368 \begin_inset ERT
6369 status Collapsed
6370
6371 \layout Standard
6372
6373 \backslash
6374 /
6375 \end_inset
6376
6377 -compile-only
6378 \begin_inset LatexCommand \index{-\/-compile-only}
6379
6380 \end_inset
6381
6382
6383 \begin_inset LatexCommand \index{-c -\/-compile-only}
6384
6385 \end_inset
6386
6387
6388 \series default
6389  will compile and assemble the source, but will not call the linkage editor.
6390 \layout List
6391 \labelwidthstring 00.00.0000
6392
6393
6394 \series bold
6395 -
6396 \series default
6397
6398 \begin_inset ERT
6399 status Collapsed
6400
6401 \layout Standard
6402
6403 \backslash
6404 /
6405 \end_inset
6406
6407
6408 \series bold
6409 -c1mode
6410 \begin_inset LatexCommand \index{-\/-c1mode}
6411
6412 \end_inset
6413
6414
6415 \series default
6416  reads the preprocessed source from standard input and compiles it.
6417  The file name for the assembler output must be specified using the -o option.
6418 \layout List
6419 \labelwidthstring 00.00.0000
6420
6421
6422 \series bold
6423 -E
6424 \begin_inset LatexCommand \index{-E}
6425
6426 \end_inset
6427
6428
6429 \series default
6430  Run only the C preprocessor.
6431  Preprocess all the C source files specified and output the results to standard
6432  output.
6433 \layout List
6434 \labelwidthstring 00.00.0000
6435
6436
6437 \series bold
6438 -o\SpecialChar ~
6439 <path/file>
6440 \begin_inset LatexCommand \index{-o <path/file>}
6441
6442 \end_inset
6443
6444
6445 \series default
6446 The output path resp.
6447  file where everything will be placed.
6448  If the parameter is a path, it must have a trailing slash (or backslash
6449  for the Windows binaries) to be recognized as a path.
6450
6451 \layout List
6452 \labelwidthstring 00.00.0000
6453
6454
6455 \series bold
6456 -
6457 \begin_inset ERT
6458 status Collapsed
6459
6460 \layout Standard
6461
6462 \backslash
6463 /
6464 \end_inset
6465
6466 -stack-auto
6467 \begin_inset LatexCommand \index{-\/-stack-auto}
6468
6469 \end_inset
6470
6471
6472 \series default
6473 \size large
6474 \emph on
6475
6476 \size default
6477 \emph default
6478 All functions in the source file will be compiled as
6479 \emph on
6480 reentrant
6481 \emph default
6482
6483 \begin_inset LatexCommand \index{reentrant}
6484
6485 \end_inset
6486
6487 , i.e.
6488  the parameters and local variables will be allocated on the stack
6489 \begin_inset LatexCommand \index{stack}
6490
6491 \end_inset
6492
6493 .
6494  see section Parameters and Local Variables for more details.
6495  If this option is used all source files in the project should be compiled
6496  with this option.
6497
6498 \layout List
6499 \labelwidthstring 00.00.0000
6500
6501
6502 \series bold
6503 -
6504 \begin_inset ERT
6505 status Collapsed
6506
6507 \layout Standard
6508
6509 \backslash
6510 /
6511 \end_inset
6512
6513 -callee-saves
6514 \begin_inset LatexCommand \index{-\/-callee-saves}
6515
6516 \end_inset
6517
6518  function1[,function2][,function3]....
6519
6520 \series default
6521  The compiler by default uses a caller saves convention for register saving
6522  across function calls, however this can cause unnecessary register pushing
6523  & popping when calling small functions from larger functions.
6524  This option can be used to switch the register saving convention for the
6525  function names specified.
6526  The compiler will not save registers when calling these functions, no extra
6527  code will be generated at the entry & exit (function prologue
6528 \series bold
6529
6530 \begin_inset LatexCommand \index{function prologue}
6531
6532 \end_inset
6533
6534
6535 \series default
6536  & epilogue
6537 \series bold
6538
6539 \begin_inset LatexCommand \index{function epilogue}
6540
6541 \end_inset
6542
6543
6544 \series default
6545 ) for these functions to save & restore the registers used by these functions,
6546  this can SUBSTANTIALLY reduce code & improve run time performance of the
6547  generated code.
6548  In the future the compiler (with inter procedural analysis) will be able
6549  to determine the appropriate scheme to use for each function call.
6550  DO NOT use this option for built-in functions such as _mulint..., if this
6551  option is used for a library function the appropriate library function
6552  needs to be recompiled with the same option.
6553  If the project consists of multiple source files then all the source file
6554  should be compiled with the same -
6555 \begin_inset ERT
6556 status Collapsed
6557
6558 \layout Standard
6559
6560 \backslash
6561 /
6562 \end_inset
6563
6564 -callee-saves option string.
6565  Also see #pragma\SpecialChar ~
6566 callee_saves
6567 \begin_inset LatexCommand \index{\#pragma callee\_saves}
6568
6569 \end_inset
6570
6571 .
6572 \layout List
6573 \labelwidthstring 00.00.0000
6574
6575
6576 \series bold
6577 -
6578 \begin_inset ERT
6579 status Collapsed
6580
6581 \layout Standard
6582
6583 \backslash
6584 /
6585 \end_inset
6586
6587 -debug
6588 \begin_inset LatexCommand \index{-\/-debug}
6589
6590 \end_inset
6591
6592
6593 \bar under
6594
6595 \series default
6596 \bar default
6597 When this option is used the compiler will generate debug information.
6598  The debug information collected in a file with .cdb extension can be used
6599  with the SDCDB.
6600  For more information see documentation for SDCDB.
6601  Another file with no extension contains debug information in AOMF or AOMF51
6602 \begin_inset LatexCommand \index{AOMF, AOMF51}
6603
6604 \end_inset
6605
6606  format which is commonly used by third party tools.
6607 \layout List
6608 \labelwidthstring 00.00.0000
6609
6610
6611 \series bold
6612 -S
6613 \begin_inset LatexCommand \index{-S}
6614
6615 \end_inset
6616
6617
6618 \size large
6619 \bar under
6620
6621 \series default
6622 \size default
6623 \bar default
6624 Stop after the stage of compilation proper; do not assemble.
6625  The output is an assembler code file for the input file specified.
6626 \layout List
6627 \labelwidthstring 00.00.0000
6628
6629
6630 \series bold
6631 -
6632 \begin_inset ERT
6633 status Collapsed
6634
6635 \layout Standard
6636
6637 \backslash
6638 /
6639 \end_inset
6640
6641 -int-long-reent
6642 \begin_inset LatexCommand \index{-\/-int-long-reent}
6643
6644 \end_inset
6645
6646
6647 \series default
6648  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
6649  Note by default these libraries are compiled as non-reentrant.
6650  See section Installation 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 -cyclomatic
6667 \begin_inset LatexCommand \index{-\/-cyclomatic}
6668
6669 \end_inset
6670
6671
6672 \bar under
6673
6674 \series default
6675 \bar default
6676 This option will cause the compiler to generate an information message for
6677  each function in the source file.
6678  The message contains some
6679 \emph on
6680 important
6681 \emph default
6682  information about the function.
6683  The number of edges and nodes the compiler detected in the control flow
6684  graph of the function, and most importantly the
6685 \emph on
6686 cyclomatic complexity
6687 \begin_inset LatexCommand \index{Cyclomatic complexity}
6688
6689 \end_inset
6690
6691
6692 \emph default
6693  see section on Cyclomatic Complexity for more details.
6694 \layout List
6695 \labelwidthstring 00.00.0000
6696
6697
6698 \series bold
6699 -
6700 \begin_inset ERT
6701 status Collapsed
6702
6703 \layout Standard
6704
6705 \backslash
6706 /
6707 \end_inset
6708
6709 -float-reent
6710 \begin_inset LatexCommand \index{-\/-float-reent}
6711
6712 \end_inset
6713
6714
6715 \series default
6716  Floating point library is compiled as reentrant
6717 \begin_inset LatexCommand \index{reentrant}
6718
6719 \end_inset
6720
6721 .
6722  See section Installation for more details.
6723 \layout List
6724 \labelwidthstring 00.00.0000
6725
6726
6727 \series bold
6728 -
6729 \begin_inset ERT
6730 status Collapsed
6731
6732 \layout Standard
6733
6734 \backslash
6735 /
6736 \end_inset
6737
6738 -main-return
6739 \begin_inset LatexCommand \index{-\/-main-return}
6740
6741 \end_inset
6742
6743
6744 \series default
6745  This option can be used when the code generated is called by a monitor
6746  program.
6747  The compiler will generate a 'ret' upon return from the 'main'
6748 \begin_inset LatexCommand \index{main return}
6749
6750 \end_inset
6751
6752  function.
6753  The default setting is to lock up i.e.
6754  generate a '
6755 \family typewriter
6756 sjmp .
6757 \family default
6758 '.
6759 \layout List
6760 \labelwidthstring 00.00.0000
6761
6762
6763 \series bold
6764 -
6765 \begin_inset ERT
6766 status Collapsed
6767
6768 \layout Standard
6769
6770 \backslash
6771 /
6772 \end_inset
6773
6774 -nostdincl
6775 \begin_inset LatexCommand \index{-\/-nostdincl}
6776
6777 \end_inset
6778
6779
6780 \series default
6781  This will prevent the compiler from passing on the default include path
6782  to the preprocessor.
6783 \layout List
6784 \labelwidthstring 00.00.0000
6785
6786
6787 \series bold
6788 -
6789 \begin_inset ERT
6790 status Collapsed
6791
6792 \layout Standard
6793
6794 \backslash
6795 /
6796 \end_inset
6797
6798 -nostdlib
6799 \begin_inset LatexCommand \index{-\/-nostdlib}
6800
6801 \end_inset
6802
6803
6804 \series default
6805  This will prevent the compiler from passing on the default library
6806 \begin_inset LatexCommand \index{Libraries}
6807
6808 \end_inset
6809
6810  path to the linker.
6811 \layout List
6812 \labelwidthstring 00.00.0000
6813
6814
6815 \series bold
6816 -
6817 \begin_inset ERT
6818 status Collapsed
6819
6820 \layout Standard
6821
6822 \backslash
6823 /
6824 \end_inset
6825
6826 -verbose
6827 \begin_inset LatexCommand \index{-\/-verbose}
6828
6829 \end_inset
6830
6831
6832 \series default
6833  Shows the various actions the compiler is performing.
6834 \layout List
6835 \labelwidthstring 00.00.0000
6836
6837
6838 \series bold
6839 -V
6840 \begin_inset LatexCommand \index{-V}
6841
6842 \end_inset
6843
6844
6845 \series default
6846  Shows the actual commands the compiler is executing.
6847 \layout List
6848 \labelwidthstring 00.00.0000
6849
6850
6851 \series bold
6852 -
6853 \begin_inset ERT
6854 status Collapsed
6855
6856 \layout Standard
6857
6858 \backslash
6859 /
6860 \end_inset
6861
6862 -no-c-code-in-asm
6863 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
6864
6865 \end_inset
6866
6867
6868 \series default
6869  Hides your ugly and inefficient c-code from the asm file, so you can always
6870  blame the compiler :).
6871 \layout List
6872 \labelwidthstring 00.00.0000
6873
6874
6875 \series bold
6876 -
6877 \begin_inset ERT
6878 status Collapsed
6879
6880 \layout Standard
6881
6882 \backslash
6883 /
6884 \end_inset
6885
6886 -i-code-in-asm
6887 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
6888
6889 \end_inset
6890
6891
6892 \series default
6893  Include i-codes in the asm file.
6894  Sounds like noise but is most helpful for debugging the compiler itself.
6895 \layout List
6896 \labelwidthstring 00.00.0000
6897
6898
6899 \series bold
6900 -
6901 \begin_inset ERT
6902 status Collapsed
6903
6904 \layout Standard
6905
6906 \backslash
6907 /
6908 \end_inset
6909
6910 -less-pedantic
6911 \begin_inset LatexCommand \index{-\/-less-pedantic}
6912
6913 \end_inset
6914
6915
6916 \series default
6917  Disable some of the more pedantic warnings
6918 \begin_inset LatexCommand \index{Warnings}
6919
6920 \end_inset
6921
6922  (jwk burps: please be more specific here, please!).
6923  If you want rather more than less warnings you should consider using a
6924  separate tool dedicated to syntax checking like splint
6925 \begin_inset LatexCommand \url{www.splint.org}
6926
6927 \end_inset
6928
6929 .
6930 \layout List
6931 \labelwidthstring 00.00.0000
6932
6933
6934 \series bold
6935 -
6936 \begin_inset ERT
6937 status Collapsed
6938
6939 \layout Standard
6940
6941 \backslash
6942 /
6943 \end_inset
6944
6945 -print-search-dirs
6946 \begin_inset LatexCommand \index{-\/-print-search-dirs}
6947
6948 \end_inset
6949
6950
6951 \series default
6952  Display the directories in the compiler's search path
6953 \layout List
6954 \labelwidthstring 00.00.0000
6955
6956
6957 \series bold
6958 -
6959 \begin_inset ERT
6960 status Collapsed
6961
6962 \layout Standard
6963
6964 \backslash
6965 /
6966 \end_inset
6967
6968 -vc
6969 \begin_inset LatexCommand \index{-\/-vc}
6970
6971 \end_inset
6972
6973
6974 \series default
6975  Display errors and warnings using MSVC style, so you can use SDCC with
6976  visual studio.
6977 \layout List
6978 \labelwidthstring 00.00.0000
6979
6980
6981 \series bold
6982 -
6983 \begin_inset ERT
6984 status Collapsed
6985
6986 \layout Standard
6987
6988 \backslash
6989 /
6990 \end_inset
6991
6992 -use-stdout
6993 \begin_inset LatexCommand \index{-\/-use-stdout}
6994
6995 \end_inset
6996
6997
6998 \series default
6999  Send errors and warnings to stdout instead of stderr.
7000 \layout List
7001 \labelwidthstring 00.00.0000
7002
7003
7004 \series bold
7005 -Wa\SpecialChar ~
7006 asmOption[,asmOption]
7007 \series default
7008
7009 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7010
7011 \end_inset
7012
7013 ...
7014  Pass the asmOption to the assembler
7015 \begin_inset LatexCommand \index{Options assembler}
7016
7017 \end_inset
7018
7019
7020 \begin_inset LatexCommand \index{Assembler options}
7021
7022 \end_inset
7023
7024 .
7025  See file sdcc/as/doc/asxhtm.html for assembler options.
7026 \layout Subsection
7027
7028 Intermediate Dump Options
7029 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7030
7031 \end_inset
7032
7033
7034 \begin_inset LatexCommand \index{Options intermediate dump}
7035
7036 \end_inset
7037
7038
7039 \begin_inset LatexCommand \index{Intermediate dump options}
7040
7041 \end_inset
7042
7043
7044 \layout Standard
7045
7046 The following options are provided for the purpose of retargetting and debugging
7047  the compiler.
7048  These provided a means to dump the intermediate code (iCode
7049 \begin_inset LatexCommand \index{iCode}
7050
7051 \end_inset
7052
7053 ) generated by the compiler in human readable form at various stages of
7054  the compilation process.
7055  More on iCodes see chapter
7056 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7057
7058 \end_inset
7059
7060
7061 \begin_inset Quotes srd
7062 \end_inset
7063
7064 The anatomy of the compiler
7065 \begin_inset Quotes srd
7066 \end_inset
7067
7068 .
7069 \layout List
7070 \labelwidthstring 00.00.0000
7071
7072
7073 \series bold
7074 -
7075 \begin_inset ERT
7076 status Collapsed
7077
7078 \layout Standard
7079
7080 \backslash
7081 /
7082 \end_inset
7083
7084 -dumpraw
7085 \begin_inset LatexCommand \index{-\/-dumpraw}
7086
7087 \end_inset
7088
7089
7090 \series default
7091  This option will cause the compiler to dump the intermediate code into
7092  a file of named
7093 \emph on
7094 <source filename>.dumpraw
7095 \emph default
7096  just after the intermediate code has been generated for a function, i.e.
7097  before any optimizations are done.
7098  The basic blocks
7099 \begin_inset LatexCommand \index{Basic blocks}
7100
7101 \end_inset
7102
7103  at this stage ordered in the depth first number, so they may not be in
7104  sequence of execution.
7105 \layout List
7106 \labelwidthstring 00.00.0000
7107
7108
7109 \series bold
7110 -
7111 \begin_inset ERT
7112 status Collapsed
7113
7114 \layout Standard
7115
7116 \backslash
7117 /
7118 \end_inset
7119
7120 -dumpgcse
7121 \begin_inset LatexCommand \index{-\/-dumpgcse}
7122
7123 \end_inset
7124
7125
7126 \series default
7127  Will create a dump of iCode's, after global subexpression elimination
7128 \begin_inset LatexCommand \index{Global subexpression elimination}
7129
7130 \end_inset
7131
7132 , into a file named
7133 \emph on
7134 <source filename>.dumpgcse.
7135 \layout List
7136 \labelwidthstring 00.00.0000
7137
7138
7139 \series bold
7140 -
7141 \begin_inset ERT
7142 status Collapsed
7143
7144 \layout Standard
7145
7146 \backslash
7147 /
7148 \end_inset
7149
7150 -dumpdeadcode
7151 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
7152
7153 \end_inset
7154
7155
7156 \series default
7157  Will create a dump of iCode's, after deadcode elimination
7158 \begin_inset LatexCommand \index{Dead-code elimination}
7159
7160 \end_inset
7161
7162 , into a file named
7163 \emph on
7164 <source filename>.dumpdeadcode.
7165 \layout List
7166 \labelwidthstring 00.00.0000
7167
7168
7169 \series bold
7170 -
7171 \begin_inset ERT
7172 status Collapsed
7173
7174 \layout Standard
7175
7176 \backslash
7177 /
7178 \end_inset
7179
7180 -dumploop
7181 \begin_inset LatexCommand \index{-\/-dumploop}
7182
7183 \end_inset
7184
7185
7186 \series default
7187 \size large
7188
7189 \size default
7190 Will create a dump of iCode's, after loop optimizations
7191 \begin_inset LatexCommand \index{Loop optimization}
7192
7193 \end_inset
7194
7195 , into a file named
7196 \emph on
7197 <source filename>.dumploop.
7198 \layout List
7199 \labelwidthstring 00.00.0000
7200
7201
7202 \series bold
7203 -
7204 \begin_inset ERT
7205 status Collapsed
7206
7207 \layout Standard
7208
7209 \backslash
7210 /
7211 \end_inset
7212
7213 -dumprange
7214 \begin_inset LatexCommand \index{-\/-dumprange}
7215
7216 \end_inset
7217
7218
7219 \series default
7220 \size large
7221
7222 \size default
7223 Will create a dump of iCode's, after live range analysis
7224 \begin_inset LatexCommand \index{Live range analysis}
7225
7226 \end_inset
7227
7228 , into a file named
7229 \emph on
7230 <source filename>.dumprange.
7231 \layout List
7232 \labelwidthstring 00.00.0000
7233
7234
7235 \series bold
7236 -
7237 \begin_inset ERT
7238 status Collapsed
7239
7240 \layout Standard
7241
7242 \backslash
7243 /
7244 \end_inset
7245
7246 -dumlrange
7247 \begin_inset LatexCommand \index{-\/-dumlrange}
7248
7249 \end_inset
7250
7251
7252 \series default
7253  Will dump the life ranges
7254 \begin_inset LatexCommand \index{Live range analysis}
7255
7256 \end_inset
7257
7258  for all symbols.
7259 \layout List
7260 \labelwidthstring 00.00.0000
7261
7262
7263 \series bold
7264 -
7265 \begin_inset ERT
7266 status Collapsed
7267
7268 \layout Standard
7269
7270 \backslash
7271 /
7272 \end_inset
7273
7274 -dumpregassign
7275 \begin_inset LatexCommand \index{-\/-dumpregassign}
7276
7277 \end_inset
7278
7279
7280 \bar under
7281
7282 \series default
7283 \bar default
7284 Will create a dump of iCode's, after register assignment
7285 \begin_inset LatexCommand \index{Register assignment}
7286
7287 \end_inset
7288
7289 , into a file named
7290 \emph on
7291 <source filename>.dumprassgn.
7292 \layout List
7293 \labelwidthstring 00.00.0000
7294
7295
7296 \series bold
7297 -
7298 \begin_inset ERT
7299 status Collapsed
7300
7301 \layout Standard
7302
7303 \backslash
7304 /
7305 \end_inset
7306
7307 -dumplrange
7308 \begin_inset LatexCommand \index{-\/-dumplrange}
7309
7310 \end_inset
7311
7312
7313 \series default
7314  Will create a dump of the live ranges of iTemp's
7315 \layout List
7316 \labelwidthstring 00.00.0000
7317
7318
7319 \series bold
7320 -
7321 \begin_inset ERT
7322 status Collapsed
7323
7324 \layout Standard
7325
7326 \backslash
7327 /
7328 \end_inset
7329
7330 -dumpall
7331 \begin_inset LatexCommand \index{-\/-dumpall}
7332
7333 \end_inset
7334
7335
7336 \size large
7337 \bar under
7338
7339 \series default
7340 \size default
7341 \bar default
7342 Will cause all the above mentioned dumps to be created.
7343 \layout Subsection
7344
7345 Redirecting output on Windows Shells
7346 \layout Standard
7347
7348 By default SDCC writes it's error messages to
7349 \begin_inset Quotes sld
7350 \end_inset
7351
7352 standard error
7353 \begin_inset Quotes srd
7354 \end_inset
7355
7356 .
7357  To force all messages to
7358 \begin_inset Quotes sld
7359 \end_inset
7360
7361 standard output
7362 \begin_inset Quotes srd
7363 \end_inset
7364
7365  use
7366 \series bold
7367 -
7368 \series default
7369 \emph on
7370
7371 \begin_inset ERT
7372 status Collapsed
7373
7374 \layout Standard
7375
7376 \backslash
7377 /
7378 \end_inset
7379
7380
7381 \series bold
7382 \emph default
7383 -
7384 \series default
7385 use-stdout
7386 \begin_inset LatexCommand \index{-\/-use-stdout}
7387
7388 \end_inset
7389
7390 .
7391  Additionally, if you happen to have visual studio installed in your windows
7392  machine, you can use it to compile your sources using a custom build and
7393  the SDCC -
7394 \emph on
7395
7396 \begin_inset ERT
7397 status Collapsed
7398
7399 \layout Standard
7400
7401 \backslash
7402 /
7403 \end_inset
7404
7405
7406 \emph default
7407 -vc
7408 \begin_inset LatexCommand \index{-\/-vc}
7409
7410 \end_inset
7411
7412  option.
7413  Something like this should work:
7414 \newline
7415
7416 \newline
7417
7418 \series bold
7419 c:
7420 \backslash
7421 sdcc
7422 \backslash
7423 bin
7424 \backslash
7425 sdcc.exe -
7426 \series default
7427 \emph on
7428
7429 \begin_inset ERT
7430 status Collapsed
7431
7432 \layout Standard
7433
7434 \backslash
7435 /
7436 \end_inset
7437
7438
7439 \series bold
7440 \emph default
7441 -vc -
7442 \series default
7443 \emph on
7444
7445 \begin_inset ERT
7446 status Collapsed
7447
7448 \layout Standard
7449
7450 \backslash
7451 /
7452 \end_inset
7453
7454
7455 \series bold
7456 \emph default
7457 -model-large -c $(InputPath)
7458 \layout Section
7459
7460 Environment variables
7461 \begin_inset LatexCommand \index{Environment variables}
7462
7463 \end_inset
7464
7465
7466 \layout Standard
7467
7468 SDCC recognizes the following environment variables:
7469 \layout List
7470 \labelwidthstring 00.00.0000
7471
7472
7473 \series bold
7474 SDCC_LEAVE_SIGNALS
7475 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7476
7477 \end_inset
7478
7479
7480 \series default
7481  SDCC installs a signal handler
7482 \begin_inset LatexCommand \index{signal handler}
7483
7484 \end_inset
7485
7486  to be able to delete temporary files after an user break (^C) or an exception.
7487  If this environment variable is set, SDCC won't install the signal handler
7488  in order to be able to debug SDCC.
7489 \layout List
7490 \labelwidthstring 00.00.0000
7491
7492
7493 \series bold
7494 TMP,\SpecialChar ~
7495 TEMP,\SpecialChar ~
7496 TMPDIR
7497 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7498
7499 \end_inset
7500
7501
7502 \series default
7503  Path, where temporary files will be created.
7504  The order of the variables is the search order.
7505  In a standard *nix environment these variables are not set, and there's
7506  no need to set them.
7507  On Windows it's recommended to set one of them.
7508 \layout List
7509 \labelwidthstring 00.00.0000
7510
7511
7512 \series bold
7513 SDCC_HOME
7514 \begin_inset LatexCommand \index{SDCC\_HOME}
7515
7516 \end_inset
7517
7518
7519 \series default
7520  Path, see section
7521 \begin_inset LatexCommand \ref{sub:Install-paths}
7522
7523 \end_inset
7524
7525 \SpecialChar ~
7526
7527 \begin_inset Quotes sld
7528 \end_inset
7529
7530  Install Paths
7531 \begin_inset Quotes srd
7532 \end_inset
7533
7534 .
7535 \layout List
7536 \labelwidthstring 00.00.0000
7537
7538
7539 \series bold
7540 SDCC_INCLUDE
7541 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
7542
7543 \end_inset
7544
7545
7546 \series default
7547  Path, see section
7548 \begin_inset LatexCommand \ref{sub:Search-Paths}
7549
7550 \end_inset
7551
7552 \SpecialChar ~
7553
7554 \begin_inset Quotes sld
7555 \end_inset
7556
7557 Search Paths
7558 \begin_inset Quotes srd
7559 \end_inset
7560
7561 .
7562 \layout List
7563 \labelwidthstring 00.00.0000
7564
7565
7566 \series bold
7567 SDCC_LIB
7568 \begin_inset LatexCommand \index{SDCC\_LIB}
7569
7570 \end_inset
7571
7572
7573 \series default
7574  Path, see section
7575 \begin_inset LatexCommand \ref{sub:Search-Paths}
7576
7577 \end_inset
7578
7579 \SpecialChar ~
7580
7581 \begin_inset Quotes sld
7582 \end_inset
7583
7584 Search Paths
7585 \begin_inset Quotes srd
7586 \end_inset
7587
7588 ..
7589 \layout Standard
7590
7591 There are some more environment variables recognized by SDCC, but these
7592  are solely used for debugging purposes.
7593  They can change or disappear very quickly, and will never be documented.
7594 \layout Section
7595
7596 Storage Class Language Extensions
7597 \layout Subsection
7598
7599 MCS51/DS390 Storage Class
7600 \begin_inset LatexCommand \index{Storage class}
7601
7602 \end_inset
7603
7604  Language Extensions
7605 \layout Standard
7606
7607 In addition to the ANSI storage classes SDCC allows the following MCS51
7608  specific storage classes:
7609 \layout Subsubsection
7610
7611 data
7612 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
7613
7614 \end_inset
7615
7616  / near
7617 \begin_inset LatexCommand \index{near (storage class)}
7618
7619 \end_inset
7620
7621
7622 \layout Standard
7623
7624 This is the
7625 \series bold
7626 default
7627 \series default
7628  storage class for the Small Memory model (
7629 \emph on
7630 data
7631 \emph default
7632  and
7633 \emph on
7634 near
7635 \emph default
7636  can be used synonymously).
7637  Variables declared with this storage class will be allocated in the directly
7638  addressable portion of the internal RAM of a 8051, e.g.:
7639 \layout Verse
7640
7641
7642 \family typewriter
7643 data unsigned char test_data;
7644 \layout Standard
7645
7646 Writing 0x01 to this variable generates the assembly code:
7647 \layout Verse
7648
7649
7650 \family typewriter
7651 75*00 01\SpecialChar ~
7652 \SpecialChar ~
7653 \SpecialChar ~
7654 mov\SpecialChar ~
7655 \SpecialChar ~
7656 _test_data,#0x01
7657 \layout Subsubsection
7658
7659 xdata
7660 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
7661
7662 \end_inset
7663
7664  / far
7665 \begin_inset LatexCommand \index{far (storage class)}
7666
7667 \end_inset
7668
7669
7670 \layout Standard
7671
7672 Variables declared with this storage class will be placed in the external
7673  RAM.
7674  This is the
7675 \series bold
7676 default
7677 \series default
7678  storage class for the Large Memory model, e.g.:
7679 \layout Verse
7680
7681
7682 \family typewriter
7683 xdata unsigned char test_xdata;
7684 \layout Standard
7685
7686 Writing 0x01 to this variable generates the assembly code:
7687 \layout Verse
7688
7689
7690 \family typewriter
7691 90s00r00\SpecialChar ~
7692 \SpecialChar ~
7693 \SpecialChar ~
7694 mov\SpecialChar ~
7695 \SpecialChar ~
7696 dptr,#_test_xdata
7697 \newline
7698 74\SpecialChar ~
7699 01\SpecialChar ~
7700 \SpecialChar ~
7701 \SpecialChar ~
7702 \SpecialChar ~
7703 \SpecialChar ~
7704 \SpecialChar ~
7705 mov\SpecialChar ~
7706 \SpecialChar ~
7707 a,#0x01
7708 \newline
7709 F0\SpecialChar ~
7710 \SpecialChar ~
7711 \SpecialChar ~
7712 \SpecialChar ~
7713 \SpecialChar ~
7714 \SpecialChar ~
7715 \SpecialChar ~
7716 \SpecialChar ~
7717 \SpecialChar ~
7718 movx\SpecialChar ~
7719 @dptr,a
7720 \layout Subsubsection
7721
7722 idata
7723 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
7724
7725 \end_inset
7726
7727
7728 \layout Standard
7729
7730 Variables declared with this storage class will be allocated into the indirectly
7731  addressable portion of the internal ram of a 8051, e.g.:
7732 \layout Verse
7733
7734
7735 \family typewriter
7736 idata unsigned char test_idata;
7737 \layout Standard
7738
7739 Writing 0x01 to this variable generates the assembly code:
7740 \layout Verse
7741
7742
7743 \family typewriter
7744 78r00\SpecialChar ~
7745 \SpecialChar ~
7746 \SpecialChar ~
7747 \SpecialChar ~
7748 \SpecialChar ~
7749 \SpecialChar ~
7750 \SpecialChar ~
7751 mov\SpecialChar ~
7752 \SpecialChar ~
7753 r0,#_test_idata
7754 \newline
7755 76\SpecialChar ~
7756 01\SpecialChar ~
7757 \SpecialChar ~
7758 \SpecialChar ~
7759 \SpecialChar ~
7760 \SpecialChar ~
7761 \SpecialChar ~
7762 \SpecialChar ~
7763 mov\SpecialChar ~
7764 \SpecialChar ~
7765 @r0,#0x01
7766 \layout Standard
7767
7768 Please note, the first 128 byte of idata physically access the same RAM
7769  as the data memory.
7770  The original 8051 had 128 byte idata memory, nowadays most devices have
7771  256 byte idata memory.
7772  The stack
7773 \begin_inset LatexCommand \index{stack}
7774
7775 \end_inset
7776
7777  is located in idata memory.
7778 \layout Subsubsection
7779
7780 pdata
7781 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
7782
7783 \end_inset
7784
7785
7786 \layout Standard
7787
7788 Paged xdata access is currently not as straightforward as using the other
7789  addressing modes of a 8051.
7790  The following example writes 0x01 to the address pointed to.
7791  Please note, pdata access physically accesses xdata memory.
7792  The high byte of the address is determined by port P2
7793 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
7794
7795 \end_inset
7796
7797 (or in case of some 8051 variants by a separate Special Function Register,
7798  see section
7799 \begin_inset LatexCommand \ref{sub:MCS51-variants}
7800
7801 \end_inset
7802
7803 ).
7804 \layout Verse
7805
7806
7807 \family typewriter
7808 pdata unsigned char *test_pdata_ptr;
7809 \newline
7810
7811 \newline
7812 void main()
7813 \newline
7814 {
7815 \newline
7816 \SpecialChar ~
7817 \SpecialChar ~
7818 \SpecialChar ~
7819 \SpecialChar ~
7820 test_pdata_ptr = (pdata *)0xfe;
7821 \newline
7822 \SpecialChar ~
7823 \SpecialChar ~
7824 \SpecialChar ~
7825 \SpecialChar ~
7826 *test_pdata_ptr = 1;
7827 \newline
7828 }
7829 \layout Standard
7830
7831 Generates the assembly code:
7832 \layout Verse
7833
7834
7835 \family typewriter
7836 75*01 FE\SpecialChar ~
7837 \SpecialChar ~
7838 \SpecialChar ~
7839 mov\SpecialChar ~
7840  _test_pdata_ptr,#0xFE
7841 \newline
7842 78 FE\SpecialChar ~
7843 \SpecialChar ~
7844 \SpecialChar ~
7845 \SpecialChar ~
7846 \SpecialChar ~
7847 \SpecialChar ~
7848 mov\SpecialChar ~
7849  r0,#0xFE
7850 \newline
7851 74 01\SpecialChar ~
7852 \SpecialChar ~
7853 \SpecialChar ~
7854 \SpecialChar ~
7855 \SpecialChar ~
7856 \SpecialChar ~
7857 mov\SpecialChar ~
7858  a,#0x01
7859 \newline
7860 F2\SpecialChar ~
7861 \SpecialChar ~
7862 \SpecialChar ~
7863 \SpecialChar ~
7864 \SpecialChar ~
7865 \SpecialChar ~
7866 \SpecialChar ~
7867 \SpecialChar ~
7868 \SpecialChar ~
7869 movx @r0,a
7870 \layout Standard
7871
7872 Be extremely carefull if you use pdata together with the -
7873 \begin_inset ERT
7874 status Collapsed
7875
7876 \layout Standard
7877
7878 \backslash
7879 /
7880 \end_inset
7881
7882 -xstack
7883 \begin_inset LatexCommand \index{-\/-xstack}
7884
7885 \end_inset
7886
7887  option.
7888 \layout Subsubsection
7889
7890 code
7891 \begin_inset LatexCommand \index{code}
7892
7893 \end_inset
7894
7895
7896 \layout Standard
7897
7898 'Variables' declared with this storage class will be placed in the code
7899  memory:
7900 \layout Verse
7901
7902
7903 \family typewriter
7904 code unsigned char test_code;
7905 \layout Standard
7906
7907 Read access to this variable generates the assembly code:
7908 \layout Verse
7909
7910
7911 \family typewriter
7912 90s00r6F\SpecialChar ~
7913 \SpecialChar ~
7914 \SpecialChar ~
7915 mov dptr,#_test_code
7916 \newline
7917 E4\SpecialChar ~
7918 \SpecialChar ~
7919 \SpecialChar ~
7920 \SpecialChar ~
7921 \SpecialChar ~
7922 \SpecialChar ~
7923 \SpecialChar ~
7924 \SpecialChar ~
7925 \SpecialChar ~
7926 clr a
7927 \newline
7928 93\SpecialChar ~
7929 \SpecialChar ~
7930 \SpecialChar ~
7931 \SpecialChar ~
7932 \SpecialChar ~
7933 \SpecialChar ~
7934 \SpecialChar ~
7935 \SpecialChar ~
7936 \SpecialChar ~
7937 movc a,@a+dptr
7938 \layout Standard
7939
7940
7941 \family typewriter
7942 char
7943 \family default
7944  indexed arrays of characters in code memory can be accessed efficiently:
7945 \layout Verse
7946
7947
7948 \family typewriter
7949 code char test_array[] = {'c','h','e','a','p'};
7950 \layout Standard
7951
7952 Read access to this array using an 8-bit unsigned index generates the assembly
7953  code:
7954 \layout Verse
7955
7956
7957 \family typewriter
7958 E5*00\SpecialChar ~
7959 \SpecialChar ~
7960 \SpecialChar ~
7961 \SpecialChar ~
7962 \SpecialChar ~
7963 \SpecialChar ~
7964 mov a,_index
7965 \layout Verse
7966
7967
7968 \family typewriter
7969 90s00r41\SpecialChar ~
7970 \SpecialChar ~
7971 \SpecialChar ~
7972 mov dptr,#_test_array
7973 \layout Verse
7974
7975
7976 \family typewriter
7977 93\SpecialChar ~
7978 \SpecialChar ~
7979 \SpecialChar ~
7980 \SpecialChar ~
7981 \SpecialChar ~
7982 \SpecialChar ~
7983 \SpecialChar ~
7984 \SpecialChar ~
7985 \SpecialChar ~
7986 movc a,@a+dptr
7987 \layout Subsubsection
7988
7989 bit
7990 \begin_inset LatexCommand \index{bit}
7991
7992 \end_inset
7993
7994
7995 \layout Standard
7996
7997 This is a data-type and a storage class specifier.
7998  When a variable is declared as a bit, it is allocated into the bit addressable
7999  memory of 8051, e.g.:
8000 \layout Verse
8001
8002
8003 \family typewriter
8004 bit test_bit;
8005 \layout Standard
8006
8007 Writing 1 to this variable generates the assembly code:
8008 \layout Verse
8009
8010
8011 \family typewriter
8012 D2*00\SpecialChar ~
8013 \SpecialChar ~
8014 \SpecialChar ~
8015 \SpecialChar ~
8016 \SpecialChar ~
8017 \SpecialChar ~
8018 \SpecialChar ~
8019 setb\SpecialChar ~
8020 _test_bit
8021 \layout Standard
8022
8023 The bit addressable memory consists of 128 bits which are located from 0x20
8024  to 0x2f in data memory.
8025
8026 \layout Standard
8027
8028 Apart from this 8051 specific storage class most architectures support ANSI-C
8029  bitfields
8030 \begin_inset LatexCommand \index{bitfields}
8031
8032 \end_inset
8033
8034
8035 \begin_inset Foot
8036 collapsed false
8037
8038 \layout Standard
8039
8040 Not really meant as examples, but nevertheless showing what bitfields are
8041  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8042 \end_inset
8043
8044 .
8045 \layout Subsubsection
8046
8047 sfr
8048 \begin_inset LatexCommand \index{sfr}
8049
8050 \end_inset
8051
8052  / sbit
8053 \begin_inset LatexCommand \index{sbit}
8054
8055 \end_inset
8056
8057
8058 \layout Standard
8059
8060 Like the bit keyword,
8061 \emph on
8062 sfr / sbit
8063 \emph default
8064 signifies both a data-type and storage class, they are used to describe
8065  the
8066 \emph on
8067 s
8068 \emph default
8069 pecial
8070 \emph on
8071 f
8072 \emph default
8073 unction
8074 \emph on
8075 r
8076 \emph default
8077 egisters and
8078 \emph on
8079 s
8080 \emph default
8081 pecial
8082 \emph on
8083 bit
8084 \emph default
8085  variables of a 8051, eg:
8086 \layout Verse
8087
8088
8089 \family typewriter
8090 sfr at
8091 \begin_inset LatexCommand \index{at}
8092
8093 \end_inset
8094
8095  0x80 P0;\SpecialChar ~
8096  /* special function register P0 at location 0x80 */
8097 \newline
8098 sbit at 0xd7 CY; /* CY (Carry Flag
8099 \begin_inset LatexCommand \index{Flags}
8100
8101 \end_inset
8102
8103
8104 \begin_inset LatexCommand \index{Carry flag}
8105
8106 \end_inset
8107
8108 ) */
8109 \layout Standard
8110
8111 Special function registers which are located on an address dividable by
8112  8 are bit-addressable, an
8113 \emph on
8114  sbit
8115 \emph default
8116  addresses a specific bit within these sfr.
8117 \layout Subsubsection
8118
8119 Pointers
8120 \begin_inset LatexCommand \index{Pointer}
8121
8122 \end_inset
8123
8124  to MCS51/DS390 specific memory spaces
8125 \layout Standard
8126
8127 SDCC allows (via language extensions) pointers to explicitly point to any
8128  of the memory spaces
8129 \begin_inset LatexCommand \index{Memory model}
8130
8131 \end_inset
8132
8133  of the 8051.
8134  In addition to the explicit pointers, the compiler uses (by default) generic
8135  pointers which can be used to point to any of the memory spaces.
8136 \newline
8137
8138 \newline
8139 Pointer declaration examples:
8140 \layout Verse
8141
8142
8143 \family typewriter
8144 /* pointer physically in internal ram pointing to object in external ram
8145  */
8146 \newline
8147 xdata unsigned char * data p;
8148 \newline
8149
8150 \newline
8151 /* pointer physically in external ram pointing to object in internal ram
8152  */
8153 \newline
8154 data unsigned char * xdata p;
8155 \newline
8156
8157 \newline
8158 /* pointer physically in code rom pointing to data in xdata space */
8159 \newline
8160 xdata unsigned char * code p;
8161 \newline
8162
8163 \newline
8164 /* pointer physically in code space pointing to data in code space */
8165 \newline
8166 code unsigned char * code p;
8167 \newline
8168
8169 \newline
8170 /* the following is a generic pointer physically located in xdata space
8171  */
8172 \newline
8173 char * xdata p;
8174 \layout Standard
8175
8176 Well you get the idea.
8177
8178 \newline
8179
8180 \newline
8181 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
8182 \emph on
8183 generic
8184 \emph default
8185  pointers.
8186
8187 \size small
8188
8189 \newline
8190
8191 \newline
8192
8193 \size default
8194 The highest order byte of the
8195 \emph on
8196 generic
8197 \emph default
8198  pointers contains the data space information.
8199  Assembler support routines are called whenever data is stored or retrieved
8200  using
8201 \emph on
8202 generic
8203 \emph default
8204  pointers.
8205  These are useful for developing reusable library
8206 \begin_inset LatexCommand \index{Libraries}
8207
8208 \end_inset
8209
8210  routines.
8211  Explicitly specifying the pointer type will generate the most efficient
8212  code.
8213 \layout Subsubsection
8214
8215 Notes on MCS51 memory
8216 \begin_inset LatexCommand \index{MCS51 memory}
8217
8218 \end_inset
8219
8220  layout
8221 \layout Standard
8222
8223 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
8224  RAM memory which is structured as follows:
8225 \newline
8226
8227 \newline
8228 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
8229
8230 \newline
8231 - Bytes 20-2F - 16 bytes to hold 128 bit
8232 \begin_inset LatexCommand \index{bit}
8233
8234 \end_inset
8235
8236  variables and,
8237 \newline
8238 - Bytes 30-7F - 80 bytes for general purpose use.
8239 \newline
8240
8241 \layout Standard
8242
8243 Additionally some members of the MCS51 family may have up to 128 bytes of
8244  additional, indirectly addressable, internal RAM memory (
8245 \emph on
8246 idata
8247 \emph default
8248
8249 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8250
8251 \end_inset
8252
8253 ).
8254  Furthermore, some chips may have some built in external memory (
8255 \emph on
8256 xdata
8257 \emph default
8258
8259 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8260
8261 \end_inset
8262
8263 ) which should not be confused with the internal, directly addressable RAM
8264  memory (
8265 \emph on
8266 data
8267 \emph default
8268
8269 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8270
8271 \end_inset
8272
8273 ).
8274  Sometimes this built in
8275 \emph on
8276 xdata
8277 \emph default
8278  memory has to be activated before using it (you can probably find this
8279  information on the datasheet of the microcontroller your are using, see
8280  also section
8281 \begin_inset LatexCommand \ref{sub:Startup-Code}
8282
8283 \end_inset
8284
8285 \SpecialChar ~
8286 Startup-Code).
8287 \layout Standard
8288
8289 Normally SDCC will only use the first bank
8290 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
8291
8292 \end_inset
8293
8294  of registers (register bank 0), but it is possible to specify that other
8295  banks of registers should be used in interrupt
8296 \begin_inset LatexCommand \index{interrupt}
8297
8298 \end_inset
8299
8300  routines.
8301  By default, the compiler will place the stack after the last byte of allocated
8302  memory for variables.
8303  For example, if the first 2 banks of registers are used, and only four
8304  bytes are used for
8305 \emph on
8306 data
8307 \emph default
8308  variables, it will position the base of the internal stack at address 20
8309  (0x14).
8310  This implies that as the stack
8311 \begin_inset LatexCommand \index{stack}
8312
8313 \end_inset
8314
8315  grows, it will use up the remaining register banks, and the 16 bytes used
8316  by the 128 bit variables, and 80 bytes for general purpose use.
8317  If any bit variables are used, the data variables will be placed after
8318  the byte holding the last bit variable.
8319  For example, if register banks 0 and 1 are used, and there are 9 bit variables
8320  (two bytes used),
8321 \emph on
8322 data
8323 \emph default
8324  variables will be placed starting at address 0x22.
8325  You can also use -
8326 \begin_inset ERT
8327 status Collapsed
8328
8329 \layout Standard
8330
8331 \backslash
8332 /
8333 \end_inset
8334
8335 -data-loc
8336 \begin_inset LatexCommand \index{-\/-data-loc<Value>}
8337
8338 \end_inset
8339
8340  to specify the start address of the
8341 \emph on
8342 data
8343 \emph default
8344  and -
8345 \begin_inset ERT
8346 status Collapsed
8347
8348 \layout Standard
8349
8350 \backslash
8351 /
8352 \end_inset
8353
8354 -iram-size to specify the size of the total internal RAM (
8355 \emph on
8356 data
8357 \emph default
8358 +
8359 \emph on
8360 idata
8361 \emph default
8362 ).
8363
8364 \layout Standard
8365
8366 By default the 8051 linker will place the stack after the last byte of data
8367  variables.
8368  Option -
8369 \begin_inset ERT
8370 status Collapsed
8371
8372 \layout Standard
8373
8374 \backslash
8375 /
8376 \end_inset
8377
8378 -stack-loc
8379 \begin_inset LatexCommand \index{-\/-stack-loc<Value>}
8380
8381 \end_inset
8382
8383  allows you to specify the start of the stack, i.e.
8384  you could start it after any data in the general purpose area.
8385  If your microcontroller has additional indirectly addressable internal
8386  RAM (
8387 \emph on
8388 idata
8389 \emph default
8390 ) you can place the stack on it.
8391  You may also need to use -
8392 \begin_inset ERT
8393 status Collapsed
8394
8395 \layout Standard
8396
8397 \backslash
8398 /
8399 \end_inset
8400
8401 -xdata-loc
8402 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
8403
8404 \end_inset
8405
8406  to set the start address of the external RAM (
8407 \emph on
8408 xdata
8409 \emph default
8410 ) and -
8411 \begin_inset ERT
8412 status Collapsed
8413
8414 \layout Standard
8415
8416 \backslash
8417 /
8418 \end_inset
8419
8420 -xram-size
8421 \begin_inset LatexCommand \index{-\/-data-loc}
8422
8423 \end_inset
8424
8425  to specify its size.
8426  Same goes for the code memory, using -
8427 \begin_inset ERT
8428 status Collapsed
8429
8430 \layout Standard
8431
8432 \backslash
8433 /
8434 \end_inset
8435
8436 -code-loc
8437 \begin_inset LatexCommand \index{-\/-data-loc}
8438
8439 \end_inset
8440
8441  and -
8442 \begin_inset ERT
8443 status Collapsed
8444
8445 \layout Standard
8446
8447 \backslash
8448 /
8449 \end_inset
8450
8451 -code-size
8452 \begin_inset LatexCommand \index{-\/-data-loc}
8453
8454 \end_inset
8455
8456 .
8457  If in doubt, don't specify any options and see if the resulting memory
8458  layout is appropriate, then you can adjust it.
8459 \layout Standard
8460
8461 The linker generates two files with memory allocation information.
8462  The first, with extension .map
8463 \begin_inset LatexCommand \index{<file>.map}
8464
8465 \end_inset
8466
8467  shows all the variables and segments.
8468  The second with extension .mem
8469 \begin_inset LatexCommand \index{<file>.mem}
8470
8471 \end_inset
8472
8473  shows the final memory layout.
8474  The linker will complain either if memory segments overlap, there is not
8475  enough memory, or there is not enough space for stack.
8476  If you get any linking warnings and/or errors related to stack or segments
8477  allocation, take a look at either the .map or .mem files to find out what
8478  the problem is.
8479  The .mem file may even suggest a solution to the problem.
8480 \layout Subsection
8481
8482 Z80/Z180 Storage Class
8483 \begin_inset LatexCommand \index{Storage class}
8484
8485 \end_inset
8486
8487  Language Extensions
8488 \layout Subsubsection
8489
8490 sfr
8491 \begin_inset LatexCommand \index{sfr}
8492
8493 \end_inset
8494
8495  (in/out to 8-bit addresses)
8496 \layout Standard
8497
8498 The Z80
8499 \begin_inset LatexCommand \index{Z80}
8500
8501 \end_inset
8502
8503  family has separate address spaces for memory and
8504 \emph on
8505 i
8506 \emph default
8507 nput/
8508 \emph on
8509 o
8510 \emph default
8511 utput memory.
8512  I/O memory
8513 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
8514
8515 \end_inset
8516
8517  is accessed with special instructions, e.g.:
8518 \layout Verse
8519
8520
8521 \family typewriter
8522 sfr at 0x78 IoPort;\SpecialChar ~
8523 \SpecialChar ~
8524 /* define a var in I/O space at 78h called IoPort */
8525
8526 \layout Standard
8527
8528 Writing 0x01 to this variable generates the assembly code:
8529 \layout Verse
8530
8531
8532 \family typewriter
8533 3E 01\SpecialChar ~
8534 \SpecialChar ~
8535 \SpecialChar ~
8536 \SpecialChar ~
8537 \SpecialChar ~
8538 \SpecialChar ~
8539 ld a,#0x01
8540 \newline
8541 D3 78\SpecialChar ~
8542 \SpecialChar ~
8543 \SpecialChar ~
8544 \SpecialChar ~
8545 \SpecialChar ~
8546 \SpecialChar ~
8547 out (_IoPort),a
8548 \layout Subsubsection
8549
8550 banked sfr
8551 \begin_inset LatexCommand \index{sfr}
8552
8553 \end_inset
8554
8555  (in/out to 16-bit addresses)
8556 \layout Standard
8557
8558 The keyword
8559 \emph on
8560 banked
8561 \emph default
8562  is used to support 16 bit addresses in I/O memory e.g.:
8563 \layout Verse
8564
8565
8566 \family typewriter
8567 sfr banked at
8568 \begin_inset LatexCommand \index{at}
8569
8570 \end_inset
8571
8572  0x123 IoPort;
8573 \layout Standard
8574
8575 Writing 0x01 to this variable generates the assembly code:
8576 \layout Verse
8577
8578
8579 \family typewriter
8580 01 23 01\SpecialChar ~
8581 \SpecialChar ~
8582 \SpecialChar ~
8583 ld bc,#_IoPort
8584 \newline
8585 3E 01\SpecialChar ~
8586 \SpecialChar ~
8587 \SpecialChar ~
8588 \SpecialChar ~
8589 \SpecialChar ~
8590 \SpecialChar ~
8591 ld a,#0x01
8592 \newline
8593 ED 79\SpecialChar ~
8594 \SpecialChar ~
8595 \SpecialChar ~
8596 \SpecialChar ~
8597 \SpecialChar ~
8598 \SpecialChar ~
8599 out (c),a
8600 \layout Subsubsection
8601
8602 sfr
8603 \begin_inset LatexCommand \index{sfr}
8604
8605 \end_inset
8606
8607  (in0/out0 to 8 bit addresses on Z180
8608 \begin_inset LatexCommand \index{Z180}
8609
8610 \end_inset
8611
8612 /HD64180
8613 \begin_inset LatexCommand \index{HD64180}
8614
8615 \end_inset
8616
8617 )
8618 \layout Standard
8619
8620 The compiler option -
8621 \begin_inset ERT
8622 status Collapsed
8623
8624 \layout Standard
8625
8626 \backslash
8627 /
8628 \end_inset
8629
8630 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
8631 portmode
8632 \begin_inset LatexCommand \index{\#pragma portmode}
8633
8634 \end_inset
8635
8636 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
8637 ns
8638 \family typewriter
8639 in0/out0
8640 \family default
8641  instead of
8642 \family typewriter
8643 in/out
8644 \family default
8645 .
8646  If you include the file z180.h this will be set automatically.
8647 \layout Section
8648
8649 Absolute Addressing
8650 \begin_inset LatexCommand \index{Absolute addressing}
8651
8652 \end_inset
8653
8654
8655 \layout Standard
8656
8657 Data items can be assigned an absolute address with the
8658 \emph on
8659 at
8660 \begin_inset LatexCommand \index{at}
8661
8662 \end_inset
8663
8664  <address>
8665 \emph default
8666  keyword, in addition to a storage class, e.g.:
8667 \layout Verse
8668
8669
8670 \family typewriter
8671 xdata
8672 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8673
8674 \end_inset
8675
8676  at
8677 \begin_inset LatexCommand \index{at}
8678
8679 \end_inset
8680
8681  0x7ffe unsigned int chksum;
8682 \layout Standard
8683
8684 In the above example the variable chksum will located at 0x7ffe and 0x7fff
8685  of the external ram.
8686  The compiler does
8687 \emph on
8688 not
8689 \emph default
8690  reserve any space for variables declared in this way (they are implemented
8691  with an equate in the assembler).
8692  Thus it is left to the programmer to make sure there are no overlaps with
8693  other variables that are declared without the absolute address.
8694  The assembler listing file (.lst
8695 \begin_inset LatexCommand \index{<file>.lst}
8696
8697 \end_inset
8698
8699 ) and the linker output files (.rst
8700 \begin_inset LatexCommand \index{<file>.rst}
8701
8702 \end_inset
8703
8704 ) and (.map
8705 \begin_inset LatexCommand \index{<file>.map}
8706
8707 \end_inset
8708
8709 ) are good places to look for such overlaps.
8710  Variables with an absolute address are
8711 \emph on
8712 not
8713 \emph default
8714  initialized
8715 \begin_inset LatexCommand \index{Variable initialization}
8716
8717 \end_inset
8718
8719 .
8720 \layout Standard
8721
8722 In case of memory mapped I/O devices the keyword
8723 \emph on
8724 volatile
8725 \emph default
8726  should be used to tell the compiler that accesses might not be optimized
8727  away:
8728 \layout Verse
8729
8730
8731 \family typewriter
8732 volatile
8733 \begin_inset LatexCommand \index{volatile}
8734
8735 \end_inset
8736
8737  xdata
8738 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8739
8740 \end_inset
8741
8742  at
8743 \begin_inset LatexCommand \index{at}
8744
8745 \end_inset
8746
8747  0x8000 unsigned char PORTA_8255;
8748 \layout Standard
8749
8750 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
8751 r) array
8752 \family typewriter
8753 \size footnotesize
8754
8755 \begin_inset LatexCommand \index{Aligned array}
8756
8757 \end_inset
8758
8759
8760 \family default
8761 \size default
8762  starts at a block (256 byte) boundary
8763 \begin_inset LatexCommand \index{block boundary}
8764
8765 \end_inset
8766
8767  (section
8768 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
8769
8770 \end_inset
8771
8772  has an example).
8773 \newline
8774 Absolute addresses can be specified for variables in all storage classes,
8775  e.g.:
8776 \layout Verse
8777
8778
8779 \family typewriter
8780 bit
8781 \begin_inset LatexCommand \index{bit}
8782
8783 \end_inset
8784
8785  at
8786 \begin_inset LatexCommand \index{at}
8787
8788 \end_inset
8789
8790  0x02 bvar;
8791 \layout Standard
8792
8793 The above example will allocate the variable at offset 0x02 in the bit-addressab
8794 le space.
8795  There is no real advantage to assigning absolute addresses to variables
8796  in this manner, unless you want strict control over all the variables allocated.
8797  One possible use would be to write hardware portable code.
8798  For example, if you have a routine that uses one or more of the microcontroller
8799  I/O pins, and such pins are different for two different hardwares, you
8800  can declare the I/O pins in your routine using:
8801 \layout Verse
8802
8803
8804 \family typewriter
8805 extern volatile bit SDI;
8806 \newline
8807 extern volatile bit SCLK;
8808 \newline
8809 extern volatile bit CPOL;
8810 \newline
8811
8812 \newline
8813 void DS1306_put(unsigned char value)
8814 \newline
8815 {
8816 \newline
8817 \SpecialChar ~
8818 \SpecialChar ~
8819 \SpecialChar ~
8820 \SpecialChar ~
8821 unsigned char mask=0x80;
8822 \newline
8823
8824 \newline
8825 \SpecialChar ~
8826 \SpecialChar ~
8827 \SpecialChar ~
8828 \SpecialChar ~
8829 while(mask)
8830 \newline
8831 \SpecialChar ~
8832 \SpecialChar ~
8833 \SpecialChar ~
8834 \SpecialChar ~
8835 {
8836 \newline
8837 \SpecialChar ~
8838 \SpecialChar ~
8839 \SpecialChar ~
8840 \SpecialChar ~
8841 \SpecialChar ~
8842 \SpecialChar ~
8843 \SpecialChar ~
8844 \SpecialChar ~
8845 SDI=(value & mask)?1:0;
8846 \newline
8847 \SpecialChar ~
8848 \SpecialChar ~
8849 \SpecialChar ~
8850 \SpecialChar ~
8851 \SpecialChar ~
8852 \SpecialChar ~
8853 \SpecialChar ~
8854 \SpecialChar ~
8855 SCLK=!CPOL;
8856 \newline
8857 \SpecialChar ~
8858 \SpecialChar ~
8859 \SpecialChar ~
8860 \SpecialChar ~
8861 \SpecialChar ~
8862 \SpecialChar ~
8863 \SpecialChar ~
8864 \SpecialChar ~
8865 SCLK=CPOL;
8866 \newline
8867 \SpecialChar ~
8868 \SpecialChar ~
8869 \SpecialChar ~
8870 \SpecialChar ~
8871 \SpecialChar ~
8872 \SpecialChar ~
8873 \SpecialChar ~
8874 \SpecialChar ~
8875 mask/=2;
8876 \newline
8877 \SpecialChar ~
8878 \SpecialChar ~
8879 \SpecialChar ~
8880 \SpecialChar ~
8881 }
8882 \newline
8883 }
8884 \layout Standard
8885
8886 Then, someplace in the code for the first hardware you would use
8887 \layout Verse
8888
8889
8890 \family typewriter
8891 bit at 0x80 SDI;\SpecialChar ~
8892 \SpecialChar ~
8893 \SpecialChar ~
8894 \SpecialChar ~
8895 /* I/O port 0, bit 0 */
8896 \newline
8897 bit at 0x81 SCLK;\SpecialChar ~
8898 \SpecialChar ~
8899 \SpecialChar ~
8900 /* I/O port 0, bit 1 */
8901 \newline
8902 bit CPOL;\SpecialChar ~
8903 \SpecialChar ~
8904 \SpecialChar ~
8905 \SpecialChar ~
8906 \SpecialChar ~
8907 \SpecialChar ~
8908 \SpecialChar ~
8909 \SpecialChar ~
8910 \SpecialChar ~
8911 \SpecialChar ~
8912 \SpecialChar ~
8913 /* This is a variable, let the linker allocate this one */
8914 \layout Standard
8915
8916 Similarly, for the second hardware you would use
8917 \layout Verse
8918
8919
8920 \family typewriter
8921 bit at 0x83 SDI;\SpecialChar ~
8922 \SpecialChar ~
8923 \SpecialChar ~
8924 \SpecialChar ~
8925 /* I/O port 0, bit 3 */
8926 \newline
8927 bit at 0x91 SCLK;\SpecialChar ~
8928 \SpecialChar ~
8929 \SpecialChar ~
8930 /* I/O port 1, bit 1 */
8931 \newline
8932 bit
8933 \begin_inset LatexCommand \index{bit}
8934
8935 \end_inset
8936
8937  CPOL;\SpecialChar ~
8938 \SpecialChar ~
8939 \SpecialChar ~
8940 \SpecialChar ~
8941 \SpecialChar ~
8942 \SpecialChar ~
8943 \SpecialChar ~
8944 \SpecialChar ~
8945 \SpecialChar ~
8946 \SpecialChar ~
8947 \SpecialChar ~
8948 /* This is a variable, let the linker allocate this one */
8949 \layout Standard
8950
8951 and you can use the same hardware dependent routine without changes, as
8952  for example in a library.
8953  This is somehow similar to sbit, but only one absolute address has to be
8954  specified in the whole project.
8955 \layout Section
8956
8957 Parameters
8958 \begin_inset LatexCommand \index{Parameters}
8959
8960 \end_inset
8961
8962
8963 \begin_inset LatexCommand \index{function parameter}
8964
8965 \end_inset
8966
8967  & Local Variables
8968 \begin_inset LatexCommand \index{local variables}
8969
8970 \end_inset
8971
8972
8973 \layout Standard
8974
8975 Automatic (local) variables and parameters to functions can either be placed
8976  on the stack or in data-space.
8977  The default action of the compiler is to place these variables in the internal
8978  RAM (for small model) or external RAM (for large model).
8979  This in fact makes them similar to
8980 \emph on
8981 static
8982 \begin_inset LatexCommand \index{static}
8983
8984 \end_inset
8985
8986
8987 \emph default
8988  so by default functions are non-reentrant
8989 \begin_inset LatexCommand \index{reentrant}
8990
8991 \end_inset
8992
8993 .
8994
8995 \newline
8996
8997 \newline
8998 They can be placed on the stack
8999 \begin_inset LatexCommand \index{stack}
9000
9001 \end_inset
9002
9003  either by using the
9004 \emph on
9005  -
9006 \begin_inset ERT
9007 status Collapsed
9008
9009 \layout Standard
9010
9011 \backslash
9012 /
9013 \end_inset
9014
9015 -stack-auto
9016 \begin_inset LatexCommand \index{-\/-stack-auto}
9017
9018 \end_inset
9019
9020
9021 \emph default
9022  option or by using the
9023 \emph on
9024 reentrant
9025 \begin_inset LatexCommand \index{reentrant}
9026
9027 \end_inset
9028
9029
9030 \emph default
9031  keyword in the function declaration, e.g.:
9032 \layout Verse
9033
9034
9035 \family typewriter
9036 unsigned char foo(char i) reentrant
9037 \newline
9038 {
9039 \newline
9040 \SpecialChar ~
9041 \SpecialChar ~
9042 \SpecialChar ~
9043 \SpecialChar ~
9044 ...
9045
9046 \newline
9047 }
9048 \layout Standard
9049
9050 Since stack space on 8051 is limited, the
9051 \emph on
9052 reentrant
9053 \emph default
9054 keyword or the
9055 \emph on
9056  -
9057 \begin_inset ERT
9058 status Collapsed
9059
9060 \layout Standard
9061
9062 \backslash
9063 /
9064 \end_inset
9065
9066 -stack-auto
9067 \emph default
9068  option should be used sparingly.
9069  Note that the reentrant keyword just means that the parameters & local
9070  variables will be allocated to the stack, it
9071 \emph on
9072 does not
9073 \emph default
9074  mean that the function is register bank
9075 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9076
9077 \end_inset
9078
9079  independent.
9080 \newline
9081
9082 \newline
9083 Local variables
9084 \begin_inset LatexCommand \index{local variables}
9085
9086 \end_inset
9087
9088  can be assigned storage classes and absolute
9089 \begin_inset LatexCommand \index{Absolute addressing}
9090
9091 \end_inset
9092
9093  addresses, e.g.:
9094 \layout Verse
9095
9096
9097 \family typewriter
9098 unsigned char foo()
9099 \newline
9100 {
9101 \newline
9102 \SpecialChar ~
9103 \SpecialChar ~
9104 \SpecialChar ~
9105 \SpecialChar ~
9106 xdata unsigned char i;
9107 \newline
9108 \SpecialChar ~
9109 \SpecialChar ~
9110 \SpecialChar ~
9111 \SpecialChar ~
9112 bit bvar;
9113 \newline
9114 \SpecialChar ~
9115 \SpecialChar ~
9116 \SpecialChar ~
9117 \SpecialChar ~
9118 data at
9119 \begin_inset LatexCommand \index{at}
9120
9121 \end_inset
9122
9123  0x31 unsigned char j;
9124 \newline
9125 \SpecialChar ~
9126 \SpecialChar ~
9127 \SpecialChar ~
9128 \SpecialChar ~
9129 ...
9130
9131 \newline
9132 }
9133 \layout Standard
9134
9135 In the above example the variable
9136 \emph on
9137 i
9138 \emph default
9139  will be allocated in the external ram,
9140 \emph on
9141 bvar
9142 \emph default
9143  in bit addressable space and
9144 \emph on
9145  j
9146 \emph default
9147  in internal ram.
9148  When compiled with
9149 \emph on
9150 -
9151 \begin_inset ERT
9152 status Collapsed
9153
9154 \layout Standard
9155
9156 \backslash
9157 /
9158 \end_inset
9159
9160 -stack-auto
9161 \emph default
9162  or when a function is declared as
9163 \emph on
9164 reentrant
9165 \emph default
9166  this should only be done for static variables.
9167 \layout Standard
9168
9169 Parameters
9170 \begin_inset LatexCommand \index{function parameter}
9171
9172 \end_inset
9173
9174  however are not allowed any storage class
9175 \begin_inset LatexCommand \index{Storage class}
9176
9177 \end_inset
9178
9179 , (storage classes for parameters will be ignored), their allocation is
9180  governed by the memory model in use, and the reentrancy options.
9181 \layout Section
9182
9183 Overlaying
9184 \begin_inset LatexCommand \label{sub:Overlaying}
9185
9186 \end_inset
9187
9188
9189 \begin_inset LatexCommand \index{Overlaying}
9190
9191 \end_inset
9192
9193
9194 \layout Standard
9195
9196 For non-reentrant
9197 \begin_inset LatexCommand \index{reentrant}
9198
9199 \end_inset
9200
9201  functions SDCC will try to reduce internal ram space usage by overlaying
9202  parameters and local variables of a function (if possible).
9203  Parameters and local variables
9204 \begin_inset LatexCommand \index{local variables}
9205
9206 \end_inset
9207
9208  of a function will be allocated to an overlayable segment if the function
9209  has
9210 \emph on
9211 no other function calls and the function is non-reentrant and the memory
9212  model
9213 \begin_inset LatexCommand \index{Memory model}
9214
9215 \end_inset
9216
9217  is small.
9218
9219 \emph default
9220  If an explicit storage class
9221 \begin_inset LatexCommand \index{Storage class}
9222
9223 \end_inset
9224
9225  is specified for a local variable, it will NOT be overlayed.
9226 \layout Standard
9227
9228 Note that the compiler (not the linkage editor) makes the decision for overlayin
9229 g the data items.
9230  Functions that are called from an interrupt service routine should be preceded
9231  by a #pragma\SpecialChar ~
9232 nooverlay
9233 \begin_inset LatexCommand \index{\#pragma nooverlay}
9234
9235 \end_inset
9236
9237  if they are not reentrant.
9238 \layout Standard
9239
9240 Also note that the compiler does not do any processing of inline assembler
9241  code, so the compiler might incorrectly assign local variables and parameters
9242  of a function into the overlay segment if the inline assembler code calls
9243  other c-functions that might use the overlay.
9244  In that case the #pragma\SpecialChar ~
9245 nooverlay should be used.
9246 \layout Standard
9247
9248 Parameters and local variables of functions that contain 16 or 32 bit multiplica
9249 tion
9250 \begin_inset LatexCommand \index{Multiplication}
9251
9252 \end_inset
9253
9254  or division
9255 \begin_inset LatexCommand \index{Division}
9256
9257 \end_inset
9258
9259  will NOT be overlayed since these are implemented using external functions,
9260  e.g.:
9261 \layout Verse
9262
9263
9264 \family typewriter
9265 #pragma save
9266 \newline
9267 #pragma nooverlay
9268 \begin_inset LatexCommand \index{\#pragma nooverlay}
9269
9270 \end_inset
9271
9272
9273 \newline
9274 void set_error(unsigned char errcd)
9275 \newline
9276 {
9277 \newline
9278 \SpecialChar ~
9279 \SpecialChar ~
9280 \SpecialChar ~
9281 \SpecialChar ~
9282 P3 = errcd;
9283 \newline
9284 }
9285 \newline
9286 #pragma restore
9287 \newline
9288
9289 \newline
9290 void some_isr () interrupt
9291 \begin_inset LatexCommand \index{interrupt}
9292
9293 \end_inset
9294
9295  2
9296 \newline
9297 {
9298 \newline
9299 \SpecialChar ~
9300 \SpecialChar ~
9301 \SpecialChar ~
9302 \SpecialChar ~
9303 ...
9304 \newline
9305 \SpecialChar ~
9306 \SpecialChar ~
9307 \SpecialChar ~
9308 \SpecialChar ~
9309 set_error(10);
9310 \newline
9311 \SpecialChar ~
9312 \SpecialChar ~
9313 \SpecialChar ~
9314 \SpecialChar ~
9315 ...
9316
9317 \newline
9318 }
9319 \layout Standard
9320
9321 In the above example the parameter
9322 \emph on
9323 errcd
9324 \emph default
9325  for the function
9326 \emph on
9327 set_error
9328 \emph default
9329  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
9330 nooverlay was
9331  not present, this could cause unpredictable runtime behavior when called
9332  from an interrupt service routine.
9333  The #pragma\SpecialChar ~
9334 nooverlay ensures that the parameters and local variables for
9335  the function are NOT overlayed.
9336 \layout Section
9337
9338 Interrupt Service Routines
9339 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
9340
9341 \end_inset
9342
9343
9344 \layout Standard
9345
9346 SDCC allows
9347 \emph on
9348 i
9349 \emph default
9350 nterrupt
9351 \emph on
9352 s
9353 \emph default
9354 ervice
9355 \emph on
9356 r
9357 \emph default
9358 outines to be coded in C, with some extended keywords.
9359 \layout Verse
9360
9361
9362 \family typewriter
9363 void timer_isr (void) interrupt 1 using 1
9364 \newline
9365 {
9366 \newline
9367 \SpecialChar ~
9368 \SpecialChar ~
9369 \SpecialChar ~
9370 \SpecialChar ~
9371 ...
9372
9373 \newline
9374 }
9375 \layout Standard
9376
9377 The optional number following the
9378 \emph on
9379 interrupt
9380 \begin_inset LatexCommand \index{interrupt}
9381
9382 \end_inset
9383
9384
9385 \emph default
9386  keyword is the interrupt number this routine will service.
9387  When present, the compiler will insert a call to this routine in the interrupt
9388  vector table for the interrupt number specified.
9389  If you have multiple source files in your project, interrupt service routines
9390  can be present in any of them, but a prototype of the isr MUST be present
9391  or included in the file that contains the function
9392 \emph on
9393 main
9394 \emph default
9395 .
9396  The
9397 \emph on
9398 using
9399 \emph default
9400  keyword can be used to tell the compiler to use the specified register
9401  bank (8051 specific) when generating code for this function.
9402
9403 \newline
9404
9405 \layout Standard
9406
9407 Interrupt numbers and the corresponding address & descriptions for the Standard
9408  8051/8052 are listed below.
9409  SDCC will automatically adjust the interrupt vector table to the maximum
9410  interrupt number specified.
9411 \newline
9412
9413 \layout Standard
9414 \align center
9415
9416 \begin_inset  Tabular
9417 <lyxtabular version="3" rows="7" columns="3">
9418 <features>
9419 <column alignment="center" valignment="top" leftline="true" width="0in">
9420 <column alignment="center" valignment="top" leftline="true" width="0in">
9421 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
9422 <row topline="true" bottomline="true">
9423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9424 \begin_inset Text
9425
9426 \layout Standard
9427
9428 Interrupt #
9429 \end_inset
9430 </cell>
9431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9432 \begin_inset Text
9433
9434 \layout Standard
9435
9436 Description
9437 \end_inset
9438 </cell>
9439 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9440 \begin_inset Text
9441
9442 \layout Standard
9443
9444 Vector Address
9445 \end_inset
9446 </cell>
9447 </row>
9448 <row topline="true">
9449 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9450 \begin_inset Text
9451
9452 \layout Standard
9453
9454 0
9455 \end_inset
9456 </cell>
9457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9458 \begin_inset Text
9459
9460 \layout Standard
9461
9462 External 0
9463 \end_inset
9464 </cell>
9465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9466 \begin_inset Text
9467
9468 \layout Standard
9469
9470 0x0003
9471 \end_inset
9472 </cell>
9473 </row>
9474 <row topline="true">
9475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9476 \begin_inset Text
9477
9478 \layout Standard
9479
9480 1
9481 \end_inset
9482 </cell>
9483 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9484 \begin_inset Text
9485
9486 \layout Standard
9487
9488 Timer 0
9489 \end_inset
9490 </cell>
9491 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9492 \begin_inset Text
9493
9494 \layout Standard
9495
9496 0x000B
9497 \end_inset
9498 </cell>
9499 </row>
9500 <row topline="true">
9501 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9502 \begin_inset Text
9503
9504 \layout Standard
9505
9506 2
9507 \end_inset
9508 </cell>
9509 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9510 \begin_inset Text
9511
9512 \layout Standard
9513
9514 External 1
9515 \end_inset
9516 </cell>
9517 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9518 \begin_inset Text
9519
9520 \layout Standard
9521
9522 0x0013
9523 \end_inset
9524 </cell>
9525 </row>
9526 <row topline="true">
9527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9528 \begin_inset Text
9529
9530 \layout Standard
9531
9532 3
9533 \end_inset
9534 </cell>
9535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9536 \begin_inset Text
9537
9538 \layout Standard
9539
9540 Timer 1
9541 \end_inset
9542 </cell>
9543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9544 \begin_inset Text
9545
9546 \layout Standard
9547
9548 0x001B
9549 \end_inset
9550 </cell>
9551 </row>
9552 <row topline="true">
9553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9554 \begin_inset Text
9555
9556 \layout Standard
9557
9558 4
9559 \end_inset
9560 </cell>
9561 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9562 \begin_inset Text
9563
9564 \layout Standard
9565
9566 Serial
9567 \end_inset
9568 </cell>
9569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9570 \begin_inset Text
9571
9572 \layout Standard
9573
9574 0x0023
9575 \end_inset
9576 </cell>
9577 </row>
9578 <row topline="true" bottomline="true">
9579 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9580 \begin_inset Text
9581
9582 \layout Standard
9583
9584 5
9585 \end_inset
9586 </cell>
9587 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9588 \begin_inset Text
9589
9590 \layout Standard
9591
9592 Timer 2 (8052)
9593 \end_inset
9594 </cell>
9595 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9596 \begin_inset Text
9597
9598 \layout Standard
9599
9600 0x002B
9601 \end_inset
9602 </cell>
9603 </row>
9604 </lyxtabular>
9605
9606 \end_inset
9607
9608
9609 \newline
9610
9611 \layout Standard
9612
9613 If the interrupt service routine is defined without
9614 \emph on
9615 using
9616 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
9617
9618 \end_inset
9619
9620
9621 \emph default
9622  a register bank or with register bank 0 (
9623 \emph on
9624 using
9625 \emph default
9626  0), the compiler will save the registers used by itself on the stack upon
9627  entry and restore them at exit, however if such an interrupt service routine
9628  calls another function then the entire register bank will be saved on the
9629  stack.
9630  This scheme may be advantageous for small interrupt service routines which
9631  have low register usage.
9632 \layout Standard
9633
9634 If the interrupt service routine is defined to be using a specific register
9635  bank then only
9636 \emph on
9637 a, b, dptr
9638 \emph default
9639  & psw are saved and restored, if such an interrupt service routine calls
9640  another function (using another register bank) then the entire register
9641  bank of the called function will be saved on the stack.
9642  This scheme is recommended for larger interrupt service routines.
9643 \layout Standard
9644
9645 Interrupt service routines open the door for some very interesting bugs:
9646
9647 \layout Standard
9648
9649 If the interrupt service routines changes variables which are accessed by
9650  other functions these variables should be declared
9651 \emph on
9652 volatile
9653 \emph default
9654
9655 \begin_inset LatexCommand \index{volatile}
9656
9657 \end_inset
9658
9659 .
9660
9661 \layout Standard
9662
9663 If the access to these variables is not
9664 \emph on
9665 atomic
9666 \begin_inset LatexCommand \index{atomic access}
9667
9668 \end_inset
9669
9670
9671 \emph default
9672  (i.e.
9673  the processor needs more than one instruction for the access and could
9674  be interrupted while accessing the variable) the interrupt must disabled
9675  during the access to avoid inconsistent data.
9676  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
9677  and should be protected by disabling interrupts.
9678  You're not automatically on the safe side if you use 8 bit variables though.
9679  We need an example here: f.e.
9680  on the 8051 the harmless looking
9681 \begin_inset Quotes srd
9682 \end_inset
9683
9684
9685 \family typewriter
9686 flags\SpecialChar ~
9687 |=\SpecialChar ~
9688 0x80;
9689 \family default
9690
9691 \begin_inset Quotes sld
9692 \end_inset
9693
9694  is not atomic if
9695 \family typewriter
9696 flags
9697 \family default
9698  resides in xdata.
9699  Setting
9700 \begin_inset Quotes srd
9701 \end_inset
9702
9703
9704 \family typewriter
9705 flags\SpecialChar ~
9706 |=\SpecialChar ~
9707 0x40;
9708 \family default
9709
9710 \begin_inset Quotes sld
9711 \end_inset
9712
9713  from within an interrupt routine might get lost if the interrupt occurs
9714  at the wrong time.
9715
9716 \begin_inset Quotes sld
9717 \end_inset
9718
9719
9720 \family typewriter
9721 counter\SpecialChar ~
9722 +=\SpecialChar ~
9723 8;
9724 \family default
9725
9726 \begin_inset Quotes srd
9727 \end_inset
9728
9729  is not atomic on the 8051 even if
9730 \family typewriter
9731 counter
9732 \family default
9733  is located in data memory.
9734  Bugs like these are hard to reproduce and can cause a lot of trouble.
9735
9736 \layout Standard
9737
9738 A special note here, int (16 bit) and long (32 bit) integer division
9739 \begin_inset LatexCommand \index{Division}
9740
9741 \end_inset
9742
9743 , multiplication
9744 \begin_inset LatexCommand \index{Multiplication}
9745
9746 \end_inset
9747
9748  & modulus
9749 \begin_inset LatexCommand \index{Modulus}
9750
9751 \end_inset
9752
9753  and floating-point
9754 \begin_inset LatexCommand \index{Floating point support}
9755
9756 \end_inset
9757
9758  operations are implemented using external support routines developed in
9759  ANSI-C.
9760  If an interrupt service routine needs to do any of these operations then
9761  the support routines (as mentioned in a following section) will have to
9762  be recompiled using the
9763 \emph on
9764  -
9765 \begin_inset ERT
9766 status Collapsed
9767
9768 \layout Standard
9769
9770 \backslash
9771 /
9772 \end_inset
9773
9774 -stack-auto
9775 \begin_inset LatexCommand \index{-\/-stack-auto}
9776
9777 \end_inset
9778
9779
9780 \emph default
9781  option and the source file will need to be compiled using the
9782 \emph on
9783 -
9784 \begin_inset ERT
9785 status Collapsed
9786
9787 \layout Standard
9788
9789 \backslash
9790 /
9791 \end_inset
9792
9793 -int-long-reent
9794 \emph default
9795
9796 \begin_inset LatexCommand \index{-\/-int-long-reent}
9797
9798 \end_inset
9799
9800  compiler option.
9801 \layout Standard
9802
9803 Calling other functions from an interrupt service routine is not recommended,
9804  avoid it if possible.
9805  Note that when some function is called from an interrupt service routine
9806  it should be preceded by a #pragma\SpecialChar ~
9807 nooverlay
9808 \begin_inset LatexCommand \index{\#pragma nooverlay}
9809
9810 \end_inset
9811
9812  if it is not reentrant.
9813  Furthermore nonreentrant functions should not be called from the main program
9814  while the interrupt service routine might be active.
9815
9816 \newline
9817
9818 \newline
9819 Also see section
9820 \begin_inset LatexCommand \ref{sub:Overlaying}
9821
9822 \end_inset
9823
9824 \SpecialChar ~
9825 about Overlaying and section
9826 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
9827
9828 \end_inset
9829
9830 \SpecialChar ~
9831 about Functions using private register banks.
9832 \layout Section
9833
9834 Enabling and Disabling Interrupts
9835 \layout Subsection
9836
9837 Critical Functions and Critical Statements
9838 \layout Standard
9839
9840 A special keyword may be associated with a block or a function declaring
9841  it as
9842 \emph on
9843 critical
9844 \emph default
9845 .
9846  SDCC will generate code to disable all interrupts
9847 \begin_inset LatexCommand \index{interrupt}
9848
9849 \end_inset
9850
9851  upon entry to a critical function and restore the interrupt enable to the
9852  previous state before returning.
9853  Nesting critical functions will need one additional byte on the stack
9854 \begin_inset LatexCommand \index{stack}
9855
9856 \end_inset
9857
9858  for each call.
9859 \layout Verse
9860
9861
9862 \family typewriter
9863 int foo () critical
9864 \begin_inset LatexCommand \index{critical}
9865
9866 \end_inset
9867
9868
9869 \newline
9870 {
9871 \newline
9872 \SpecialChar ~
9873 \SpecialChar ~
9874 \SpecialChar ~
9875 \SpecialChar ~
9876 ...
9877
9878 \newline
9879 \SpecialChar ~
9880 \SpecialChar ~
9881 \SpecialChar ~
9882 \SpecialChar ~
9883 ...
9884
9885 \newline
9886 }
9887 \layout Standard
9888
9889 The critical attribute maybe used with other attributes like
9890 \emph on
9891 reentrant.
9892 \emph default
9893
9894 \newline
9895 The keyword
9896 \emph on
9897 critical
9898 \emph default
9899  may also be used to disable interrupts more locally:
9900 \layout Verse
9901
9902
9903 \family typewriter
9904 critical{ i++; }
9905 \layout Standard
9906
9907 More than one statement could have been included in the block.
9908 \layout Subsection
9909
9910 Enabling and Disabling Interrupts directly
9911 \layout Standard
9912
9913 Interrupts
9914 \begin_inset LatexCommand \index{interrupt}
9915
9916 \end_inset
9917
9918  can also be disabled and enabled directly (8051):
9919 \layout Verse
9920
9921
9922 \family typewriter
9923 EA = 0;\SpecialChar ~
9924 \SpecialChar ~
9925 \SpecialChar ~
9926 \SpecialChar ~
9927 \SpecialChar ~
9928 \SpecialChar ~
9929 \SpecialChar ~
9930 \SpecialChar ~
9931 \SpecialChar ~
9932 \SpecialChar ~
9933 \SpecialChar ~
9934 \SpecialChar ~
9935 or:\SpecialChar ~
9936 \SpecialChar ~
9937 \SpecialChar ~
9938 \SpecialChar ~
9939 \SpecialChar ~
9940 \SpecialChar ~
9941 \SpecialChar ~
9942 \SpecialChar ~
9943 \SpecialChar ~
9944 \SpecialChar ~
9945 \SpecialChar ~
9946 EA_SAVE = EA;
9947 \layout Verse
9948
9949
9950 \family typewriter
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 \SpecialChar ~
9981 EA = 0;
9982 \layout Verse
9983
9984
9985 \family typewriter
9986 EA = 1;\SpecialChar ~
9987 \SpecialChar ~
9988 \SpecialChar ~
9989 \SpecialChar ~
9990 \SpecialChar ~
9991 \SpecialChar ~
9992 \SpecialChar ~
9993 \SpecialChar ~
9994 \SpecialChar ~
9995 \SpecialChar ~
9996 \SpecialChar ~
9997 \SpecialChar ~
9998 \SpecialChar ~
9999 \SpecialChar ~
10000 \SpecialChar ~
10001 \SpecialChar ~
10002 \SpecialChar ~
10003 \SpecialChar ~
10004 \SpecialChar ~
10005 \SpecialChar ~
10006 \SpecialChar ~
10007 \SpecialChar ~
10008 \SpecialChar ~
10009 \SpecialChar ~
10010 \SpecialChar ~
10011 \SpecialChar ~
10012 ...
10013 \layout Verse
10014
10015
10016 \family typewriter
10017 \SpecialChar ~
10018 \SpecialChar ~
10019 \SpecialChar ~
10020 \SpecialChar ~
10021 \SpecialChar ~
10022 \SpecialChar ~
10023 \SpecialChar ~
10024 \SpecialChar ~
10025 \SpecialChar ~
10026 \SpecialChar ~
10027 \SpecialChar ~
10028 \SpecialChar ~
10029 \SpecialChar ~
10030 \SpecialChar ~
10031 \SpecialChar ~
10032 \SpecialChar ~
10033 \SpecialChar ~
10034 \SpecialChar ~
10035 \SpecialChar ~
10036 \SpecialChar ~
10037 \SpecialChar ~
10038 \SpecialChar ~
10039 \SpecialChar ~
10040 \SpecialChar ~
10041 \SpecialChar ~
10042 \SpecialChar ~
10043 \SpecialChar ~
10044 \SpecialChar ~
10045 \SpecialChar ~
10046 \SpecialChar ~
10047 \SpecialChar ~
10048 \SpecialChar ~
10049 \SpecialChar ~
10050 EA = EA_SAVE;
10051 \layout Standard
10052
10053 On other architectures which have seperate opcodes for enabling and disabling
10054  interrupts you might want to make use of defines with inline assembly
10055 \begin_inset LatexCommand \index{Assembler routines}
10056
10057 \end_inset
10058
10059  (HC08):
10060 \layout Verse
10061
10062
10063 \family typewriter
10064 #define CLI _asm
10065 \begin_inset LatexCommand \index{\_asm}
10066
10067 \end_inset
10068
10069 \SpecialChar ~
10070 \SpecialChar ~
10071 cli\SpecialChar ~
10072 \SpecialChar ~
10073 _endasm
10074 \begin_inset LatexCommand \index{\_endasm}
10075
10076 \end_inset
10077
10078 ;
10079 \layout Verse
10080
10081
10082 \family typewriter
10083 #define SEI _asm\SpecialChar ~
10084 \SpecialChar ~
10085 sei\SpecialChar ~
10086 \SpecialChar ~
10087 _endasm;
10088 \layout Verse
10089
10090
10091 \family typewriter
10092 ...
10093 \layout Standard
10094
10095 Note: it is sometimes sufficient to disable only a specific interrupt source
10096  like f.e.
10097  a timer or serial interrupt by manipulating an
10098 \emph on
10099 interrupt mask
10100 \begin_inset LatexCommand \index{interrupt mask}
10101
10102 \end_inset
10103
10104
10105 \emph default
10106  register.
10107
10108 \layout Standard
10109
10110 Usually the time during which interrupts are disabled should be kept as
10111  short as possible.
10112  This minimizes both
10113 \emph on
10114 interrupt latency
10115 \emph default
10116
10117 \begin_inset LatexCommand \index{interrupt latency}
10118
10119 \end_inset
10120
10121  (the time between the occurrence of the interrupt and the execution of
10122  the first code in the interrupt routine) and
10123 \emph on
10124 interrupt jitter
10125 \emph default
10126
10127 \begin_inset LatexCommand \index{interrupt jitter}
10128
10129 \end_inset
10130
10131  (the difference between the shortest and the longest interrupt latency).
10132  These really are something different, f.e.
10133  a serial interrupt has to be served before its buffer overruns so it cares
10134  for the maximum interrupt latency, whereas it does not care about jitter.
10135  On a loudspeaker driven via a digital to analog converter which is fed
10136  by an interrupt a latency of a few milliseconds might be tolerable, whereas
10137  a much smaller jitter will be very audible.
10138 \layout Standard
10139
10140 You can reenable interrupts within an interrupt routine and on some architecture
10141 s you can make use of two (or more) levels of
10142 \emph on
10143 interrupt priorities
10144 \emph default
10145
10146 \begin_inset LatexCommand \index{interrupt priority}
10147
10148 \end_inset
10149
10150 .
10151  On some architectures which don't support interrupt priorities these can
10152  be implemented by manipulating the interrupt mask and reenabling interrupts
10153  within the interrupt routine.
10154  Don't add complexity unless you have to.
10155
10156 \layout Section
10157
10158 Functions using private register banks
10159 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
10160
10161 \end_inset
10162
10163  (mcs51/ds390)
10164 \layout Standard
10165
10166 Some architectures have support for quickly changing register sets.
10167  SDCC supports this feature with the
10168 \emph on
10169 using
10170 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10171
10172 \end_inset
10173
10174
10175 \emph default
10176  attribute (which tells the compiler to use a register bank
10177 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10178
10179 \end_inset
10180
10181  other than the default bank zero).
10182  It should only be applied to
10183 \emph on
10184 interrupt
10185 \begin_inset LatexCommand \index{interrupt}
10186
10187 \end_inset
10188
10189
10190 \emph default
10191  functions (see footnote below).
10192  This will in most circumstances make the generated ISR code more efficient
10193  since it will not have to save registers on the stack.
10194 \layout Standard
10195
10196 The
10197 \emph on
10198 using
10199 \emph default
10200  attribute will have no effect on the generated code for a
10201 \emph on
10202 non-interrupt
10203 \emph default
10204  function (but may occasionally be useful anyway
10205 \begin_inset Foot
10206 collapsed false
10207
10208 \layout Standard
10209
10210 possible exception: if a function is called ONLY from 'interrupt' functions
10211  using a particular bank, it can be declared with the same 'using' attribute
10212  as the calling 'interrupt' functions.
10213  For instance, if you have several ISRs using bank one, and all of them
10214  call memcpy(), it might make sense to create a specialized version of memcpy()
10215  'using 1', since this would prevent the ISR from having to save bank zero
10216  to the stack on entry and switch to bank zero before calling the function
10217 \end_inset
10218
10219 ).
10220 \newline
10221
10222 \emph on
10223 (pending: I don't think this has been done yet)
10224 \layout Standard
10225
10226 An
10227 \emph on
10228 interrupt
10229 \emph default
10230  function using a non-zero bank will assume that it can trash that register
10231  bank, and will not save it.
10232  Since high-priority interrupts
10233 \begin_inset LatexCommand \index{interrupt priority}
10234
10235 \end_inset
10236
10237  can interrupt low-priority ones on the 8051 and friends, this means that
10238  if a high-priority ISR
10239 \emph on
10240 using
10241 \emph default
10242  a particular bank occurs while processing a low-priority ISR
10243 \emph on
10244 using
10245 \emph default
10246  the same bank, terrible and bad things can happen.
10247  To prevent this, no single register bank should be
10248 \emph on
10249 used
10250 \emph default
10251  by both a high priority and a low priority ISR.
10252  This is probably most easily done by having all high priority ISRs use
10253  one bank and all low priority ISRs use another.
10254  If you have an ISR which can change priority at runtime, you're on your
10255  own: I suggest using the default bank zero and taking the small performance
10256  hit.
10257 \layout Standard
10258
10259 It is most efficient if your ISR calls no other functions.
10260  If your ISR must call other functions, it is most efficient if those functions
10261  use the same bank as the ISR (see note 1 below); the next best is if the
10262  called functions use bank zero.
10263  It is very inefficient to call a function using a different, non-zero bank
10264  from an ISR.
10265
10266 \layout Section
10267
10268 Startup Code
10269 \begin_inset LatexCommand \label{sub:Startup-Code}
10270
10271 \end_inset
10272
10273
10274 \begin_inset LatexCommand \index{Startup code}
10275
10276 \end_inset
10277
10278
10279 \layout Subsection
10280
10281 MCS51/DS390 Startup Code
10282 \layout Standard
10283
10284 The compiler inserts a call to the C routine
10285 \emph on
10286 _sdcc_external_startup()
10287 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
10288
10289 \end_inset
10290
10291
10292 \series bold
10293 \emph default
10294
10295 \series default
10296 at the start of the CODE area.
10297  This routine is in the runtime library
10298 \begin_inset LatexCommand \index{Runtime library}
10299
10300 \end_inset
10301
10302 .
10303  By default this routine returns 0, if this routine returns a non-zero value,
10304  the static & global variable initialization will be skipped and the function
10305  main will be invoked.
10306  Otherwise static & global variables will be initialized before the function
10307  main is invoked.
10308  You could add a
10309 \emph on
10310 _sdcc_external_startup()
10311 \emph default
10312  routine to your program to override the default if you need to setup hardware
10313  or perform some other critical operation prior to static & global variable
10314  initialization.
10315  On some mcs51 variants xdata has to be explicitly enabled before it can
10316  be accessed, this is the place to do it.
10317  See also the compiler option
10318 \emph on
10319 -
10320 \begin_inset ERT
10321 status Collapsed
10322
10323 \layout Standard
10324
10325 \backslash
10326 /
10327 \end_inset
10328
10329 -no-xinit
10330 \emph default
10331 -
10332 \emph on
10333 opt
10334 \emph default
10335
10336 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
10337
10338 \end_inset
10339
10340  and section
10341 \begin_inset LatexCommand \ref{sub:MCS51-variants}
10342
10343 \end_inset
10344
10345 \SpecialChar ~
10346 about MCS51-variants.
10347 \layout Subsection
10348
10349 HC08 Startup Code
10350 \layout Standard
10351
10352 The HC08 startup code follows the same scheme as the MCS51 startup code.
10353 \layout Subsection
10354
10355 Z80 Startup Code
10356 \layout Standard
10357
10358 On the Z80 the startup code is inserted by linking with crt0.o which is generated
10359  from sdcc/device/lib/z80/crt0.s.
10360  If you need a different startup code you can use the compiler option
10361 \emph on
10362 -
10363 \series bold
10364 \emph default
10365
10366 \begin_inset ERT
10367 status Collapsed
10368
10369 \layout Standard
10370
10371 \backslash
10372 /
10373 \end_inset
10374
10375
10376 \series default
10377 \emph on
10378 -no-std-crt0
10379 \emph default
10380
10381 \begin_inset LatexCommand \index{-\/-no-std-crt0}
10382
10383 \end_inset
10384
10385  and provide your own crt0.o.
10386
10387 \layout Section
10388
10389 Inline Assembler Code
10390 \begin_inset LatexCommand \index{Assembler routines}
10391
10392 \end_inset
10393
10394
10395 \layout Subsection
10396
10397 A Step by Step Introduction
10398 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
10399
10400 \end_inset
10401
10402
10403 \layout Standard
10404
10405 Starting from a small snippet of c-code this example shows for the MCS51
10406  how to use inline assembly, access variables, a function parameter and
10407  an array in xdata memory.
10408  The example uses an MCS51 here but is easily adapted for other architectures.
10409  This is a buffer routine which should be optimized:
10410 \layout Verse
10411
10412
10413 \family typewriter
10414 \size footnotesize
10415 unsigned char far
10416 \begin_inset LatexCommand \index{far (storage class)}
10417
10418 \end_inset
10419
10420  at
10421 \begin_inset LatexCommand \index{at}
10422
10423 \end_inset
10424
10425  0x7f00 buf[0x100];
10426 \begin_inset LatexCommand \index{Aligned array}
10427
10428 \end_inset
10429
10430
10431 \newline
10432 unsigned char head,tail;
10433 \newline
10434
10435 \newline
10436 void to_buffer( unsigned char c )
10437 \newline
10438 {
10439 \newline
10440 \SpecialChar ~
10441 \SpecialChar ~
10442 \SpecialChar ~
10443 \SpecialChar ~
10444 if( head != tail-1 )
10445 \newline
10446 \SpecialChar ~
10447 \SpecialChar ~
10448 \SpecialChar ~
10449 \SpecialChar ~
10450 \SpecialChar ~
10451 \SpecialChar ~
10452 \SpecialChar ~
10453 \SpecialChar ~
10454 buf[ head++ ] = c;
10455 \newline
10456 }
10457 \layout Standard
10458
10459 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
10460  then a corresponding buffer.asm file is generated.
10461  We define a new function
10462 \family typewriter
10463 to_buffer_asm()
10464 \family default
10465  in file buffer.c in which we cut and paste the generated code, removing
10466  unwanted comments and some ':'.
10467  Then add
10468 \begin_inset Quotes sld
10469 \end_inset
10470
10471 _asm
10472 \begin_inset Quotes srd
10473 \end_inset
10474
10475  and
10476 \begin_inset Quotes sld
10477 \end_inset
10478
10479 _endasm;
10480 \begin_inset Quotes srd
10481 \end_inset
10482
10483  to the beginning and the end of the function body:
10484 \layout Verse
10485
10486
10487 \family typewriter
10488 \size footnotesize
10489 /* With a cut and paste from the .asm file, we have something to start with.
10490 \newline
10491 \SpecialChar ~
10492 \SpecialChar ~
10493 \SpecialChar ~
10494 The function is not yet OK! (registers aren't saved) */
10495 \newline
10496 void to_buffer_asm( unsigned char c )
10497 \newline
10498 {
10499 \newline
10500 \SpecialChar ~
10501 \SpecialChar ~
10502 \SpecialChar ~
10503 \SpecialChar ~
10504 _asm
10505 \begin_inset LatexCommand \index{\_asm}
10506
10507 \end_inset
10508
10509
10510 \newline
10511 \SpecialChar ~
10512 \SpecialChar ~
10513 \SpecialChar ~
10514 \SpecialChar ~
10515 mov\SpecialChar ~
10516 \SpecialChar ~
10517 r2,dpl
10518 \newline
10519 ;buffer.c if( head != tail-1 )
10520 \newline
10521 \SpecialChar ~
10522 \SpecialChar ~
10523 \SpecialChar ~
10524 \SpecialChar ~
10525 mov\SpecialChar ~
10526 \SpecialChar ~
10527 a,_tail
10528 \newline
10529 \SpecialChar ~
10530 \SpecialChar ~
10531 \SpecialChar ~
10532 \SpecialChar ~
10533 dec\SpecialChar ~
10534 \SpecialChar ~
10535 a
10536 \newline
10537 \SpecialChar ~
10538 \SpecialChar ~
10539 \SpecialChar ~
10540 \SpecialChar ~
10541 mov\SpecialChar ~
10542 \SpecialChar ~
10543 r3,a
10544 \newline
10545 \SpecialChar ~
10546 \SpecialChar ~
10547 \SpecialChar ~
10548 \SpecialChar ~
10549 mov\SpecialChar ~
10550 \SpecialChar ~
10551 a,_head
10552 \newline
10553 \SpecialChar ~
10554 \SpecialChar ~
10555 \SpecialChar ~
10556 \SpecialChar ~
10557 cjne a,ar3,00106$
10558 \newline
10559 \SpecialChar ~
10560 \SpecialChar ~
10561 \SpecialChar ~
10562 \SpecialChar ~
10563 ret
10564 \newline
10565 00106$:
10566 \newline
10567 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
10568 \begin_inset LatexCommand \index{Aligned array}
10569
10570 \end_inset
10571
10572
10573 \newline
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 mov\SpecialChar ~
10579 \SpecialChar ~
10580 r3,_head
10581 \newline
10582 \SpecialChar ~
10583 \SpecialChar ~
10584 \SpecialChar ~
10585 \SpecialChar ~
10586 inc\SpecialChar ~
10587 \SpecialChar ~
10588 _head
10589 \newline
10590 \SpecialChar ~
10591 \SpecialChar ~
10592 \SpecialChar ~
10593 \SpecialChar ~
10594 mov\SpecialChar ~
10595 \SpecialChar ~
10596 dpl,r3
10597 \newline
10598 \SpecialChar ~
10599 \SpecialChar ~
10600 \SpecialChar ~
10601 \SpecialChar ~
10602 mov\SpecialChar ~
10603 \SpecialChar ~
10604 dph,#(_buf >> 8)
10605 \newline
10606 \SpecialChar ~
10607 \SpecialChar ~
10608 \SpecialChar ~
10609 \SpecialChar ~
10610 mov\SpecialChar ~
10611 \SpecialChar ~
10612 a,r2
10613 \newline
10614 \SpecialChar ~
10615 \SpecialChar ~
10616 \SpecialChar ~
10617 \SpecialChar ~
10618 movx @dptr,a
10619 \newline
10620 00103$:
10621 \newline
10622 \SpecialChar ~
10623 \SpecialChar ~
10624 \SpecialChar ~
10625 \SpecialChar ~
10626 ret
10627 \newline
10628 \SpecialChar ~
10629 \SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 _endasm;
10633 \newline
10634 }
10635 \layout Standard
10636
10637 The new file buffer.c should compile with only one warning about the unreferenced
10638  function argument 'c'.
10639  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
10640  (1) and finally have:
10641 \layout Verse
10642
10643
10644 \family typewriter
10645 \size footnotesize
10646 unsigned char far at 0x7f00 buf[0x100];
10647 \newline
10648 unsigned char head,tail;
10649 \newline
10650 #define USE_ASSEMBLY (1)
10651 \newline
10652
10653 \newline
10654 #if USE_ASSEMBLY
10655 \newline
10656
10657 \newline
10658 void to_buffer( unsigned char c )
10659 \newline
10660 {
10661 \newline
10662 \SpecialChar ~
10663 \SpecialChar ~
10664 \SpecialChar ~
10665 \SpecialChar ~
10666 if( head != tail-1 )
10667 \newline
10668 \SpecialChar ~
10669 \SpecialChar ~
10670 \SpecialChar ~
10671 \SpecialChar ~
10672 \SpecialChar ~
10673 \SpecialChar ~
10674 \SpecialChar ~
10675 \SpecialChar ~
10676 buf[ head++ ] = c;
10677 \newline
10678 }
10679 \newline
10680
10681 \newline
10682 #else
10683 \newline
10684
10685 \newline
10686 void to_buffer( unsigned char c )
10687 \newline
10688 {
10689 \newline
10690 \SpecialChar ~
10691 \SpecialChar ~
10692 \SpecialChar ~
10693 \SpecialChar ~
10694 c; // to avoid warning: unreferenced function argument
10695 \newline
10696 \SpecialChar ~
10697 \SpecialChar ~
10698 \SpecialChar ~
10699 \SpecialChar ~
10700 _asm
10701 \begin_inset LatexCommand \index{\_asm}
10702
10703 \end_inset
10704
10705
10706 \newline
10707 \SpecialChar ~
10708 \SpecialChar ~
10709 \SpecialChar ~
10710 \SpecialChar ~
10711 \SpecialChar ~
10712 \SpecialChar ~
10713 \SpecialChar ~
10714 \SpecialChar ~
10715 ; save used registers here.
10716
10717 \newline
10718 \SpecialChar ~
10719 \SpecialChar ~
10720 \SpecialChar ~
10721 \SpecialChar ~
10722 \SpecialChar ~
10723 \SpecialChar ~
10724 \SpecialChar ~
10725 \SpecialChar ~
10726 ; If we were still using r2,r3 we would have to push them here.
10727
10728 \newline
10729 ; if( head != tail-1 )
10730 \newline
10731 \SpecialChar ~
10732 \SpecialChar ~
10733 \SpecialChar ~
10734 \SpecialChar ~
10735 \SpecialChar ~
10736 \SpecialChar ~
10737 \SpecialChar ~
10738 \SpecialChar ~
10739 mov\SpecialChar ~
10740  a,_tail
10741 \newline
10742 \SpecialChar ~
10743 \SpecialChar ~
10744 \SpecialChar ~
10745 \SpecialChar ~
10746 \SpecialChar ~
10747 \SpecialChar ~
10748 \SpecialChar ~
10749 \SpecialChar ~
10750 dec\SpecialChar ~
10751  a
10752 \newline
10753 \SpecialChar ~
10754 \SpecialChar ~
10755 \SpecialChar ~
10756 \SpecialChar ~
10757 \SpecialChar ~
10758 \SpecialChar ~
10759 \SpecialChar ~
10760 \SpecialChar ~
10761 xrl\SpecialChar ~
10762  a,_head
10763 \newline
10764 \SpecialChar ~
10765 \SpecialChar ~
10766 \SpecialChar ~
10767 \SpecialChar ~
10768 \SpecialChar ~
10769 \SpecialChar ~
10770 \SpecialChar ~
10771 \SpecialChar ~
10772 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
10773 \newline
10774 \SpecialChar ~
10775 \SpecialChar ~
10776 \SpecialChar ~
10777 \SpecialChar ~
10778 \SpecialChar ~
10779 \SpecialChar ~
10780 \SpecialChar ~
10781 \SpecialChar ~
10782 jz\SpecialChar ~
10783 \SpecialChar ~
10784  t_b_end$
10785 \newline
10786 \SpecialChar ~
10787 \SpecialChar ~
10788 \SpecialChar ~
10789 \SpecialChar ~
10790 \SpecialChar ~
10791 \SpecialChar ~
10792 \SpecialChar ~
10793 \SpecialChar ~
10794 ;
10795 \newline
10796 ; buf[ head++ ] = c;
10797 \newline
10798 \SpecialChar ~
10799 \SpecialChar ~
10800 \SpecialChar ~
10801 \SpecialChar ~
10802 \SpecialChar ~
10803 \SpecialChar ~
10804 \SpecialChar ~
10805 \SpecialChar ~
10806 mov\SpecialChar ~
10807  a,dpl \SpecialChar ~
10808 \SpecialChar ~
10809 \SpecialChar ~
10810 \SpecialChar ~
10811 \SpecialChar ~
10812 \SpecialChar ~
10813 \SpecialChar ~
10814 ; dpl holds lower byte of function argument
10815 \newline
10816 \SpecialChar ~
10817 \SpecialChar ~
10818 \SpecialChar ~
10819 \SpecialChar ~
10820 \SpecialChar ~
10821 \SpecialChar ~
10822 \SpecialChar ~
10823 \SpecialChar ~
10824 mov\SpecialChar ~
10825  dpl,_head \SpecialChar ~
10826 \SpecialChar ~
10827 \SpecialChar ~
10828 ; buf is 0x100 byte aligned so head can be used directly
10829 \newline
10830 \SpecialChar ~
10831 \SpecialChar ~
10832 \SpecialChar ~
10833 \SpecialChar ~
10834 \SpecialChar ~
10835 \SpecialChar ~
10836 \SpecialChar ~
10837 \SpecialChar ~
10838 mov\SpecialChar ~
10839  dph,#(_buf>>8)
10840 \newline
10841 \SpecialChar ~
10842 \SpecialChar ~
10843 \SpecialChar ~
10844 \SpecialChar ~
10845 \SpecialChar ~
10846 \SpecialChar ~
10847 \SpecialChar ~
10848 \SpecialChar ~
10849 movx @dptr,a
10850 \newline
10851 \SpecialChar ~
10852 \SpecialChar ~
10853 \SpecialChar ~
10854 \SpecialChar ~
10855 \SpecialChar ~
10856 \SpecialChar ~
10857 \SpecialChar ~
10858 \SpecialChar ~
10859 inc \SpecialChar ~
10860 _head
10861 \newline
10862 \SpecialChar ~
10863 \SpecialChar ~
10864 \SpecialChar ~
10865 \SpecialChar ~
10866 \SpecialChar ~
10867 \SpecialChar ~
10868 \SpecialChar ~
10869 \SpecialChar ~
10870 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
10871 \newline
10872 t_b_end$:
10873 \newline
10874 \SpecialChar ~
10875 \SpecialChar ~
10876 \SpecialChar ~
10877 \SpecialChar ~
10878 \SpecialChar ~
10879 \SpecialChar ~
10880 \SpecialChar ~
10881 \SpecialChar ~
10882 ; restore used registers here
10883 \newline
10884 \SpecialChar ~
10885 \SpecialChar ~
10886 \SpecialChar ~
10887 \SpecialChar ~
10888 _endasm;
10889 \newline
10890 }
10891 \newline
10892 #endif
10893 \layout Standard
10894
10895 The inline assembler code can contain any valid code understood by the assembler
10896 , this includes any assembler directives and comment lines
10897 \begin_inset Foot
10898 collapsed false
10899
10900 \layout Standard
10901
10902 The assembler does not like some characters like ':' or ''' in comments.
10903  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
10904 \end_inset
10905
10906 .
10907  The compiler does not do any validation of the code within the
10908 \family typewriter
10909 _asm
10910 \begin_inset LatexCommand \index{\_asm}
10911
10912 \end_inset
10913
10914  ...
10915  _endasm;
10916 \family default
10917  keyword pair.
10918  Specifically it will not know which registers are used and thus register
10919  pushing/popping
10920 \begin_inset LatexCommand \index{push/pop}
10921
10922 \end_inset
10923
10924  has to be done manually.
10925
10926 \layout Standard
10927
10928 It is recommended that each assembly instruction (including labels) be placed
10929  in a separate line (as the example shows).
10930  When the -
10931 \begin_inset ERT
10932 status Collapsed
10933
10934 \layout Standard
10935
10936 \backslash
10937 /
10938 \end_inset
10939
10940 -
10941 \emph on
10942 peep-asm
10943 \begin_inset LatexCommand \index{-\/-peep-asm}
10944
10945 \end_inset
10946
10947
10948 \emph default
10949  command line option is used, the inline assembler code will be passed through
10950  the peephole optimizer
10951 \begin_inset LatexCommand \index{Peephole optimizer}
10952
10953 \end_inset
10954
10955 .
10956  There are only a few (if any) cases where this option makes sense, it might
10957  cause some unexpected changes in the inline assembler code.
10958  Please go through the peephole optimizer rules defined in file
10959 \emph on
10960 SDCCpeeph.def
10961 \emph default
10962  before using this option.
10963 \layout Subsection
10964
10965 Naked Functions
10966 \begin_inset LatexCommand \label{sub:Naked-Functions}
10967
10968 \end_inset
10969
10970
10971 \begin_inset LatexCommand \index{Naked functions}
10972
10973 \end_inset
10974
10975
10976 \layout Standard
10977
10978 A special keyword may be associated with a function declaring it as
10979 \emph on
10980 _naked
10981 \begin_inset LatexCommand \index{\_naked}
10982
10983 \end_inset
10984
10985 .
10986
10987 \emph default
10988 The
10989 \emph on
10990 _naked
10991 \emph default
10992  function modifier attribute prevents the compiler from generating prologue
10993 \begin_inset LatexCommand \index{function prologue}
10994
10995 \end_inset
10996
10997  and epilogue
10998 \begin_inset LatexCommand \index{function epilogue}
10999
11000 \end_inset
11001
11002  code for that function.
11003  This means that the user is entirely responsible for such things as saving
11004  any registers that may need to be preserved, selecting the proper register
11005  bank, generating the
11006 \emph on
11007 return
11008 \emph default
11009  instruction at the end, etc.
11010  Practically, this means that the contents of the function must be written
11011  in inline assembler.
11012  This is particularly useful for interrupt functions, which can have a large
11013  (and often unnecessary) prologue/epilogue.
11014  For example, compare the code generated by these two functions:
11015 \layout Verse
11016
11017
11018 \family typewriter
11019 volatile
11020 \begin_inset LatexCommand \index{volatile}
11021
11022 \end_inset
11023
11024  data unsigned char counter;
11025 \newline
11026
11027 \newline
11028 void simpleInterrupt(void) interrupt
11029 \begin_inset LatexCommand \index{interrupt}
11030
11031 \end_inset
11032
11033  1
11034 \newline
11035 {
11036 \newline
11037 \SpecialChar ~
11038 \SpecialChar ~
11039 \SpecialChar ~
11040 \SpecialChar ~
11041 counter++;
11042 \newline
11043 }
11044 \newline
11045
11046 \newline
11047 void nakedInterrupt(void) interrupt 2 _naked
11048 \newline
11049 {
11050 \newline
11051 \SpecialChar ~
11052 \SpecialChar ~
11053 \SpecialChar ~
11054 \SpecialChar ~
11055 _asm
11056 \begin_inset LatexCommand \index{\_asm}
11057
11058 \end_inset
11059
11060
11061 \newline
11062 \SpecialChar ~
11063 \SpecialChar ~
11064 \SpecialChar ~
11065 \SpecialChar ~
11066 \SpecialChar ~
11067 \SpecialChar ~
11068 inc\SpecialChar ~
11069 \SpecialChar ~
11070 \SpecialChar ~
11071 \SpecialChar ~
11072 \SpecialChar ~
11073 _counter ; does not change flags, no need to save psw
11074 \newline
11075 \SpecialChar ~
11076 \SpecialChar ~
11077 \SpecialChar ~
11078 \SpecialChar ~
11079 \SpecialChar ~
11080 \SpecialChar ~
11081 reti\SpecialChar ~
11082 \SpecialChar ~
11083 \SpecialChar ~
11084 \SpecialChar ~
11085 ; MUST explicitly include ret or reti in _naked function.
11086 \newline
11087 \SpecialChar ~
11088 \SpecialChar ~
11089 \SpecialChar ~
11090 \SpecialChar ~
11091 _endasm
11092 \begin_inset LatexCommand \index{\_endasm}
11093
11094 \end_inset
11095
11096 ;
11097 \newline
11098 }
11099 \layout Standard
11100
11101 For an 8051 target, the generated simpleInterrupt looks like:
11102 \layout Verse
11103
11104
11105 \family typewriter
11106 _simpleInterrupt:
11107 \newline
11108 \SpecialChar ~
11109 \SpecialChar ~
11110 \SpecialChar ~
11111 \SpecialChar ~
11112 push\SpecialChar ~
11113 \SpecialChar ~
11114 \SpecialChar ~
11115 \SpecialChar ~
11116 acc
11117 \newline
11118 \SpecialChar ~
11119 \SpecialChar ~
11120 \SpecialChar ~
11121 \SpecialChar ~
11122 push\SpecialChar ~
11123 \SpecialChar ~
11124 \SpecialChar ~
11125 \SpecialChar ~
11126 b
11127 \newline
11128 \SpecialChar ~
11129 \SpecialChar ~
11130 \SpecialChar ~
11131 \SpecialChar ~
11132 push\SpecialChar ~
11133 \SpecialChar ~
11134 \SpecialChar ~
11135 \SpecialChar ~
11136 dpl
11137 \newline
11138 \SpecialChar ~
11139 \SpecialChar ~
11140 \SpecialChar ~
11141 \SpecialChar ~
11142 push\SpecialChar ~
11143 \SpecialChar ~
11144 \SpecialChar ~
11145 \SpecialChar ~
11146 dph
11147 \newline
11148 \SpecialChar ~
11149 \SpecialChar ~
11150 \SpecialChar ~
11151 \SpecialChar ~
11152 push\SpecialChar ~
11153 \SpecialChar ~
11154 \SpecialChar ~
11155 \SpecialChar ~
11156 psw
11157 \newline
11158 \SpecialChar ~
11159 \SpecialChar ~
11160 \SpecialChar ~
11161 \SpecialChar ~
11162 mov\SpecialChar ~
11163 \SpecialChar ~
11164 \SpecialChar ~
11165 \SpecialChar ~
11166 \SpecialChar ~
11167 psw,#0x00
11168 \newline
11169 \SpecialChar ~
11170 \SpecialChar ~
11171 \SpecialChar ~
11172 \SpecialChar ~
11173 inc\SpecialChar ~
11174 \SpecialChar ~
11175 \SpecialChar ~
11176 \SpecialChar ~
11177 \SpecialChar ~
11178 _counter
11179 \newline
11180 \SpecialChar ~
11181 \SpecialChar ~
11182 \SpecialChar ~
11183 \SpecialChar ~
11184 pop\SpecialChar ~
11185 \SpecialChar ~
11186 \SpecialChar ~
11187 \SpecialChar ~
11188 \SpecialChar ~
11189 psw
11190 \newline
11191 \SpecialChar ~
11192 \SpecialChar ~
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 pop\SpecialChar ~
11196 \SpecialChar ~
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 \SpecialChar ~
11200 dph
11201 \newline
11202 \SpecialChar ~
11203 \SpecialChar ~
11204 \SpecialChar ~
11205 \SpecialChar ~
11206 pop\SpecialChar ~
11207 \SpecialChar ~
11208 \SpecialChar ~
11209 \SpecialChar ~
11210 \SpecialChar ~
11211 dpl
11212 \newline
11213 \SpecialChar ~
11214 \SpecialChar ~
11215 \SpecialChar ~
11216 \SpecialChar ~
11217 pop\SpecialChar ~
11218 \SpecialChar ~
11219 \SpecialChar ~
11220 \SpecialChar ~
11221 \SpecialChar ~
11222 b
11223 \newline
11224 \SpecialChar ~
11225 \SpecialChar ~
11226 \SpecialChar ~
11227 \SpecialChar ~
11228 pop\SpecialChar ~
11229 \SpecialChar ~
11230 \SpecialChar ~
11231 \SpecialChar ~
11232 \SpecialChar ~
11233 acc
11234 \newline
11235 \SpecialChar ~
11236 \SpecialChar ~
11237 \SpecialChar ~
11238 \SpecialChar ~
11239 reti
11240 \layout Standard
11241
11242 whereas nakedInterrupt looks like:
11243 \layout Verse
11244
11245
11246 \family typewriter
11247 _nakedInterrupt:
11248 \newline
11249 \SpecialChar ~
11250 \SpecialChar ~
11251 \SpecialChar ~
11252 \SpecialChar ~
11253 inc\SpecialChar ~
11254 \SpecialChar ~
11255 \SpecialChar ~
11256 \SpecialChar ~
11257 _counter ; does not change flags, no need to save psw
11258 \newline
11259 \SpecialChar ~
11260 \SpecialChar ~
11261 \SpecialChar ~
11262 \SpecialChar ~
11263 reti\SpecialChar ~
11264 \SpecialChar ~
11265 \SpecialChar ~
11266 \SpecialChar ~
11267 \SpecialChar ~
11268 \SpecialChar ~
11269 \SpecialChar ~
11270 \SpecialChar ~
11271 \SpecialChar ~
11272 \SpecialChar ~
11273 \SpecialChar ~
11274 \SpecialChar ~
11275 ; MUST explicitly include ret or reti in _naked function
11276 \layout Standard
11277
11278 The related directive #pragma exclude
11279 \begin_inset LatexCommand \index{\#pragma exclude}
11280
11281 \end_inset
11282
11283  allows a more fine grained control over pushing & popping
11284 \begin_inset LatexCommand \index{push/pop}
11285
11286 \end_inset
11287
11288  the registers.
11289 \layout Standard
11290
11291 While there is nothing preventing you from writing C code inside a
11292 \family typewriter
11293 _naked
11294 \family default
11295  function, there are many ways to shoot yourself in the foot doing this,
11296  and it is recommended that you stick to inline assembler.
11297 \layout Subsection
11298
11299 Use of Labels within Inline Assembler
11300 \layout Standard
11301
11302 SDCC allows the use of in-line assembler with a few restrictions regarding
11303  labels.
11304  In older versions of the compiler all labels defined within inline assembler
11305  code
11306 \emph on
11307 had to be
11308 \emph default
11309  of the form
11310 \emph on
11311 nnnnn$
11312 \emph default
11313  where nnnn is a number less than 100 (which implies a limit of utmost 100
11314  inline assembler labels
11315 \emph on
11316 per function
11317 \emph default
11318 \noun on
11319 )
11320 \noun default
11321 .
11322
11323 \layout Verse
11324
11325
11326 \family typewriter
11327 _asm
11328 \begin_inset LatexCommand \index{\_asm}
11329
11330 \end_inset
11331
11332
11333 \newline
11334 \SpecialChar ~
11335 \SpecialChar ~
11336 \SpecialChar ~
11337 \SpecialChar ~
11338 mov\SpecialChar ~
11339 \SpecialChar ~
11340 \SpecialChar ~
11341 \SpecialChar ~
11342 \SpecialChar ~
11343 b,#10
11344 \newline
11345 00001$:
11346 \newline
11347 \SpecialChar ~
11348 \SpecialChar ~
11349 \SpecialChar ~
11350 \SpecialChar ~
11351 djnz\SpecialChar ~
11352 \SpecialChar ~
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 b,00001$
11356 \newline
11357 _endasm
11358 \begin_inset LatexCommand \index{\_endasm}
11359
11360 \end_inset
11361
11362  ;
11363 \layout Standard
11364
11365 Inline assembler code cannot reference any C-Labels, however it can reference
11366  labels
11367 \begin_inset LatexCommand \index{Labels}
11368
11369 \end_inset
11370
11371  defined by the inline assembler, e.g.:
11372 \layout Verse
11373
11374
11375 \family typewriter
11376 foo() {
11377 \newline
11378 \SpecialChar ~
11379 \SpecialChar ~
11380 \SpecialChar ~
11381 \SpecialChar ~
11382 /* some c code */
11383 \newline
11384 \SpecialChar ~
11385 \SpecialChar ~
11386 \SpecialChar ~
11387 \SpecialChar ~
11388 _asm
11389 \newline
11390 \SpecialChar ~
11391 \SpecialChar ~
11392 \SpecialChar ~
11393 \SpecialChar ~
11394 \SpecialChar ~
11395 \SpecialChar ~
11396 ; some assembler code
11397 \newline
11398 \SpecialChar ~
11399 \SpecialChar ~
11400 \SpecialChar ~
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 ljmp $0003
11405 \newline
11406 \SpecialChar ~
11407 \SpecialChar ~
11408 \SpecialChar ~
11409 \SpecialChar ~
11410 _endasm;
11411 \newline
11412 \SpecialChar ~
11413 \SpecialChar ~
11414 \SpecialChar ~
11415 \SpecialChar ~
11416 /* some more c code */
11417 \newline
11418 clabel:\SpecialChar ~
11419 \SpecialChar ~
11420 /* inline assembler cannot reference this label */
11421 \newline
11422 \SpecialChar ~
11423 \SpecialChar ~
11424 \SpecialChar ~
11425 \SpecialChar ~
11426 _asm
11427 \newline
11428 \SpecialChar ~
11429 \SpecialChar ~
11430 \SpecialChar ~
11431 \SpecialChar ~
11432 $0003: ;label (can be referenced by inline assembler only)
11433 \newline
11434 \SpecialChar ~
11435 \SpecialChar ~
11436 \SpecialChar ~
11437 \SpecialChar ~
11438 _endasm ;
11439 \newline
11440 \SpecialChar ~
11441 \SpecialChar ~
11442 \SpecialChar ~
11443 \SpecialChar ~
11444 /* some more c code */
11445 \newline
11446 }
11447 \layout Standard
11448
11449 In other words inline assembly code can access labels defined in inline
11450  assembly within the scope of the function.
11451  The same goes the other way, i.e.
11452  labels defines in inline assembly can not be accessed by C statements.
11453 \layout Section
11454
11455 Interfacing with Assembler Code
11456 \begin_inset LatexCommand \index{Assembler routines}
11457
11458 \end_inset
11459
11460
11461 \layout Subsection
11462
11463 Global Registers used for Parameter Passing
11464 \begin_inset LatexCommand \index{Parameter passing}
11465
11466 \end_inset
11467
11468
11469 \layout Standard
11470
11471 The compiler always uses the global registers
11472 \emph on
11473 DPL, DPH
11474 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
11475
11476 \end_inset
11477
11478
11479 \begin_inset LatexCommand \index{DPTR}
11480
11481 \end_inset
11482
11483 , B
11484 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
11485
11486 \end_inset
11487
11488
11489 \emph default
11490 and
11491 \emph on
11492  ACC
11493 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
11494
11495 \end_inset
11496
11497
11498 \emph default
11499  to pass the first parameter to a routine.
11500  The second parameter onwards is either allocated on the stack (for reentrant
11501  routines or if -
11502 \begin_inset ERT
11503 status Collapsed
11504
11505 \layout Standard
11506
11507 \backslash
11508 /
11509 \end_inset
11510
11511 -stack-auto is used) or in data / xdata memory (depending on the memory
11512  model).
11513
11514 \layout Subsection
11515
11516 Assembler Routine (non-reentrant)
11517 \layout Standard
11518
11519 In the following example
11520 \begin_inset LatexCommand \index{reentrant}
11521
11522 \end_inset
11523
11524
11525 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
11526
11527 \end_inset
11528
11529  the function c_func calls an assembler routine asm_func, which takes two
11530  parameters
11531 \begin_inset LatexCommand \index{function parameter}
11532
11533 \end_inset
11534
11535 .
11536 \layout Verse
11537
11538
11539 \family typewriter
11540 extern int asm_func(unsigned char, unsigned char);
11541 \newline
11542
11543 \newline
11544 int c_func (unsigned char i, unsigned char j)
11545 \newline
11546 {
11547 \newline
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 return asm_func(i,j);
11553 \newline
11554 }
11555 \newline
11556
11557 \newline
11558 int main()
11559 \newline
11560 {
11561 \newline
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 \SpecialChar ~
11566 return c_func(10,9);
11567 \newline
11568 }
11569 \layout Standard
11570
11571 The corresponding assembler function is:
11572 \layout Verse
11573
11574
11575 \family typewriter
11576 .globl _asm_func_PARM_2
11577 \newline
11578 \SpecialChar ~
11579 \SpecialChar ~
11580 \SpecialChar ~
11581 \SpecialChar ~
11582 \SpecialChar ~
11583 \SpecialChar ~
11584 \SpecialChar ~
11585 \SpecialChar ~
11586 .globl _asm_func
11587 \newline
11588 \SpecialChar ~
11589 \SpecialChar ~
11590 \SpecialChar ~
11591 \SpecialChar ~
11592 \SpecialChar ~
11593 \SpecialChar ~
11594 \SpecialChar ~
11595 \SpecialChar ~
11596 .area OSEG
11597 \newline
11598 _asm_func_PARM_2:
11599 \newline
11600 \SpecialChar ~
11601 \SpecialChar ~
11602 \SpecialChar ~
11603 \SpecialChar ~
11604 \SpecialChar ~
11605 \SpecialChar ~
11606 \SpecialChar ~
11607 \SpecialChar ~
11608 .ds    1
11609 \newline
11610 \SpecialChar ~
11611 \SpecialChar ~
11612 \SpecialChar ~
11613 \SpecialChar ~
11614 \SpecialChar ~
11615 \SpecialChar ~
11616 \SpecialChar ~
11617 \SpecialChar ~
11618 .area CSEG
11619 \newline
11620 _asm_func:
11621 \newline
11622 \SpecialChar ~
11623 \SpecialChar ~
11624 \SpecialChar ~
11625 \SpecialChar ~
11626 \SpecialChar ~
11627 \SpecialChar ~
11628 \SpecialChar ~
11629 \SpecialChar ~
11630 mov\SpecialChar ~
11631 \SpecialChar ~
11632 \SpecialChar ~
11633 \SpecialChar ~
11634 a,dpl
11635 \newline
11636 \SpecialChar ~
11637 \SpecialChar ~
11638 \SpecialChar ~
11639 \SpecialChar ~
11640 \SpecialChar ~
11641 \SpecialChar ~
11642 \SpecialChar ~
11643 \SpecialChar ~
11644 add\SpecialChar ~
11645 \SpecialChar ~
11646 \SpecialChar ~
11647 \SpecialChar ~
11648 a,_asm_func_PARM_2
11649 \newline
11650 \SpecialChar ~
11651 \SpecialChar ~
11652 \SpecialChar ~
11653 \SpecialChar ~
11654 \SpecialChar ~
11655 \SpecialChar ~
11656 \SpecialChar ~
11657 \SpecialChar ~
11658 mov\SpecialChar ~
11659 \SpecialChar ~
11660 \SpecialChar ~
11661 \SpecialChar ~
11662 dpl,a
11663 \newline
11664 \SpecialChar ~
11665 \SpecialChar ~
11666 \SpecialChar ~
11667 \SpecialChar ~
11668 \SpecialChar ~
11669 \SpecialChar ~
11670 \SpecialChar ~
11671 \SpecialChar ~
11672 mov\SpecialChar ~
11673 \SpecialChar ~
11674 \SpecialChar ~
11675 \SpecialChar ~
11676 dph
11677 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
11678
11679 \end_inset
11680
11681 ,#0x00
11682 \newline
11683 \SpecialChar ~
11684 \SpecialChar ~
11685 \SpecialChar ~
11686 \SpecialChar ~
11687 \SpecialChar ~
11688 \SpecialChar ~
11689 \SpecialChar ~
11690 \SpecialChar ~
11691 ret
11692 \layout Standard
11693
11694 Note here that the return values
11695 \begin_inset LatexCommand \index{return value}
11696
11697 \end_inset
11698
11699  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
11700  two byte values.
11701  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
11702 b' & 'acc' for four byte values.
11703 \layout Standard
11704
11705 The parameter naming convention is _<function_name>_PARM_<n>, where n is
11706  the parameter number starting from 1, and counting from the left.
11707  The first parameter is passed in
11708 \begin_inset Quotes eld
11709 \end_inset
11710
11711 dpl
11712 \begin_inset Quotes erd
11713 \end_inset
11714
11715  for a one byte parameter,
11716 \begin_inset Quotes eld
11717 \end_inset
11718
11719 dptr
11720 \begin_inset Quotes erd
11721 \end_inset
11722
11723  for two bytes,
11724 \begin_inset Quotes eld
11725 \end_inset
11726
11727 b,dptr
11728 \begin_inset Quotes erd
11729 \end_inset
11730
11731  for three bytes and
11732 \begin_inset Quotes eld
11733 \end_inset
11734
11735 acc,b,dptr
11736 \begin_inset Quotes erd
11737 \end_inset
11738
11739  for a four bytes parameter.
11740  The variable name for the second parameter will be _<function_name>_PARM_2.
11741 \newline
11742
11743 \newline
11744 Assemble the assembler routine with the following command:
11745 \newline
11746
11747 \newline
11748
11749 \family sans
11750 \series bold
11751 asx8051 -losg asmfunc.asm
11752 \newline
11753
11754 \newline
11755
11756 \family default
11757 \series default
11758 Then compile and link the assembler routine to the C source file with the
11759  following command:
11760 \newline
11761
11762 \newline
11763
11764 \family sans
11765 \series bold
11766 sdcc cfunc.c asmfunc.rel
11767 \layout Subsection
11768
11769 Assembler Routine (reentrant)
11770 \layout Standard
11771
11772 In this case
11773 \begin_inset LatexCommand \index{reentrant}
11774
11775 \end_inset
11776
11777
11778 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
11779
11780 \end_inset
11781
11782  the second parameter
11783 \begin_inset LatexCommand \index{function parameter}
11784
11785 \end_inset
11786
11787  onwards will be passed on the stack, the parameters are pushed from right
11788  to left i.e.
11789  after the call the leftmost parameter will be on the top of the stack.
11790  Here is an example:
11791 \layout Verse
11792
11793
11794 \family typewriter
11795 extern int asm_func(unsigned char, unsigned char);
11796 \newline
11797
11798 \newline
11799 int c_func (unsigned char i, unsigned char j) reentrant
11800 \newline
11801 {
11802 \newline
11803 \SpecialChar ~
11804 \SpecialChar ~
11805 \SpecialChar ~
11806 \SpecialChar ~
11807 return asm_func(i,j);
11808 \newline
11809 }
11810 \newline
11811
11812 \newline
11813 int main()
11814 \newline
11815 {
11816 \newline
11817 \SpecialChar ~
11818 \SpecialChar ~
11819 \SpecialChar ~
11820 \SpecialChar ~
11821 return c_func(10,9);
11822 \newline
11823 }
11824 \layout Standard
11825
11826 The corresponding assembler routine is:
11827 \layout Verse
11828
11829
11830 \family typewriter
11831 .globl _asm_func
11832 \newline
11833 _asm_func:
11834 \newline
11835 \SpecialChar ~
11836 \SpecialChar ~
11837 \SpecialChar ~
11838 \SpecialChar ~
11839 push  _bp
11840 \newline
11841 \SpecialChar ~
11842 \SpecialChar ~
11843 \SpecialChar ~
11844 \SpecialChar ~
11845 mov _bp,sp
11846 \newline
11847 \SpecialChar ~
11848 \SpecialChar ~
11849 \SpecialChar ~
11850 \SpecialChar ~
11851 mov r2,dpl
11852 \newline
11853 \SpecialChar ~
11854 \SpecialChar ~
11855 \SpecialChar ~
11856 \SpecialChar ~
11857 mov a,_bp
11858 \newline
11859 \SpecialChar ~
11860 \SpecialChar ~
11861 \SpecialChar ~
11862 \SpecialChar ~
11863 add a,#0xfd
11864 \newline
11865 \SpecialChar ~
11866 \SpecialChar ~
11867 \SpecialChar ~
11868 \SpecialChar ~
11869 mov r0,a
11870 \newline
11871 \SpecialChar ~
11872 \SpecialChar ~
11873 \SpecialChar ~
11874 \SpecialChar ~
11875 add  a,#0xfc ;?
11876 \newline
11877 \SpecialChar ~
11878 \SpecialChar ~
11879 \SpecialChar ~
11880 \SpecialChar ~
11881 mov  r1,a
11882 \newline
11883 \SpecialChar ~
11884 \SpecialChar ~
11885 \SpecialChar ~
11886 \SpecialChar ~
11887 mov  a,@r0
11888 \newline
11889 \SpecialChar ~
11890 \SpecialChar ~
11891 \SpecialChar ~
11892 \SpecialChar ~
11893 add  a,r2 ;?
11894 \newline
11895 \SpecialChar ~
11896 \SpecialChar ~
11897 \SpecialChar ~
11898 \SpecialChar ~
11899 mov  dpl,a
11900 \newline
11901 \SpecialChar ~
11902 \SpecialChar ~
11903 \SpecialChar ~
11904 \SpecialChar ~
11905 mov  dph,#0x00
11906 \newline
11907 \SpecialChar ~
11908 \SpecialChar ~
11909 \SpecialChar ~
11910 \SpecialChar ~
11911 mov  sp,_bp
11912 \newline
11913 \SpecialChar ~
11914 \SpecialChar ~
11915 \SpecialChar ~
11916 \SpecialChar ~
11917 pop  _bp
11918 \newline
11919 \SpecialChar ~
11920 \SpecialChar ~
11921 \SpecialChar ~
11922 \SpecialChar ~
11923 ret
11924 \layout Standard
11925
11926 The compiling and linking procedure remains the same, however note the extra
11927  entry & exit linkage required for the assembler code, _bp is the stack
11928  frame pointer and is used to compute the offset into the stack for parameters
11929  and local variables.
11930 \layout Section
11931
11932 int (16 bit)
11933 \begin_inset LatexCommand \index{int (16 bit)}
11934
11935 \end_inset
11936
11937  and long (32 bit)
11938 \begin_inset LatexCommand \index{long (32 bit)}
11939
11940 \end_inset
11941
11942  Support
11943 \layout Standard
11944
11945 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
11946  multiplication and modulus operations are implemented by support routines.
11947  These support routines are all developed in ANSI-C to facilitate porting
11948  to other MCUs, although some model specific assembler optimizations are
11949  used.
11950  The following files contain the described routines, all of them can be
11951  found in <installdir>/share/sdcc/lib.
11952 \newline
11953
11954 \layout Standard
11955 \align center
11956
11957 \begin_inset  Tabular
11958 <lyxtabular version="3" rows="11" columns="2">
11959 <features>
11960 <column alignment="center" valignment="top" leftline="true" width="0">
11961 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
11962 <row topline="true" bottomline="true">
11963 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
11964 \begin_inset Text
11965
11966 \layout Standard
11967
11968
11969 \series bold
11970 Function
11971 \end_inset
11972 </cell>
11973 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
11974 \begin_inset Text
11975
11976 \layout Standard
11977
11978
11979 \series bold
11980 Description
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 _mulint.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 16 bit multiplication
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 _divsint.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  signed 16 bit division (calls _divuint)
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 _divuint.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  unsigned 16 bit division
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 _modsint.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 signed 16 bit modulus (calls _moduint)
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 _moduint.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 unsigned 16 bit modulus
12071 \end_inset
12072 </cell>
12073 </row>
12074 <row topline="true">
12075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12076 \begin_inset Text
12077
12078 \layout Standard
12079
12080 _mullong.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 32 bit multiplication
12089 \end_inset
12090 </cell>
12091 </row>
12092 <row topline="true">
12093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12094 \begin_inset Text
12095
12096 \layout Standard
12097
12098 _divslong.c
12099 \end_inset
12100 </cell>
12101 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12102 \begin_inset Text
12103
12104 \layout Standard
12105
12106  signed 32 division (calls _divulong)
12107 \end_inset
12108 </cell>
12109 </row>
12110 <row topline="true">
12111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12112 \begin_inset Text
12113
12114 \layout Standard
12115
12116 _divulong.c
12117 \end_inset
12118 </cell>
12119 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12120 \begin_inset Text
12121
12122 \layout Standard
12123
12124 unsigned 32 division
12125 \end_inset
12126 </cell>
12127 </row>
12128 <row topline="true">
12129 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12130 \begin_inset Text
12131
12132 \layout Standard
12133
12134 _modslong.c
12135 \end_inset
12136 </cell>
12137 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12138 \begin_inset Text
12139
12140 \layout Standard
12141
12142  signed 32 bit modulus (calls _modulong)
12143 \end_inset
12144 </cell>
12145 </row>
12146 <row topline="true" bottomline="true">
12147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12148 \begin_inset Text
12149
12150 \layout Standard
12151
12152 _modulong.c
12153 \end_inset
12154 </cell>
12155 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12156 \begin_inset Text
12157
12158 \layout Standard
12159
12160 unsigned 32 bit modulus
12161 \end_inset
12162 </cell>
12163 </row>
12164 </lyxtabular>
12165
12166 \end_inset
12167
12168
12169 \newline
12170
12171 \layout Standard
12172
12173 Since they are compiled as
12174 \emph on
12175 non-reentrant
12176 \emph default
12177
12178 \begin_inset LatexCommand \index{reentrant}
12179
12180 \end_inset
12181
12182 , interrupt
12183 \begin_inset LatexCommand \index{interrupt}
12184
12185 \end_inset
12186
12187  service routines should not do any of the above operations.
12188  If this is unavoidable then the above routines will need to be compiled
12189  with the
12190 \emph on
12191 -
12192 \begin_inset ERT
12193 status Collapsed
12194
12195 \layout Standard
12196
12197 \backslash
12198 /
12199 \end_inset
12200
12201 -stack-auto
12202 \begin_inset LatexCommand \index{-\/-stack-auto}
12203
12204 \end_inset
12205
12206
12207 \emph default
12208  option, after which the source program will have to be compiled with
12209 \emph on
12210 -
12211 \begin_inset ERT
12212 status Collapsed
12213
12214 \layout Standard
12215
12216 \backslash
12217 /
12218 \end_inset
12219
12220 -int-long-reent
12221 \begin_inset LatexCommand \index{-\/-int-long-reent}
12222
12223 \end_inset
12224
12225
12226 \emph default
12227  option.
12228  Notice that you don't have to call these routines directly.
12229  The compiler will use them automatically every time an integer operation
12230  is required.
12231 \layout Section
12232
12233 Floating Point Support
12234 \begin_inset LatexCommand \index{Floating point support}
12235
12236 \end_inset
12237
12238
12239 \layout Standard
12240
12241 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
12242  floating point support routines are derived from gcc's floatlib.c and consist
12243  of the following routines:
12244 \newline
12245
12246 \layout Standard
12247 \align center
12248
12249 \size footnotesize
12250
12251 \begin_inset  Tabular
12252 <lyxtabular version="3" rows="17" columns="2">
12253 <features>
12254 <column alignment="center" valignment="top" leftline="true" width="0">
12255 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12256 <row topline="true" bottomline="true">
12257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12258 \begin_inset Text
12259
12260 \layout Standard
12261
12262
12263 \family roman
12264 \series medium
12265 \shape up
12266 \size normal
12267 \emph off
12268 \bar no
12269 \noun off
12270 \color none
12271 Function
12272 \end_inset
12273 </cell>
12274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12275 \begin_inset Text
12276
12277 \layout Standard
12278
12279 Description
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 _fsadd.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 add 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 _fssub.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 subtract 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 _fsdiv.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 divide floating point numbers
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 _fsmul.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 multiply floating point numbers
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 _fs2uchar.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 char
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 _fs2char.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 char
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 _fs2uint.c
12515 \end_inset
12516 </cell>
12517 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12518 \begin_inset Text
12519
12520 \layout Standard
12521
12522
12523 \family roman
12524 \series medium
12525 \shape up
12526 \size normal
12527 \emph off
12528 \bar no
12529 \noun off
12530 \color none
12531 convert floating point to unsigned int
12532 \end_inset
12533 </cell>
12534 </row>
12535 <row topline="true">
12536 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12537 \begin_inset Text
12538
12539 \layout Standard
12540
12541
12542 \family roman
12543 \series medium
12544 \shape up
12545 \size normal
12546 \emph off
12547 \bar no
12548 \noun off
12549 \color none
12550 _fs2int.c
12551 \end_inset
12552 </cell>
12553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12554 \begin_inset Text
12555
12556 \layout Standard
12557
12558
12559 \family roman
12560 \series medium
12561 \shape up
12562 \size normal
12563 \emph off
12564 \bar no
12565 \noun off
12566 \color none
12567 convert floating point to signed int
12568 \end_inset
12569 </cell>
12570 </row>
12571 <row topline="true">
12572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12573 \begin_inset Text
12574
12575 \layout Standard
12576
12577
12578 \family roman
12579 \series medium
12580 \shape up
12581 \size normal
12582 \emph off
12583 \bar no
12584 \noun off
12585 \color none
12586 _fs2ulong.
12587 \family default
12588 \series default
12589 \shape default
12590 \size default
12591 \emph default
12592 \bar default
12593 \noun default
12594 \color default
12595 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 floating point to unsigned long
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 _fs2long.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 floating point to signed long
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 _uchar2fs.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 char 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 _char2fs.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 char to floating point number
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 _uint2fs.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 int to floating point
12757 \end_inset
12758 </cell>
12759 </row>
12760 <row topline="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 _int2fs.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 int to floating point numbers
12793 \end_inset
12794 </cell>
12795 </row>
12796 <row topline="true">
12797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12798 \begin_inset Text
12799
12800 \layout Standard
12801
12802
12803 \family roman
12804 \series medium
12805 \shape up
12806 \size normal
12807 \emph off
12808 \bar no
12809 \noun off
12810 \color none
12811 _ulong2fs.c
12812 \end_inset
12813 </cell>
12814 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12815 \begin_inset Text
12816
12817 \layout Standard
12818
12819
12820 \family roman
12821 \series medium
12822 \shape up
12823 \size normal
12824 \emph off
12825 \bar no
12826 \noun off
12827 \color none
12828 convert unsigned long to floating point number
12829 \end_inset
12830 </cell>
12831 </row>
12832 <row topline="true" bottomline="true">
12833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12834 \begin_inset Text
12835
12836 \layout Standard
12837
12838
12839 \family roman
12840 \series medium
12841 \shape up
12842 \size normal
12843 \emph off
12844 \bar no
12845 \noun off
12846 \color none
12847 _long2fs.c
12848 \end_inset
12849 </cell>
12850 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12851 \begin_inset Text
12852
12853 \layout Standard
12854
12855
12856 \family roman
12857 \series medium
12858 \shape up
12859 \size normal
12860 \emph off
12861 \bar no
12862 \noun off
12863 \color none
12864 convert long to floating point number
12865 \end_inset
12866 </cell>
12867 </row>
12868 </lyxtabular>
12869
12870 \end_inset
12871
12872
12873 \newline
12874
12875 \layout Standard
12876
12877 These support routines are developed in ANSI-C so there is room for space
12878  and speed improvement.
12879  Note if all these routines are used simultaneously the data space might
12880  overflow.
12881  For serious floating point usage it is recommended that the large model
12882  be used.
12883  Also notice that you don't have to call this routines directly.
12884  The compiler will use them automatically every time a floating point operation
12885  is required.
12886 \layout Section
12887
12888 Library Routines
12889 \begin_inset LatexCommand \index{Libraries}
12890
12891 \end_inset
12892
12893
12894 \layout Standard
12895
12896
12897 \emph on
12898 <pending: this is messy and incomplete - a little more information is in
12899  sdcc/doc/libdoc.txt
12900 \emph default
12901  >
12902 \layout Subsection
12903
12904 Compiler support routines (_gptrget, _mulint etc.)
12905 \layout Subsection
12906
12907 Stdclib functions (puts, printf, strcat etc.)
12908 \layout Subsubsection
12909
12910 <stdio.h>
12911 \layout Standard
12912
12913
12914 \begin_inset LatexCommand \index{<stdio.h>}
12915
12916 \end_inset
12917
12918 As usual on embedded systems you have to provide your own
12919 \family typewriter
12920 getchar()
12921 \begin_inset LatexCommand \index{getchar()}
12922
12923 \end_inset
12924
12925
12926 \family default
12927 and
12928 \family typewriter
12929 putchar()
12930 \begin_inset LatexCommand \index{putchar()}
12931
12932 \end_inset
12933
12934
12935 \family default
12936  routines.
12937  SDCC does not know whether the system connects to a serial line with or
12938  without handshake, LCD, keyboard or other device.
12939  You'll find examples for serial routines f.e.
12940  in sdcc/device/lib.
12941 \layout Standard
12942
12943 If you're short on memory you might want to use
12944 \family typewriter
12945 printf_small()
12946 \family default
12947
12948 \emph on
12949 instead
12950 \emph default
12951  of
12952 \family typewriter
12953  printf()
12954 \begin_inset LatexCommand \index{printf()}
12955
12956 \end_inset
12957
12958 .
12959
12960 \family default
12961  For the mcs51 there is an assembly version
12962 \family typewriter
12963 printf_fast()
12964 \family default
12965  which should fit the requirements of many embedded systems (by unsetting
12966  #defines it can be customized to
12967 \emph on
12968 not
12969 \emph default
12970  support long variables and field widths).
12971 \layout Subsection
12972
12973 Math functions (sin, pow, sqrt etc.)
12974 \layout Subsection
12975
12976 Other libraries
12977 \layout Standard
12978
12979 Libraries
12980 \begin_inset LatexCommand \index{Libraries}
12981
12982 \end_inset
12983
12984  included in SDCC should have a license at least as liberal as the GNU Lesser
12985  General Public License
12986 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
12987
12988 \end_inset
12989
12990
12991 \emph on
12992 LGPL
12993 \emph default
12994 .
12995 \layout Comment
12996
12997 license statements for the libraries are missing.
12998  sdcc/device/lib/ser_ir.c
12999 \layout Comment
13000
13001 or _decdptr f.e.
13002  come with a GPL (as opposed to LGPL) License - this will not be liberal
13003  enough for many embedded programmers.
13004 \layout Standard
13005
13006 If you have ported some library or want to share experience about some code
13007  which f.e.
13008  falls into any of these categories Busses (I
13009 \begin_inset Formula $^{\textrm{2}}$
13010 \end_inset
13011
13012 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
13013  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
13014  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
13015 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
13016
13017 \end_inset
13018
13019 \SpecialChar ~
13020 would certainly like to hear about it.
13021  Programmers coding for embedded systems are not especially famous for being
13022  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
13023 e these references are very valuable.
13024  Let's help to create a climate where information is shared.
13025 \layout Section
13026
13027 Memory Models
13028 \layout Subsection
13029
13030 MCS51 Memory Models
13031 \begin_inset LatexCommand \index{Memory model}
13032
13033 \end_inset
13034
13035
13036 \begin_inset LatexCommand \index{MCS51 memory model}
13037
13038 \end_inset
13039
13040
13041 \layout Subsubsection
13042
13043 Small and Large
13044 \layout Standard
13045
13046 SDCC allows two memory models for MCS51 code,
13047 \shape slanted
13048 small
13049 \shape default
13050  and
13051 \shape slanted
13052 large
13053 \shape default
13054 .
13055  Modules compiled with different memory models should
13056 \emph on
13057 never
13058 \emph default
13059  be combined together or the results would be unpredictable.
13060  The library routines supplied with the compiler are compiled as both small
13061  and large.
13062  The compiled library modules are contained in separate directories as small
13063  and large so that you can link to either set.
13064
13065 \layout Standard
13066
13067 When the large model is used all variables declared without a storage class
13068  will be allocated into the external ram, this includes all parameters and
13069  local variables (for non-reentrant
13070 \begin_inset LatexCommand \index{reentrant}
13071
13072 \end_inset
13073
13074  functions).
13075  When the small model is used variables without storage class are allocated
13076  in the internal ram.
13077 \layout Standard
13078
13079 Judicious usage of the processor specific storage classes
13080 \begin_inset LatexCommand \index{Storage class}
13081
13082 \end_inset
13083
13084  and the 'reentrant' function type will yield much more efficient code,
13085  than using the large model.
13086  Several optimizations are disabled when the program is compiled using the
13087  large model, it is therefore recommended that the small model be used unless
13088  absolutely required.
13089 \layout Subsubsection
13090
13091 External Stack
13092 \begin_inset LatexCommand \label{sub:External-Stack}
13093
13094 \end_inset
13095
13096
13097 \begin_inset LatexCommand \index{stack}
13098
13099 \end_inset
13100
13101
13102 \begin_inset LatexCommand \index{External stack (mcs51)}
13103
13104 \end_inset
13105
13106
13107 \layout Standard
13108
13109 The external stack (-
13110 \begin_inset ERT
13111 status Collapsed
13112
13113 \layout Standard
13114
13115 \backslash
13116 /
13117 \end_inset
13118
13119 -xstack option
13120 \begin_inset LatexCommand \index{-\/-xstack}
13121
13122 \end_inset
13123
13124 ) is located in pdata
13125 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
13126
13127 \end_inset
13128
13129  memory (usually at the start of the external ram segment) and is 256 bytes
13130  in size.
13131  When -
13132 \begin_inset ERT
13133 status Collapsed
13134
13135 \layout Standard
13136
13137 \backslash
13138 /
13139 \end_inset
13140
13141 -xstack option is used to compile the program, the parameters and local
13142  variables
13143 \begin_inset LatexCommand \index{local variables}
13144
13145 \end_inset
13146
13147  of all reentrant functions are allocated in this area.
13148  This option is provided for programs with large stack space requirements.
13149  When used with the -
13150 \begin_inset ERT
13151 status Collapsed
13152
13153 \layout Standard
13154
13155 \backslash
13156 /
13157 \end_inset
13158
13159 -stack-auto
13160 \begin_inset LatexCommand \index{-\/-stack-auto}
13161
13162 \end_inset
13163
13164  option, all parameters and local variables are allocated on the external
13165  stack (note: support libraries will need to be recompiled with the same
13166  options).
13167 \layout Standard
13168
13169 The compiler outputs the higher order address byte of the external ram segment
13170  into port P2
13171 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
13172
13173 \end_inset
13174
13175  (see also section
13176 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13177
13178 \end_inset
13179
13180 ), therefore when using the External Stack option, this port
13181 \emph on
13182 may not
13183 \emph default
13184  be used by the application program.
13185 \layout Subsection
13186
13187 DS390 Memory Model
13188 \begin_inset LatexCommand \index{Memory model}
13189
13190 \end_inset
13191
13192
13193 \begin_inset LatexCommand \index{DS390 memory model}
13194
13195 \end_inset
13196
13197
13198 \layout Standard
13199
13200 The only model supported is Flat 24
13201 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
13202
13203 \end_inset
13204
13205 .
13206  This generates code for the 24 bit contiguous addressing mode of the Dallas
13207  DS80C390 part.
13208  In this mode, up to four meg of external RAM or code space can be directly
13209  addressed.
13210  See the data sheets at www.dalsemi.com for further information on this part.
13211 \newline
13212
13213 \newline
13214 Note that the compiler does not generate any code to place the processor
13215  into 24 bitmode (although
13216 \emph on
13217 tinibios
13218 \emph default
13219  in the ds390 libraries will do that for you).
13220  If you don't use
13221 \emph on
13222 tinibios
13223 \emph default
13224
13225 \begin_inset LatexCommand \index{Tinibios (DS390)}
13226
13227 \end_inset
13228
13229 , the boot loader or similar code must ensure that the processor is in 24
13230  bit contiguous addressing mode before calling the SDCC startup code.
13231 \newline
13232
13233 \newline
13234 Like the
13235 \emph on
13236 -
13237 \begin_inset ERT
13238 status Collapsed
13239
13240 \layout Standard
13241
13242 \backslash
13243 /
13244 \end_inset
13245
13246 -model-large
13247 \emph default
13248  option, variables will by default be placed into the XDATA segment.
13249
13250 \newline
13251
13252 \newline
13253 Segments may be placed anywhere in the 4 meg address space using the usual
13254  -
13255 \begin_inset ERT
13256 status Collapsed
13257
13258 \layout Standard
13259
13260 \backslash
13261 /
13262 \end_inset
13263
13264 -*-loc options.
13265  Note that if any segments are located above 64K, the -r flag must be passed
13266  to the linker to generate the proper segment relocations, and the Intel
13267  HEX output format must be used.
13268  The -r flag can be passed to the linker by using the option
13269 \emph on
13270 -Wl-r
13271 \emph default
13272  on the SDCC command line.
13273  However, currently the linker can not handle code segments > 64k.
13274 \layout Section
13275
13276 Pragmas
13277 \begin_inset LatexCommand \index{Pragmas}
13278
13279 \end_inset
13280
13281
13282 \layout Standard
13283
13284 SDCC supports the following #pragma directives:
13285 \layout Itemize
13286
13287 save
13288 \begin_inset LatexCommand \index{\#pragma save}
13289
13290 \end_inset
13291
13292  - this will save all current options to the save/restore stack.
13293  See restore.
13294 \layout Itemize
13295
13296 restore
13297 \begin_inset LatexCommand \index{\#pragma restore}
13298
13299 \end_inset
13300
13301  - will restore saved options from the last save.
13302  saves & restores can be nested.
13303  SDCC uses a save/restore stack: save pushes current options to the stack,
13304  restore pulls current options from the stack.
13305  See save.
13306 \layout Itemize
13307
13308 nogcse
13309 \begin_inset LatexCommand \index{\#pragma nogcse}
13310
13311 \end_inset
13312
13313  - will stop global common subexpression elimination.
13314 \layout Itemize
13315
13316 noinduction
13317 \begin_inset LatexCommand \index{\#pragma noinduction}
13318
13319 \end_inset
13320
13321  - will stop loop induction optimizations.
13322 \layout Itemize
13323
13324 nojtbound
13325 \begin_inset LatexCommand \index{\#pragma nojtbound}
13326
13327 \end_inset
13328
13329  - will not generate code for boundary value checking, when switch statements
13330  are turned into jump-tables (dangerous).
13331  For more details see section
13332 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
13333
13334 \end_inset
13335
13336 .
13337 \layout Itemize
13338
13339 nooverlay
13340 \begin_inset LatexCommand \index{\#pragma nooverlay}
13341
13342 \end_inset
13343
13344  - the compiler will not overlay the parameters and local variables of a
13345  function.
13346 \layout Itemize
13347
13348 less_pedantic
13349 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
13350
13351 \end_inset
13352
13353  - the compiler will not warn you anymore for obvious mistakes, you'r on
13354  your own now ;-(
13355 \layout Itemize
13356
13357 noloopreverse
13358 \begin_inset LatexCommand \index{\#pragma noloopreverse}
13359
13360 \end_inset
13361
13362  - Will not do loop reversal optimization
13363 \layout Itemize
13364
13365 exclude
13366 \begin_inset LatexCommand \index{\#pragma exclude}
13367
13368 \end_inset
13369
13370  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
13371  pair of push/pop
13372 \begin_inset LatexCommand \index{push/pop}
13373
13374 \end_inset
13375
13376  instruction in ISR function (using interrupt
13377 \begin_inset LatexCommand \index{interrupt}
13378
13379 \end_inset
13380
13381  keyword).
13382  The directive should be placed immediately before the ISR function definition
13383  and it affects ALL ISR functions following it.
13384  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
13385 exclude\SpecialChar ~
13386 none
13387 \begin_inset LatexCommand \index{\#pragma exclude}
13388
13389 \end_inset
13390
13391 .
13392 \layout Itemize
13393
13394 noiv
13395 \begin_inset LatexCommand \index{\#pragma noiv}
13396
13397 \end_inset
13398
13399  - Do not generate interrupt
13400 \begin_inset LatexCommand \index{interrupt}
13401
13402 \end_inset
13403
13404  vector table entries for all ISR functions defined after the pragma.
13405  This is useful in cases where the interrupt vector table must be defined
13406  manually, or when there is a secondary, manually defined interrupt vector
13407  table (e.g.
13408  for the autovector feature of the Cypress EZ-USB FX2).
13409  More elegantly this can be achieved by obmitting the optional interrupt
13410  number after the interrupt keyword, see section
13411 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
13412
13413 \end_inset
13414
13415 \SpecialChar ~
13416 about interrupts.
13417 \layout Itemize
13418
13419 callee_saves
13420 \begin_inset LatexCommand \index{\#pragma callee\_saves}
13421
13422 \end_inset
13423
13424
13425 \begin_inset LatexCommand \index{function prologue}
13426
13427 \end_inset
13428
13429  function1[,function2[,function3...]] - The compiler by default uses a caller
13430  saves convention for register saving across function calls, however this
13431  can cause unnecessary register pushing & popping
13432 \begin_inset LatexCommand \index{push/pop}
13433
13434 \end_inset
13435
13436  when calling small functions from larger functions.
13437  This option can be used to switch off the register saving convention for
13438  the function names specified.
13439  The compiler will not save registers when calling these functions, extra
13440  code need to be manually inserted at the entry & exit for these functions
13441  to save & restore the registers used by these functions, this can SUBSTANTIALLY
13442  reduce code & improve run time performance of the generated code.
13443  In the future the compiler (with inter procedural analysis) may be able
13444  to determine the appropriate scheme to use for each function call.
13445  If -
13446 \begin_inset ERT
13447 status Collapsed
13448
13449 \layout Standard
13450
13451 \backslash
13452 /
13453 \end_inset
13454
13455 -callee-saves command line option is used, the function names specified
13456  in #pragma\SpecialChar ~
13457 callee_saves
13458 \begin_inset LatexCommand \index{\#pragma callee\_saves}
13459
13460 \end_inset
13461
13462  is appended to the list of functions specified in the command line.
13463 \layout Standard
13464
13465 SDCPP supports the following #pragma directives:
13466 \layout Itemize
13467
13468 preproc_asm
13469 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
13470
13471 \end_inset
13472
13473  (+ | -) - switch _asm _endasm block preprocessing on / off.
13474  Default is on.
13475 \layout Standard
13476
13477 The pragma's are intended to be used to turn-on or off certain optimizations
13478  which might cause the compiler to generate extra stack / data space to
13479  store compiler generated temporary variables.
13480  This usually happens in large functions.
13481  Pragma directives should be used as shown in the following example, they
13482  are used to control options & optimizations for a given function; pragmas
13483  should be placed before and/or after a function, placing pragma's inside
13484  a function body could have unpredictable results.
13485 \layout Verse
13486
13487
13488 \family typewriter
13489 #pragma save
13490 \begin_inset LatexCommand \index{\#pragma save}
13491
13492 \end_inset
13493
13494  \SpecialChar ~
13495 \SpecialChar ~
13496 \SpecialChar ~
13497 \SpecialChar ~
13498 \SpecialChar ~
13499 \SpecialChar ~
13500 \SpecialChar ~
13501 /* save the current settings */
13502 \newline
13503 #pragma nogcse
13504 \begin_inset LatexCommand \index{\#pragma nogcse}
13505
13506 \end_inset
13507
13508  \SpecialChar ~
13509 \SpecialChar ~
13510 \SpecialChar ~
13511 \SpecialChar ~
13512 \SpecialChar ~
13513 /* turnoff global subexpression elimination */
13514 \newline
13515 #pragma noinduction
13516 \begin_inset LatexCommand \index{\#pragma noinduction}
13517
13518 \end_inset
13519
13520  /* turn off induction optimizations */
13521 \newline
13522 int foo ()
13523 \newline
13524 {
13525 \newline
13526 \SpecialChar ~
13527  \SpecialChar ~
13528  ...
13529
13530 \newline
13531 \SpecialChar ~
13532  \SpecialChar ~
13533  /* large code */
13534 \newline
13535 \SpecialChar ~
13536  \SpecialChar ~
13537  ...
13538
13539 \newline
13540 }
13541 \newline
13542 #pragma restore
13543 \begin_inset LatexCommand \index{\#pragma restore}
13544
13545 \end_inset
13546
13547  /* turn the optimizations back on */
13548 \layout Standard
13549
13550 The compiler will generate a warning message when extra space is allocated.
13551  It is strongly recommended that the save and restore pragma's be used when
13552  changing options for a function.
13553 \layout Section
13554
13555 Defines Created by the Compiler
13556 \layout Standard
13557
13558 The compiler creates the following #defines
13559 \begin_inset LatexCommand \index{\#defines}
13560
13561 \end_inset
13562
13563
13564 \begin_inset LatexCommand \index{Defines created by the compiler}
13565
13566 \end_inset
13567
13568 :
13569 \newline
13570
13571 \layout Standard
13572
13573
13574 \begin_inset  Tabular
13575 <lyxtabular version="3" rows="10" columns="2">
13576 <features>
13577 <column alignment="center" valignment="top" leftline="true" width="0">
13578 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13579 <row topline="true" bottomline="true">
13580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13581 \begin_inset Text
13582
13583 \layout Standard
13584
13585
13586 \series bold
13587 #define
13588 \end_inset
13589 </cell>
13590 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13591 \begin_inset Text
13592
13593 \layout Standard
13594
13595
13596 \series bold
13597 Description
13598 \end_inset
13599 </cell>
13600 </row>
13601 <row topline="true">
13602 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13603 \begin_inset Text
13604
13605 \layout Standard
13606
13607 SDCC
13608 \begin_inset LatexCommand \index{SDCC}
13609
13610 \end_inset
13611
13612
13613 \end_inset
13614 </cell>
13615 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13616 \begin_inset Text
13617
13618 \layout Standard
13619
13620 this Symbol is always defined
13621 \end_inset
13622 </cell>
13623 </row>
13624 <row topline="true">
13625 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13626 \begin_inset Text
13627
13628 \layout Standard
13629
13630 SDCC_mcs51
13631 \begin_inset LatexCommand \index{SDCC\_mcs51}
13632
13633 \end_inset
13634
13635  or SDCC_ds390
13636 \begin_inset LatexCommand \index{SDCC\_ds390}
13637
13638 \end_inset
13639
13640  or SDCC_z80
13641 \begin_inset LatexCommand \index{SDCC\_z80}
13642
13643 \end_inset
13644
13645 , etc
13646 \end_inset
13647 </cell>
13648 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13649 \begin_inset Text
13650
13651 \layout Standard
13652
13653 depending on the model used (e.g.: -mds390
13654 \end_inset
13655 </cell>
13656 </row>
13657 <row topline="true">
13658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13659 \begin_inset Text
13660
13661 \layout Standard
13662
13663 __mcs51
13664 \begin_inset LatexCommand \index{\_\_mcs51}
13665
13666 \end_inset
13667
13668 , __ds390
13669 \begin_inset LatexCommand \index{\_\_ds390}
13670
13671 \end_inset
13672
13673 , __hc08
13674 \begin_inset LatexCommand \index{\_\_hc08}
13675
13676 \end_inset
13677
13678 , __z80
13679 \begin_inset LatexCommand \index{\_\_z80}
13680
13681 \end_inset
13682
13683 , etc
13684 \end_inset
13685 </cell>
13686 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13687 \begin_inset Text
13688
13689 \layout Standard
13690
13691 depending on the model used (e.g.
13692  -mz80)
13693 \end_inset
13694 </cell>
13695 </row>
13696 <row topline="true">
13697 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13698 \begin_inset Text
13699
13700 \layout Standard
13701
13702 SDCC_STACK_AUTO
13703 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
13704
13705 \end_inset
13706
13707
13708 \end_inset
13709 </cell>
13710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13711 \begin_inset Text
13712
13713 \layout Standard
13714
13715 when
13716 \emph on
13717 -
13718 \begin_inset ERT
13719 status Collapsed
13720
13721 \layout Standard
13722
13723 \backslash
13724 /
13725 \end_inset
13726
13727 -stack-auto
13728 \emph default
13729  option is used
13730 \end_inset
13731 </cell>
13732 </row>
13733 <row topline="true">
13734 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13735 \begin_inset Text
13736
13737 \layout Standard
13738
13739 SDCC_MODEL_SMALL
13740 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
13741
13742 \end_inset
13743
13744
13745 \end_inset
13746 </cell>
13747 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13748 \begin_inset Text
13749
13750 \layout Standard
13751
13752 when
13753 \emph on
13754 -
13755 \begin_inset ERT
13756 status Collapsed
13757
13758 \layout Standard
13759
13760 \backslash
13761 /
13762 \end_inset
13763
13764 -model-small
13765 \emph default
13766  is used
13767 \end_inset
13768 </cell>
13769 </row>
13770 <row topline="true">
13771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13772 \begin_inset Text
13773
13774 \layout Standard
13775
13776 SDCC_MODEL_LARGE
13777 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
13778
13779 \end_inset
13780
13781
13782 \end_inset
13783 </cell>
13784 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13785 \begin_inset Text
13786
13787 \layout Standard
13788
13789 when
13790 \emph on
13791 -
13792 \begin_inset ERT
13793 status Collapsed
13794
13795 \layout Standard
13796
13797 \backslash
13798 /
13799 \end_inset
13800
13801 -model-large
13802 \emph default
13803  is used
13804 \end_inset
13805 </cell>
13806 </row>
13807 <row topline="true">
13808 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13809 \begin_inset Text
13810
13811 \layout Standard
13812
13813 SDCC_USE_XSTACK
13814 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
13815
13816 \end_inset
13817
13818
13819 \end_inset
13820 </cell>
13821 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13822 \begin_inset Text
13823
13824 \layout Standard
13825
13826 when
13827 \emph on
13828 -
13829 \begin_inset ERT
13830 status Collapsed
13831
13832 \layout Standard
13833
13834 \backslash
13835 /
13836 \end_inset
13837
13838 -xstack
13839 \emph default
13840  option is used
13841 \end_inset
13842 </cell>
13843 </row>
13844 <row topline="true">
13845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13846 \begin_inset Text
13847
13848 \layout Standard
13849
13850 SDCC_STACK_TENBIT
13851 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
13852
13853 \end_inset
13854
13855
13856 \end_inset
13857 </cell>
13858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13859 \begin_inset Text
13860
13861 \layout Standard
13862
13863 when
13864 \emph on
13865 -mds390
13866 \emph default
13867  is used
13868 \end_inset
13869 </cell>
13870 </row>
13871 <row topline="true" bottomline="true">
13872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13873 \begin_inset Text
13874
13875 \layout Standard
13876
13877 SDCC_MODEL_FLAT24
13878 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
13879
13880 \end_inset
13881
13882
13883 \end_inset
13884 </cell>
13885 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13886 \begin_inset Text
13887
13888 \layout Standard
13889
13890 when
13891 \emph on
13892 -mds390
13893 \emph default
13894  is used
13895 \end_inset
13896 </cell>
13897 </row>
13898 </lyxtabular>
13899
13900 \end_inset
13901
13902
13903 \newline
13904
13905 \layout Chapter
13906
13907 Debugging with SDCDB
13908 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
13909
13910 \end_inset
13911
13912
13913 \begin_inset LatexCommand \index{sdcdb (debugger)}
13914
13915 \end_inset
13916
13917
13918 \layout Standard
13919
13920 SDCC is distributed with a source level debugger
13921 \begin_inset LatexCommand \index{Debugger}
13922
13923 \end_inset
13924
13925 .
13926  The debugger uses a command line interface, the command repertoire of the
13927  debugger has been kept as close to gdb
13928 \begin_inset LatexCommand \index{gdb}
13929
13930 \end_inset
13931
13932  (the GNU debugger) as possible.
13933  The configuration and build process is part of the standard compiler installati
13934 on, which also builds and installs the debugger in the target directory
13935  specified during configuration.
13936  The debugger allows you debug BOTH at the C source and at the ASM source
13937  level.
13938  Sdcdb is available on Unix platforms only.
13939 \layout Section
13940
13941 Compiling for Debugging
13942 \layout Standard
13943
13944 The \SpecialChar \-
13945 \SpecialChar \-
13946 debug option must be specified for all files for which debug information
13947  is to be generated.
13948  The complier generates a .adb file for each of these files.
13949  The linker creates the .cdb file from the .adb files and the address information.
13950  This .cdb is used by the debugger.
13951 \layout Section
13952
13953 How the Debugger Works
13954 \layout Standard
13955
13956 When the -
13957 \begin_inset ERT
13958 status Collapsed
13959
13960 \layout Standard
13961
13962 \backslash
13963 /
13964 \end_inset
13965
13966 -debug option is specified the compiler generates extra symbol information
13967  some of which are put into the assembler source and some are put into the
13968  .adb file.
13969   Then the linker creates the .cdb file from the individual .adb files with
13970  the address information for the symbols.
13971  The debugger reads the symbolic information generated by the compiler &
13972  the address information generated by the linker.
13973  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
13974  execution is controlled by the debugger.
13975  When a command is issued for the debugger, it translates it into appropriate
13976  commands for the simulator.
13977 \layout Section
13978
13979 Starting the Debugger
13980 \layout Standard
13981
13982 The debugger can be started using the following command line.
13983  (Assume the file you are debugging has the file name foo).
13984 \newline
13985
13986 \newline
13987
13988 \family sans
13989 \series bold
13990 sdcdb foo
13991 \newline
13992
13993 \family default
13994 \series default
13995
13996 \newline
13997 The debugger will look for the following files.
13998 \layout Itemize
13999
14000 foo.c - the source file.
14001 \layout Itemize
14002
14003 foo.cdb - the debugger symbol information file.
14004 \layout Itemize
14005
14006 foo.ihx - the Intel hex format
14007 \begin_inset LatexCommand \index{Intel hex format}
14008
14009 \end_inset
14010
14011  object file.
14012 \layout Section
14013
14014 Command Line Options.
14015 \layout Itemize
14016
14017 -
14018 \begin_inset ERT
14019 status Collapsed
14020
14021 \layout Standard
14022
14023 \backslash
14024 /
14025 \end_inset
14026
14027 -directory=<source file directory> this option can used to specify the directory
14028  search list.
14029  The debugger will look into the directory list specified for source, cdb
14030  & ihx files.
14031  The items in the directory list must be separated by ':', e.g.
14032  if the source files can be in the directories /home/src1 and /home/src2,
14033  the -
14034 \begin_inset ERT
14035 status Collapsed
14036
14037 \layout Standard
14038
14039 \backslash
14040 /
14041 \end_inset
14042
14043 -directory option should be -
14044 \begin_inset ERT
14045 status Collapsed
14046
14047 \layout Standard
14048
14049 \backslash
14050 /
14051 \end_inset
14052
14053 -directory=/home/src1:/home/src2.
14054  Note there can be no spaces in the option.
14055
14056 \layout Itemize
14057
14058 -cd <directory> - change to the <directory>.
14059 \layout Itemize
14060
14061 -fullname - used by GUI front ends.
14062 \layout Itemize
14063
14064 -cpu <cpu-type> - this argument is passed to the simulator please see the
14065  simulator docs for details.
14066 \layout Itemize
14067
14068 -X <Clock frequency > this options is passed to the simulator please see
14069  the simulator docs for details.
14070 \layout Itemize
14071
14072 -s <serial port file> passed to simulator see the simulator docs for details.
14073 \layout Itemize
14074
14075 -S <serial in,out> passed to simulator see the simulator docs for details.
14076 \layout Itemize
14077
14078 -k <port number> passed to simulator see the simulator docs for details.
14079 \layout Section
14080
14081 Debugger Commands.
14082 \layout Standard
14083
14084 As mentioned earlier the command interface for the debugger has been deliberatel
14085 y kept as close the GNU debugger gdb, as possible.
14086  This will help the integration with existing graphical user interfaces
14087  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
14088  If you use a graphical user interface for the debugger you can skip the
14089  next sections.
14090 \layout Subsubsection*
14091
14092 break [line | file:line | function | file:function]
14093 \layout Standard
14094
14095 Set breakpoint at specified line or function:
14096 \newline
14097
14098 \newline
14099
14100 \family sans
14101 \series bold
14102 sdcdb>break 100
14103 \newline
14104 sdcdb>break foo.c:100
14105 \newline
14106 sdcdb>break funcfoo
14107 \newline
14108 sdcdb>break foo.c:funcfoo
14109 \layout Subsubsection*
14110
14111 clear [line | file:line | function | file:function ]
14112 \layout Standard
14113
14114 Clear breakpoint at specified line or function:
14115 \newline
14116
14117 \newline
14118
14119 \family sans
14120 \series bold
14121 sdcdb>clear 100
14122 \newline
14123 sdcdb>clear foo.c:100
14124 \newline
14125 sdcdb>clear funcfoo
14126 \newline
14127 sdcdb>clear foo.c:funcfoo
14128 \layout Subsubsection*
14129
14130 continue
14131 \layout Standard
14132
14133 Continue program being debugged, after breakpoint.
14134 \layout Subsubsection*
14135
14136 finish
14137 \layout Standard
14138
14139 Execute till the end of the current function.
14140 \layout Subsubsection*
14141
14142 delete [n]
14143 \layout Standard
14144
14145 Delete breakpoint number 'n'.
14146  If used without any option clear ALL user defined break points.
14147 \layout Subsubsection*
14148
14149 info [break | stack | frame | registers ]
14150 \layout Itemize
14151
14152 info break - list all breakpoints
14153 \layout Itemize
14154
14155 info stack - show the function call stack.
14156 \layout Itemize
14157
14158 info frame - show information about the current execution frame.
14159 \layout Itemize
14160
14161 info registers - show content of all registers.
14162 \layout Subsubsection*
14163
14164 step
14165 \layout Standard
14166
14167 Step program until it reaches a different source line.
14168  Note: pressing <return> repeats the last command.
14169 \layout Subsubsection*
14170
14171 next
14172 \layout Standard
14173
14174 Step program, proceeding through subroutine calls.
14175 \layout Subsubsection*
14176
14177 run
14178 \layout Standard
14179
14180 Start debugged program.
14181 \layout Subsubsection*
14182
14183 ptype variable
14184 \layout Standard
14185
14186 Print type information of the variable.
14187 \layout Subsubsection*
14188
14189 print variable
14190 \layout Standard
14191
14192 print value of variable.
14193 \layout Subsubsection*
14194
14195 file filename
14196 \layout Standard
14197
14198 load the given file name.
14199  Note this is an alternate method of loading file for debugging.
14200 \layout Subsubsection*
14201
14202 frame
14203 \layout Standard
14204
14205 print information about current frame.
14206 \layout Subsubsection*
14207
14208 set srcmode
14209 \layout Standard
14210
14211 Toggle between C source & assembly source.
14212 \layout Subsubsection*
14213
14214 ! simulator command
14215 \layout Standard
14216
14217 Send the string following '!' to the simulator, the simulator response is
14218  displayed.
14219  Note the debugger does not interpret the command being sent to the simulator,
14220  so if a command like 'go' is sent the debugger can loose its execution
14221  context and may display incorrect values.
14222 \layout Subsubsection*
14223
14224 quit
14225 \layout Standard
14226
14227 "Watch me now.
14228  Iam going Down.
14229  My name is Bobby Brown"
14230 \layout Section
14231
14232 Interfacing with XEmacs
14233 \begin_inset LatexCommand \index{XEmacs}
14234
14235 \end_inset
14236
14237
14238 \begin_inset LatexCommand \index{Emacs}
14239
14240 \end_inset
14241
14242 .
14243 \layout Standard
14244
14245 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
14246  sdcdb.el and sdcdbsrc.el.
14247  These two files can be found in the $(prefix)/bin directory after the installat
14248 ion is complete.
14249  These files need to be loaded into XEmacs for the interface to work.
14250  This can be done at XEmacs startup time by inserting the following into
14251  your '.xemacs' file (which can be found in your HOME directory):
14252 \newline
14253
14254 \newline
14255
14256 \family typewriter
14257 (load-file sdcdbsrc.el)
14258 \family default
14259
14260 \newline
14261
14262 \newline
14263 .xemacs is a lisp file so the () around the command is REQUIRED.
14264  The files can also be loaded dynamically while XEmacs is running, set the
14265  environment variable 'EMACSLOADPATH' to the installation bin directory
14266  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
14267  To start the interface enter the following command:
14268 \newline
14269
14270 \newline
14271
14272 \family sans
14273 \series bold
14274 ESC-x sdcdbsrc
14275 \family default
14276 \series default
14277
14278 \newline
14279
14280 \newline
14281 You will prompted to enter the file name to be debugged.
14282
14283 \newline
14284
14285 \newline
14286 The command line options that are passed to the simulator directly are bound
14287  to default values in the file sdcdbsrc.el.
14288  The variables are listed below, these values maybe changed as required.
14289 \layout Itemize
14290
14291 sdcdbsrc-cpu-type '51
14292 \layout Itemize
14293
14294 sdcdbsrc-frequency '11059200
14295 \layout Itemize
14296
14297 sdcdbsrc-serial nil
14298 \layout Standard
14299
14300 The following is a list of key mapping for the debugger interface.
14301 \layout Standard
14302
14303 \SpecialChar ~
14304
14305 \family typewriter
14306
14307 \newline
14308 ;; Current Listing ::
14309 \newline
14310 ;;key\SpecialChar ~
14311 \SpecialChar ~
14312 \SpecialChar ~
14313 \SpecialChar ~
14314 \SpecialChar ~
14315 \SpecialChar ~
14316 \SpecialChar ~
14317 \SpecialChar ~
14318 \SpecialChar ~
14319 \SpecialChar ~
14320 \SpecialChar ~
14321 \SpecialChar ~
14322 \SpecialChar ~
14323 \SpecialChar ~
14324 \SpecialChar ~
14325 binding\SpecialChar ~
14326 \SpecialChar ~
14327 \SpecialChar ~
14328 \SpecialChar ~
14329 \SpecialChar ~
14330 \SpecialChar ~
14331 \SpecialChar ~
14332 \SpecialChar ~
14333 \SpecialChar ~
14334 \SpecialChar ~
14335 \SpecialChar ~
14336 \SpecialChar ~
14337 \SpecialChar ~
14338 \SpecialChar ~
14339 \SpecialChar ~
14340 \SpecialChar ~
14341 \SpecialChar ~
14342 \SpecialChar ~
14343 \SpecialChar ~
14344 \SpecialChar ~
14345 \SpecialChar ~
14346 \SpecialChar ~
14347 Comment
14348 \newline
14349 ;;---\SpecialChar ~
14350 \SpecialChar ~
14351 \SpecialChar ~
14352 \SpecialChar ~
14353 \SpecialChar ~
14354 \SpecialChar ~
14355 \SpecialChar ~
14356 \SpecialChar ~
14357 \SpecialChar ~
14358 \SpecialChar ~
14359 \SpecialChar ~
14360 \SpecialChar ~
14361 \SpecialChar ~
14362 \SpecialChar ~
14363 \SpecialChar ~
14364 ------\SpecialChar ~
14365 \SpecialChar ~
14366 \SpecialChar ~
14367 \SpecialChar ~
14368 \SpecialChar ~
14369 \SpecialChar ~
14370 \SpecialChar ~
14371 \SpecialChar ~
14372 \SpecialChar ~
14373 \SpecialChar ~
14374 \SpecialChar ~
14375 \SpecialChar ~
14376 \SpecialChar ~
14377 \SpecialChar ~
14378 \SpecialChar ~
14379 \SpecialChar ~
14380 \SpecialChar ~
14381 \SpecialChar ~
14382 \SpecialChar ~
14383 \SpecialChar ~
14384 \SpecialChar ~
14385 \SpecialChar ~
14386 --------
14387 \newline
14388 ;;
14389 \newline
14390 ;; n\SpecialChar ~
14391 \SpecialChar ~
14392 \SpecialChar ~
14393 \SpecialChar ~
14394 \SpecialChar ~
14395 \SpecialChar ~
14396 \SpecialChar ~
14397 \SpecialChar ~
14398 \SpecialChar ~
14399 \SpecialChar ~
14400 \SpecialChar ~
14401 \SpecialChar ~
14402 \SpecialChar ~
14403 \SpecialChar ~
14404  sdcdb-next-from-src\SpecialChar ~
14405 \SpecialChar ~
14406 \SpecialChar ~
14407 \SpecialChar ~
14408 \SpecialChar ~
14409 \SpecialChar ~
14410 \SpecialChar ~
14411 \SpecialChar ~
14412 \SpecialChar ~
14413 \SpecialChar ~
14414 SDCDB next command
14415 \newline
14416 ;; b\SpecialChar ~
14417 \SpecialChar ~
14418 \SpecialChar ~
14419 \SpecialChar ~
14420 \SpecialChar ~
14421 \SpecialChar ~
14422 \SpecialChar ~
14423 \SpecialChar ~
14424 \SpecialChar ~
14425 \SpecialChar ~
14426 \SpecialChar ~
14427 \SpecialChar ~
14428 \SpecialChar ~
14429 \SpecialChar ~
14430  sdcdb-back-from-src\SpecialChar ~
14431 \SpecialChar ~
14432 \SpecialChar ~
14433 \SpecialChar ~
14434 \SpecialChar ~
14435 \SpecialChar ~
14436 \SpecialChar ~
14437 \SpecialChar ~
14438 \SpecialChar ~
14439 \SpecialChar ~
14440 SDCDB back command
14441 \newline
14442 ;; c\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  sdcdb-cont-from-src\SpecialChar ~
14457 \SpecialChar ~
14458 \SpecialChar ~
14459 \SpecialChar ~
14460 \SpecialChar ~
14461 \SpecialChar ~
14462 \SpecialChar ~
14463 \SpecialChar ~
14464 \SpecialChar ~
14465 \SpecialChar ~
14466 SDCDB continue command
14467 \newline
14468 ;; s\SpecialChar ~
14469 \SpecialChar ~
14470 \SpecialChar ~
14471 \SpecialChar ~
14472 \SpecialChar ~
14473 \SpecialChar ~
14474 \SpecialChar ~
14475 \SpecialChar ~
14476 \SpecialChar ~
14477 \SpecialChar ~
14478 \SpecialChar ~
14479 \SpecialChar ~
14480 \SpecialChar ~
14481 \SpecialChar ~
14482  sdcdb-step-from-src\SpecialChar ~
14483 \SpecialChar ~
14484 \SpecialChar ~
14485 \SpecialChar ~
14486 \SpecialChar ~
14487 \SpecialChar ~
14488 \SpecialChar ~
14489 \SpecialChar ~
14490 \SpecialChar ~
14491 \SpecialChar ~
14492 SDCDB step command
14493 \newline
14494 ;; ?\SpecialChar ~
14495 \SpecialChar ~
14496 \SpecialChar ~
14497 \SpecialChar ~
14498 \SpecialChar ~
14499 \SpecialChar ~
14500 \SpecialChar ~
14501 \SpecialChar ~
14502 \SpecialChar ~
14503 \SpecialChar ~
14504 \SpecialChar ~
14505 \SpecialChar ~
14506 \SpecialChar ~
14507 \SpecialChar ~
14508  sdcdb-whatis-c-sexp\SpecialChar ~
14509 \SpecialChar ~
14510 \SpecialChar ~
14511 \SpecialChar ~
14512 \SpecialChar ~
14513 \SpecialChar ~
14514 \SpecialChar ~
14515 \SpecialChar ~
14516 \SpecialChar ~
14517 \SpecialChar ~
14518 SDCDB ptypecommand for data at
14519 \newline
14520 ;;\SpecialChar ~
14521 \SpecialChar ~
14522 \SpecialChar ~
14523 \SpecialChar ~
14524 \SpecialChar ~
14525 \SpecialChar ~
14526 \SpecialChar ~
14527 \SpecialChar ~
14528 \SpecialChar ~
14529 \SpecialChar ~
14530 \SpecialChar ~
14531 \SpecialChar ~
14532 \SpecialChar ~
14533 \SpecialChar ~
14534 \SpecialChar ~
14535 \SpecialChar ~
14536 \SpecialChar ~
14537 \SpecialChar ~
14538 \SpecialChar ~
14539 \SpecialChar ~
14540 \SpecialChar ~
14541 \SpecialChar ~
14542 \SpecialChar ~
14543 \SpecialChar ~
14544 \SpecialChar ~
14545 \SpecialChar ~
14546 \SpecialChar ~
14547 \SpecialChar ~
14548 \SpecialChar ~
14549 \SpecialChar ~
14550 \SpecialChar ~
14551 \SpecialChar ~
14552 \SpecialChar ~
14553 \SpecialChar ~
14554 \SpecialChar ~
14555 \SpecialChar ~
14556 \SpecialChar ~
14557 \SpecialChar ~
14558 \SpecialChar ~
14559 \SpecialChar ~
14560 \SpecialChar ~
14561 \SpecialChar ~
14562 \SpecialChar ~
14563 \SpecialChar ~
14564 \SpecialChar ~
14565 \SpecialChar ~
14566  buffer point
14567 \newline
14568 ;; x\SpecialChar ~
14569 \SpecialChar ~
14570 \SpecialChar ~
14571 \SpecialChar ~
14572 \SpecialChar ~
14573 \SpecialChar ~
14574 \SpecialChar ~
14575 \SpecialChar ~
14576 \SpecialChar ~
14577 \SpecialChar ~
14578 \SpecialChar ~
14579 \SpecialChar ~
14580 \SpecialChar ~
14581 \SpecialChar ~
14582  sdcdbsrc-delete\SpecialChar ~
14583 \SpecialChar ~
14584 \SpecialChar ~
14585 \SpecialChar ~
14586 \SpecialChar ~
14587 \SpecialChar ~
14588 \SpecialChar ~
14589 \SpecialChar ~
14590 \SpecialChar ~
14591 \SpecialChar ~
14592 \SpecialChar ~
14593 \SpecialChar ~
14594 \SpecialChar ~
14595 \SpecialChar ~
14596 SDCDB Delete all breakpoints if no arg
14597 \newline
14598 ;;\SpecialChar ~
14599 \SpecialChar ~
14600 \SpecialChar ~
14601 \SpecialChar ~
14602 \SpecialChar ~
14603 \SpecialChar ~
14604 \SpecialChar ~
14605 \SpecialChar ~
14606 \SpecialChar ~
14607 \SpecialChar ~
14608 \SpecialChar ~
14609 \SpecialChar ~
14610 \SpecialChar ~
14611 \SpecialChar ~
14612 \SpecialChar ~
14613 \SpecialChar ~
14614 \SpecialChar ~
14615 \SpecialChar ~
14616 \SpecialChar ~
14617 \SpecialChar ~
14618 \SpecialChar ~
14619 \SpecialChar ~
14620 \SpecialChar ~
14621 \SpecialChar ~
14622 \SpecialChar ~
14623 \SpecialChar ~
14624 \SpecialChar ~
14625 \SpecialChar ~
14626 \SpecialChar ~
14627 \SpecialChar ~
14628 \SpecialChar ~
14629 \SpecialChar ~
14630 \SpecialChar ~
14631 \SpecialChar ~
14632 \SpecialChar ~
14633 \SpecialChar ~
14634 \SpecialChar ~
14635 \SpecialChar ~
14636 \SpecialChar ~
14637 \SpecialChar ~
14638 \SpecialChar ~
14639 \SpecialChar ~
14640 \SpecialChar ~
14641 \SpecialChar ~
14642 \SpecialChar ~
14643 \SpecialChar ~
14644 given or delete arg (C-u arg x)
14645 \newline
14646 ;; m\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  sdcdbsrc-frame\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 SDCDB Display current frame if no arg,
14676 \newline
14677 ;;\SpecialChar ~
14678 \SpecialChar ~
14679 \SpecialChar ~
14680 \SpecialChar ~
14681 \SpecialChar ~
14682 \SpecialChar ~
14683 \SpecialChar ~
14684 \SpecialChar ~
14685 \SpecialChar ~
14686 \SpecialChar ~
14687 \SpecialChar ~
14688 \SpecialChar ~
14689 \SpecialChar ~
14690 \SpecialChar ~
14691 \SpecialChar ~
14692 \SpecialChar ~
14693 \SpecialChar ~
14694 \SpecialChar ~
14695 \SpecialChar ~
14696 \SpecialChar ~
14697 \SpecialChar ~
14698 \SpecialChar ~
14699 \SpecialChar ~
14700 \SpecialChar ~
14701 \SpecialChar ~
14702 \SpecialChar ~
14703 \SpecialChar ~
14704 \SpecialChar ~
14705 \SpecialChar ~
14706 \SpecialChar ~
14707 \SpecialChar ~
14708 \SpecialChar ~
14709 \SpecialChar ~
14710 \SpecialChar ~
14711 \SpecialChar ~
14712 \SpecialChar ~
14713 \SpecialChar ~
14714 \SpecialChar ~
14715 \SpecialChar ~
14716 \SpecialChar ~
14717 \SpecialChar ~
14718 \SpecialChar ~
14719 \SpecialChar ~
14720 \SpecialChar ~
14721 \SpecialChar ~
14722 \SpecialChar ~
14723 \SpecialChar ~
14724 given or display frame arg
14725 \newline
14726 ;;\SpecialChar ~
14727 \SpecialChar ~
14728 \SpecialChar ~
14729 \SpecialChar ~
14730 \SpecialChar ~
14731 \SpecialChar ~
14732 \SpecialChar ~
14733 \SpecialChar ~
14734 \SpecialChar ~
14735 \SpecialChar ~
14736 \SpecialChar ~
14737 \SpecialChar ~
14738 \SpecialChar ~
14739 \SpecialChar ~
14740 \SpecialChar ~
14741 \SpecialChar ~
14742 \SpecialChar ~
14743 \SpecialChar ~
14744 \SpecialChar ~
14745 \SpecialChar ~
14746 \SpecialChar ~
14747 \SpecialChar ~
14748 \SpecialChar ~
14749 \SpecialChar ~
14750 \SpecialChar ~
14751 \SpecialChar ~
14752 \SpecialChar ~
14753 \SpecialChar ~
14754 \SpecialChar ~
14755 \SpecialChar ~
14756 \SpecialChar ~
14757 \SpecialChar ~
14758 \SpecialChar ~
14759 \SpecialChar ~
14760 \SpecialChar ~
14761 \SpecialChar ~
14762 \SpecialChar ~
14763 \SpecialChar ~
14764 \SpecialChar ~
14765 \SpecialChar ~
14766 \SpecialChar ~
14767 \SpecialChar ~
14768 \SpecialChar ~
14769 \SpecialChar ~
14770 \SpecialChar ~
14771 \SpecialChar ~
14772 \SpecialChar ~
14773 buffer point
14774 \newline
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  sdcdbsrc-goto-sdcdb\SpecialChar ~
14790 \SpecialChar ~
14791 \SpecialChar ~
14792 \SpecialChar ~
14793 \SpecialChar ~
14794 \SpecialChar ~
14795 \SpecialChar ~
14796 \SpecialChar ~
14797 \SpecialChar ~
14798 \SpecialChar ~
14799 Goto the SDCDB output buffer
14800 \newline
14801 ;; p\SpecialChar ~
14802 \SpecialChar ~
14803 \SpecialChar ~
14804 \SpecialChar ~
14805 \SpecialChar ~
14806 \SpecialChar ~
14807 \SpecialChar ~
14808 \SpecialChar ~
14809 \SpecialChar ~
14810 \SpecialChar ~
14811 \SpecialChar ~
14812 \SpecialChar ~
14813 \SpecialChar ~
14814 \SpecialChar ~
14815  sdcdb-print-c-sexp\SpecialChar ~
14816 \SpecialChar ~
14817 \SpecialChar ~
14818 \SpecialChar ~
14819 \SpecialChar ~
14820 \SpecialChar ~
14821 \SpecialChar ~
14822 \SpecialChar ~
14823 \SpecialChar ~
14824 \SpecialChar ~
14825 \SpecialChar ~
14826 SDCDB print command for data at
14827 \newline
14828 ;;\SpecialChar ~
14829 \SpecialChar ~
14830 \SpecialChar ~
14831 \SpecialChar ~
14832 \SpecialChar ~
14833 \SpecialChar ~
14834 \SpecialChar ~
14835 \SpecialChar ~
14836 \SpecialChar ~
14837 \SpecialChar ~
14838 \SpecialChar ~
14839 \SpecialChar ~
14840 \SpecialChar ~
14841 \SpecialChar ~
14842 \SpecialChar ~
14843 \SpecialChar ~
14844 \SpecialChar ~
14845 \SpecialChar ~
14846 \SpecialChar ~
14847 \SpecialChar ~
14848 \SpecialChar ~
14849 \SpecialChar ~
14850 \SpecialChar ~
14851 \SpecialChar ~
14852 \SpecialChar ~
14853 \SpecialChar ~
14854 \SpecialChar ~
14855 \SpecialChar ~
14856 \SpecialChar ~
14857 \SpecialChar ~
14858 \SpecialChar ~
14859 \SpecialChar ~
14860 \SpecialChar ~
14861 \SpecialChar ~
14862 \SpecialChar ~
14863 \SpecialChar ~
14864 \SpecialChar ~
14865 \SpecialChar ~
14866 \SpecialChar ~
14867 \SpecialChar ~
14868 \SpecialChar ~
14869 \SpecialChar ~
14870 \SpecialChar ~
14871 \SpecialChar ~
14872 \SpecialChar ~
14873 \SpecialChar ~
14874  buffer point
14875 \newline
14876 ;; g\SpecialChar ~
14877 \SpecialChar ~
14878 \SpecialChar ~
14879 \SpecialChar ~
14880 \SpecialChar ~
14881 \SpecialChar ~
14882 \SpecialChar ~
14883 \SpecialChar ~
14884 \SpecialChar ~
14885 \SpecialChar ~
14886 \SpecialChar ~
14887 \SpecialChar ~
14888 \SpecialChar ~
14889 \SpecialChar ~
14890  sdcdbsrc-goto-sdcdb\SpecialChar ~
14891 \SpecialChar ~
14892 \SpecialChar ~
14893 \SpecialChar ~
14894 \SpecialChar ~
14895 \SpecialChar ~
14896 \SpecialChar ~
14897 \SpecialChar ~
14898 \SpecialChar ~
14899 \SpecialChar ~
14900 Goto the SDCDB output buffer
14901 \newline
14902 ;; t\SpecialChar ~
14903 \SpecialChar ~
14904 \SpecialChar ~
14905 \SpecialChar ~
14906 \SpecialChar ~
14907 \SpecialChar ~
14908 \SpecialChar ~
14909 \SpecialChar ~
14910 \SpecialChar ~
14911 \SpecialChar ~
14912 \SpecialChar ~
14913 \SpecialChar ~
14914 \SpecialChar ~
14915 \SpecialChar ~
14916  sdcdbsrc-mode\SpecialChar ~
14917 \SpecialChar ~
14918 \SpecialChar ~
14919 \SpecialChar ~
14920 \SpecialChar ~
14921 \SpecialChar ~
14922 \SpecialChar ~
14923 \SpecialChar ~
14924 \SpecialChar ~
14925 \SpecialChar ~
14926 \SpecialChar ~
14927 \SpecialChar ~
14928 \SpecialChar ~
14929 \SpecialChar ~
14930 \SpecialChar ~
14931 \SpecialChar ~
14932 Toggles Sdcdbsrc mode (turns it off)
14933 \newline
14934 ;;
14935 \newline
14936 ;; C-c C-f\SpecialChar ~
14937 \SpecialChar ~
14938 \SpecialChar ~
14939 \SpecialChar ~
14940 \SpecialChar ~
14941 \SpecialChar ~
14942 \SpecialChar ~
14943 \SpecialChar ~
14944  sdcdb-finish-from-src\SpecialChar ~
14945 \SpecialChar ~
14946 \SpecialChar ~
14947 \SpecialChar ~
14948 \SpecialChar ~
14949 \SpecialChar ~
14950 \SpecialChar ~
14951 \SpecialChar ~
14952 SDCDB finish command
14953 \newline
14954 ;;
14955 \newline
14956 ;; C-x SPC\SpecialChar ~
14957 \SpecialChar ~
14958 \SpecialChar ~
14959 \SpecialChar ~
14960 \SpecialChar ~
14961 \SpecialChar ~
14962 \SpecialChar ~
14963 \SpecialChar ~
14964  sdcdb-break\SpecialChar ~
14965 \SpecialChar ~
14966 \SpecialChar ~
14967 \SpecialChar ~
14968 \SpecialChar ~
14969 \SpecialChar ~
14970 \SpecialChar ~
14971 \SpecialChar ~
14972 \SpecialChar ~
14973 \SpecialChar ~
14974 \SpecialChar ~
14975 \SpecialChar ~
14976 \SpecialChar ~
14977 \SpecialChar ~
14978 \SpecialChar ~
14979 \SpecialChar ~
14980 \SpecialChar ~
14981 \SpecialChar ~
14982 Set break for line with point
14983 \newline
14984 ;; ESC t\SpecialChar ~
14985 \SpecialChar ~
14986 \SpecialChar ~
14987 \SpecialChar ~
14988 \SpecialChar ~
14989 \SpecialChar ~
14990 \SpecialChar ~
14991 \SpecialChar ~
14992 \SpecialChar ~
14993 \SpecialChar ~
14994  sdcdbsrc-mode\SpecialChar ~
14995 \SpecialChar ~
14996 \SpecialChar ~
14997 \SpecialChar ~
14998 \SpecialChar ~
14999 \SpecialChar ~
15000 \SpecialChar ~
15001 \SpecialChar ~
15002 \SpecialChar ~
15003 \SpecialChar ~
15004 \SpecialChar ~
15005 \SpecialChar ~
15006 \SpecialChar ~
15007 \SpecialChar ~
15008 \SpecialChar ~
15009 \SpecialChar ~
15010 Toggle Sdcdbsrc mode
15011 \newline
15012 ;; ESC m\SpecialChar ~
15013 \SpecialChar ~
15014 \SpecialChar ~
15015 \SpecialChar ~
15016 \SpecialChar ~
15017 \SpecialChar ~
15018 \SpecialChar ~
15019 \SpecialChar ~
15020 \SpecialChar ~
15021 \SpecialChar ~
15022  sdcdbsrc-srcmode\SpecialChar ~
15023 \SpecialChar ~
15024 \SpecialChar ~
15025 \SpecialChar ~
15026 \SpecialChar ~
15027 \SpecialChar ~
15028 \SpecialChar ~
15029 \SpecialChar ~
15030 \SpecialChar ~
15031 \SpecialChar ~
15032 \SpecialChar ~
15033 \SpecialChar ~
15034  Toggle list mode
15035 \newline
15036 ;;
15037 \newline
15038
15039 \layout Chapter
15040 \pagebreak_top
15041 TIPS
15042 \layout Standard
15043
15044 Here are a few guidelines that will help the compiler generate more efficient
15045  code, some of the tips are specific to this compiler others are generally
15046  good programming practice.
15047 \layout Itemize
15048
15049 Use the smallest data type to represent your data-value.
15050  If it is known in advance that the value is going to be less than 256 then
15051  use an 'unsigned char' instead of a 'short' or 'int'.
15052  Please note, that ANSI C requires both signed and unsigned chars to be
15053  promoted to 'signed int' before doing any operation.
15054  This promotion can be omitted, if the result is the same.
15055  The effect of the promotion rules together with the sign-extension is often
15056  supprising:
15057 \begin_deeper
15058 \layout Verse
15059
15060
15061 \family typewriter
15062 unsigned char uc = 0xfe;
15063 \newline
15064 if (uc * uc < 0) /* this is true! */
15065 \newline
15066 {
15067 \newline
15068 \SpecialChar ~
15069 \SpecialChar ~
15070 \SpecialChar ~
15071 \SpecialChar ~
15072 ....
15073 \newline
15074 }
15075 \layout Standard
15076
15077
15078 \family typewriter
15079 uc * uc
15080 \family default
15081  is evaluated as
15082 \family typewriter
15083 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
15084 \family default
15085 .
15086
15087 \newline
15088 Another one:
15089 \layout Verse
15090
15091
15092 \family typewriter
15093 (unsigned char) -12 / (signed char) -3 = ...
15094 \layout Standard
15095
15096 No, the result is not 4:
15097 \layout Verse
15098
15099
15100 \family typewriter
15101 (int) (unsigned char) -12 / (int) (signed char) -3 =
15102 \newline
15103 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
15104 \newline
15105 (int) 0x00f4 / (int) 0xfffd =
15106 \newline
15107 (int) 0x00f4 / (int) 0xfffd =
15108 \newline
15109 (int) 244 / (int) -3 =
15110 \newline
15111 (int) -81 = (int) 0xffaf;
15112 \layout Standard
15113
15114 Don't complain, that gcc gives you a different result.
15115  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
15116  Therefore the results are different.
15117 \newline
15118 From
15119 \begin_inset Quotes sld
15120 \end_inset
15121
15122 comp.lang.c FAQ
15123 \begin_inset Quotes srd
15124 \end_inset
15125
15126 :
15127 \layout Quote
15128
15129 If well-defined overflow characteristics are important and negative values
15130  are not, or if you want to steer clear of sign-extension problems when
15131  manipulating bits or bytes, use one of the corresponding unsigned types.
15132  (Beware when mixing signed and unsigned values in expressions, though.)
15133 \newline
15134 Although character types (especially unsigned char) can be used as "tiny"
15135  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
15136 ble sign extension and increased code size.
15137 \end_deeper
15138 \layout Itemize
15139
15140 Use unsigned when it is known in advance that the value is not going to
15141  be negative.
15142  This helps especially if you are doing division or multiplication, bit-shifting
15143  or are using an array index.
15144 \layout Itemize
15145
15146 NEVER jump into a LOOP.
15147 \layout Itemize
15148
15149 Declare the variables to be local
15150 \begin_inset LatexCommand \index{local variables}
15151
15152 \end_inset
15153
15154  whenever possible, especially loop control variables (induction).
15155 \layout Itemize
15156
15157 Since the compiler does not always do implicit integral promotion, the programme
15158 r should do an explicit cast when integral promotion is required.
15159 \layout Itemize
15160
15161 Reducing the size of division, multiplication & modulus operations can reduce
15162  code size substantially.
15163  Take the following code for example.
15164 \begin_deeper
15165 \layout Verse
15166
15167
15168 \family typewriter
15169 foobar(unsigned int p1, unsigned char ch)
15170 \newline
15171 {
15172 \newline
15173 \SpecialChar ~
15174 \SpecialChar ~
15175 \SpecialChar ~
15176 \SpecialChar ~
15177 unsigned char ch1 = p1 % ch ;
15178 \newline
15179 \SpecialChar ~
15180 \SpecialChar ~
15181 \SpecialChar ~
15182 \SpecialChar ~
15183 ....
15184 \newline
15185 }
15186 \layout Standard
15187
15188 For the modulus operation the variable ch will be promoted to unsigned int
15189  first then the modulus operation will be performed (this will lead to a
15190  call to support routine _moduint()), and the result will be casted to a
15191  char.
15192  If the code is changed to
15193 \layout Verse
15194
15195
15196 \family typewriter
15197 foobar(unsigned int p1, unsigned char ch)
15198 \newline
15199 {
15200 \newline
15201 \SpecialChar ~
15202 \SpecialChar ~
15203 \SpecialChar ~
15204 \SpecialChar ~
15205 unsigned char ch1 = (unsigned char)p1 % ch ;
15206 \newline
15207 \SpecialChar ~
15208 \SpecialChar ~
15209 \SpecialChar ~
15210 \SpecialChar ~
15211 ....
15212 \newline
15213 }
15214 \layout Standard
15215
15216 It would substantially reduce the code generated (future versions of the
15217  compiler will be smart enough to detect such optimization opportunities).
15218 \end_deeper
15219 \layout Itemize
15220
15221 Have a look at the assembly listing to get a
15222 \begin_inset Quotes sld
15223 \end_inset
15224
15225 feeling
15226 \begin_inset Quotes srd
15227 \end_inset
15228
15229  for the code generation.
15230 \layout Section
15231
15232 Tools
15233 \begin_inset LatexCommand \index{Tools}
15234
15235 \end_inset
15236
15237  included in the distribution
15238 \layout Standard
15239 \align center
15240
15241 \begin_inset  Tabular
15242 <lyxtabular version="3" rows="12" columns="3">
15243 <features>
15244 <column alignment="center" valignment="top" leftline="true" width="0pt">
15245 <column alignment="center" valignment="top" leftline="true" width="0pt">
15246 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
15247 <row topline="true" bottomline="true">
15248 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15249 \begin_inset Text
15250
15251 \layout Standard
15252
15253 Name
15254 \end_inset
15255 </cell>
15256 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15257 \begin_inset Text
15258
15259 \layout Standard
15260
15261 Purpose
15262 \end_inset
15263 </cell>
15264 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15265 \begin_inset Text
15266
15267 \layout Standard
15268
15269 Directory
15270 \end_inset
15271 </cell>
15272 </row>
15273 <row topline="true">
15274 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15275 \begin_inset Text
15276
15277 \layout Standard
15278
15279 uCsim
15280 \end_inset
15281 </cell>
15282 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15283 \begin_inset Text
15284
15285 \layout Standard
15286
15287 Simulator for various architectures
15288 \end_inset
15289 </cell>
15290 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15291 \begin_inset Text
15292
15293 \layout Standard
15294
15295 sdcc/sim/ucsim
15296 \end_inset
15297 </cell>
15298 </row>
15299 <row topline="true">
15300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15301 \begin_inset Text
15302
15303 \layout Standard
15304
15305 keil2sdcc.pl
15306 \end_inset
15307 </cell>
15308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15309 \begin_inset Text
15310
15311 \layout Standard
15312
15313 header file conversion
15314 \end_inset
15315 </cell>
15316 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15317 \begin_inset Text
15318
15319 \layout Standard
15320
15321 sdcc/support/scripts
15322 \end_inset
15323 </cell>
15324 </row>
15325 <row topline="true">
15326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15327 \begin_inset Text
15328
15329 \layout Standard
15330
15331 mh2h.c
15332 \end_inset
15333 </cell>
15334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15335 \begin_inset Text
15336
15337 \layout Standard
15338
15339 header file conversion
15340 \end_inset
15341 </cell>
15342 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15343 \begin_inset Text
15344
15345 \layout Standard
15346
15347 sdcc/support/scripts
15348 \end_inset
15349 </cell>
15350 </row>
15351 <row topline="true">
15352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15353 \begin_inset Text
15354
15355 \layout Standard
15356
15357 as-gbz80
15358 \end_inset
15359 </cell>
15360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15361 \begin_inset Text
15362
15363 \layout Standard
15364
15365 Assembler
15366 \end_inset
15367 </cell>
15368 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15369 \begin_inset Text
15370
15371 \layout Standard
15372
15373
15374 \family roman
15375 \series medium
15376 \shape up
15377 \size normal
15378 \emph off
15379 \bar no
15380 \noun off
15381 \color none
15382 sdcc/bin
15383 \end_inset
15384 </cell>
15385 </row>
15386 <row topline="true">
15387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15388 \begin_inset Text
15389
15390 \layout Standard
15391
15392 as-z80
15393 \end_inset
15394 </cell>
15395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15396 \begin_inset Text
15397
15398 \layout Standard
15399
15400 Assembler
15401 \end_inset
15402 </cell>
15403 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15404 \begin_inset Text
15405
15406 \layout Standard
15407
15408
15409 \family roman
15410 \series medium
15411 \shape up
15412 \size normal
15413 \emph off
15414 \bar no
15415 \noun off
15416 \color none
15417 sdcc/bin
15418 \end_inset
15419 </cell>
15420 </row>
15421 <row topline="true">
15422 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15423 \begin_inset Text
15424
15425 \layout Standard
15426
15427 asx8051
15428 \end_inset
15429 </cell>
15430 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15431 \begin_inset Text
15432
15433 \layout Standard
15434
15435 Assembler
15436 \end_inset
15437 </cell>
15438 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15439 \begin_inset Text
15440
15441 \layout Standard
15442
15443
15444 \family roman
15445 \series medium
15446 \shape up
15447 \size normal
15448 \emph off
15449 \bar no
15450 \noun off
15451 \color none
15452 sdcc/bin
15453 \end_inset
15454 </cell>
15455 </row>
15456 <row topline="true">
15457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15458 \begin_inset Text
15459
15460 \layout Standard
15461
15462 sdcdb
15463 \end_inset
15464 </cell>
15465 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15466 \begin_inset Text
15467
15468 \layout Standard
15469
15470 Simulator
15471 \end_inset
15472 </cell>
15473 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15474 \begin_inset Text
15475
15476 \layout Standard
15477
15478
15479 \family roman
15480 \series medium
15481 \shape up
15482 \size normal
15483 \emph off
15484 \bar no
15485 \noun off
15486 \color none
15487 sdcc/bin
15488 \end_inset
15489 </cell>
15490 </row>
15491 <row topline="true">
15492 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15493 \begin_inset Text
15494
15495 \layout Standard
15496
15497 aslink
15498 \end_inset
15499 </cell>
15500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15501 \begin_inset Text
15502
15503 \layout Standard
15504
15505 Linker
15506 \end_inset
15507 </cell>
15508 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15509 \begin_inset Text
15510
15511 \layout Standard
15512
15513
15514 \family roman
15515 \series medium
15516 \shape up
15517 \size normal
15518 \emph off
15519 \bar no
15520 \noun off
15521 \color none
15522 sdcc/bin
15523 \end_inset
15524 </cell>
15525 </row>
15526 <row topline="true">
15527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15528 \begin_inset Text
15529
15530 \layout Standard
15531
15532 link-z80
15533 \end_inset
15534 </cell>
15535 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15536 \begin_inset Text
15537
15538 \layout Standard
15539
15540 Linker
15541 \end_inset
15542 </cell>
15543 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15544 \begin_inset Text
15545
15546 \layout Standard
15547
15548
15549 \family roman
15550 \series medium
15551 \shape up
15552 \size normal
15553 \emph off
15554 \bar no
15555 \noun off
15556 \color none
15557 sdcc/bin
15558 \end_inset
15559 </cell>
15560 </row>
15561 <row topline="true">
15562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15563 \begin_inset Text
15564
15565 \layout Standard
15566
15567 link-gbz80
15568 \end_inset
15569 </cell>
15570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15571 \begin_inset Text
15572
15573 \layout Standard
15574
15575 Linker
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
15584 \family roman
15585 \series medium
15586 \shape up
15587 \size normal
15588 \emph off
15589 \bar no
15590 \noun off
15591 \color none
15592 sdcc/bin
15593 \end_inset
15594 </cell>
15595 </row>
15596 <row topline="true" bottomline="true">
15597 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15598 \begin_inset Text
15599
15600 \layout Standard
15601
15602 packihx
15603 \end_inset
15604 </cell>
15605 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15606 \begin_inset Text
15607
15608 \layout Standard
15609
15610 ihx packer
15611 \end_inset
15612 </cell>
15613 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15614 \begin_inset Text
15615
15616 \layout Standard
15617
15618
15619 \family roman
15620 \series medium
15621 \shape up
15622 \size normal
15623 \emph off
15624 \bar no
15625 \noun off
15626 \color none
15627 sdcc/bin
15628 \end_inset
15629 </cell>
15630 </row>
15631 </lyxtabular>
15632
15633 \end_inset
15634
15635
15636 \newline
15637
15638 \layout Section
15639
15640 Documentation
15641 \begin_inset LatexCommand \index{Documentation}
15642
15643 \end_inset
15644
15645  included in the distribution
15646 \layout Standard
15647 \align center
15648
15649 \begin_inset  Tabular
15650 <lyxtabular version="3" rows="10" columns="2">
15651 <features>
15652 <column alignment="left" valignment="top" leftline="true" width="0">
15653 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
15654 <row topline="true" bottomline="true">
15655 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15656 \begin_inset Text
15657
15658 \layout Standard
15659
15660 Subject / Title
15661 \end_inset
15662 </cell>
15663 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15664 \begin_inset Text
15665
15666 \layout Standard
15667
15668 Where to get / filename
15669 \end_inset
15670 </cell>
15671 </row>
15672 <row topline="true">
15673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15674 \begin_inset Text
15675
15676 \layout Standard
15677
15678 SDCC Compiler User Guide
15679 \end_inset
15680 </cell>
15681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15682 \begin_inset Text
15683
15684 \layout Standard
15685
15686 You're reading it right now
15687 \end_inset
15688 </cell>
15689 </row>
15690 <row topline="true">
15691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15692 \begin_inset Text
15693
15694 \layout Standard
15695
15696 Changelog of SDCC
15697 \end_inset
15698 </cell>
15699 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15700 \begin_inset Text
15701
15702 \layout Standard
15703
15704 sdcc/Changelog
15705 \end_inset
15706 </cell>
15707 </row>
15708 <row topline="true">
15709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15710 \begin_inset Text
15711
15712 \layout Standard
15713
15714 ASXXXX Assemblers and ASLINK Relocating Linker
15715 \end_inset
15716 </cell>
15717 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15718 \begin_inset Text
15719
15720 \layout Standard
15721
15722 sdcc/as/doc/asxhtm.html
15723 \end_inset
15724 </cell>
15725 </row>
15726 <row topline="true">
15727 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15728 \begin_inset Text
15729
15730 \layout Standard
15731
15732 SDCC regression test
15733 \begin_inset LatexCommand \index{Regression test}
15734
15735 \end_inset
15736
15737
15738 \end_inset
15739 </cell>
15740 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15741 \begin_inset Text
15742
15743 \layout Standard
15744
15745 sdcc/doc/test_suite_spec.pdf
15746 \end_inset
15747 </cell>
15748 </row>
15749 <row topline="true">
15750 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15751 \begin_inset Text
15752
15753 \layout Standard
15754
15755 Various notes
15756 \end_inset
15757 </cell>
15758 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15759 \begin_inset Text
15760
15761 \layout Standard
15762
15763 sdcc/doc/*
15764 \end_inset
15765 </cell>
15766 </row>
15767 <row topline="true">
15768 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15769 \begin_inset Text
15770
15771 \layout Standard
15772
15773 Notes on debugging with sdcdb
15774 \begin_inset LatexCommand \index{sdcdb (debugger)}
15775
15776 \end_inset
15777
15778
15779 \end_inset
15780 </cell>
15781 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15782 \begin_inset Text
15783
15784 \layout Standard
15785
15786 sdcc/debugger/README
15787 \end_inset
15788 </cell>
15789 </row>
15790 <row topline="true">
15791 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15792 \begin_inset Text
15793
15794 \layout Standard
15795
15796 Software simulator for microcontrollers
15797 \end_inset
15798 </cell>
15799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15800 \begin_inset Text
15801
15802 \layout Standard
15803
15804
15805 \family roman
15806 \series medium
15807 \shape up
15808 \size normal
15809 \emph off
15810 \bar no
15811 \noun off
15812 \color none
15813 sdcc/sim/ucsim/doc
15814 \family default
15815 \series default
15816 \shape default
15817 \size default
15818 \emph default
15819 \bar default
15820 \noun default
15821 \color default
15822 /index.html
15823 \end_inset
15824 </cell>
15825 </row>
15826 <row topline="true">
15827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15828 \begin_inset Text
15829
15830 \layout Standard
15831
15832 Temporary notes on the pic16
15833 \begin_inset LatexCommand \index{PIC16}
15834
15835 \end_inset
15836
15837  port
15838 \end_inset
15839 </cell>
15840 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15841 \begin_inset Text
15842
15843 \layout Standard
15844
15845 sdcc/src/pic16/NOTES
15846 \end_inset
15847 </cell>
15848 </row>
15849 <row topline="true" bottomline="true">
15850 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15851 \begin_inset Text
15852
15853 \layout Standard
15854
15855 SDCC internal documentation (debugging file format)
15856 \end_inset
15857 </cell>
15858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15859 \begin_inset Text
15860
15861 \layout Standard
15862
15863 sdcc/doc/
15864 \family roman
15865 \series medium
15866 \shape up
15867 \size normal
15868 \emph off
15869 \bar no
15870 \noun off
15871 \color none
15872 cdbfileformat.pd
15873 \family default
15874 \series default
15875 \shape default
15876 \size default
15877 \emph default
15878 \bar default
15879 \noun default
15880 \color default
15881 f
15882 \end_inset
15883 </cell>
15884 </row>
15885 </lyxtabular>
15886
15887 \end_inset
15888
15889
15890 \newline
15891
15892 \layout Section
15893
15894 Related open source tools
15895 \begin_inset LatexCommand \index{Related tools}
15896
15897 \end_inset
15898
15899
15900 \layout Standard
15901 \align center
15902
15903 \begin_inset  Tabular
15904 <lyxtabular version="3" rows="10" columns="3">
15905 <features>
15906 <column alignment="center" valignment="top" leftline="true" width="0pt">
15907 <column alignment="block" valignment="top" leftline="true" width="30line%">
15908 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
15909 <row topline="true" bottomline="true">
15910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15911 \begin_inset Text
15912
15913 \layout Standard
15914
15915 Name
15916 \end_inset
15917 </cell>
15918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15919 \begin_inset Text
15920
15921 \layout Standard
15922
15923 Purpose
15924 \end_inset
15925 </cell>
15926 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15927 \begin_inset Text
15928
15929 \layout Standard
15930
15931 Where to get
15932 \end_inset
15933 </cell>
15934 </row>
15935 <row topline="true">
15936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15937 \begin_inset Text
15938
15939 \layout Standard
15940
15941 gpsim
15942 \begin_inset LatexCommand \index{gpsim (PIC simulator)}
15943
15944 \end_inset
15945
15946
15947 \end_inset
15948 </cell>
15949 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15950 \begin_inset Text
15951
15952 \layout Standard
15953
15954 PIC simulator
15955 \end_inset
15956 </cell>
15957 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15958 \begin_inset Text
15959
15960 \layout Standard
15961
15962
15963 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
15964
15965 \end_inset
15966
15967
15968 \end_inset
15969 </cell>
15970 </row>
15971 <row topline="true">
15972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15973 \begin_inset Text
15974
15975 \layout Standard
15976
15977 flP5
15978 \end_inset
15979 </cell>
15980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15981 \begin_inset Text
15982
15983 \layout Standard
15984
15985 PIC programmer
15986 \end_inset
15987 </cell>
15988 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15989 \begin_inset Text
15990
15991 \layout Standard
15992
15993
15994 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
15995
15996 \end_inset
15997
15998
15999 \end_inset
16000 </cell>
16001 </row>
16002 <row topline="true">
16003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16004 \begin_inset Text
16005
16006 \layout Standard
16007
16008 indent
16009 \begin_inset LatexCommand \index{indent (source formatting tool)}
16010
16011 \end_inset
16012
16013
16014 \end_inset
16015 </cell>
16016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16017 \begin_inset Text
16018
16019 \layout Standard
16020
16021 Formats C source - Master of the white spaces
16022 \end_inset
16023 </cell>
16024 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16025 \begin_inset Text
16026
16027 \layout Standard
16028
16029
16030 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
16031
16032 \end_inset
16033
16034
16035 \end_inset
16036 </cell>
16037 </row>
16038 <row topline="true">
16039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16040 \begin_inset Text
16041
16042 \layout Standard
16043
16044 srecord
16045 \begin_inset LatexCommand \index{srecord (tool)}
16046
16047 \end_inset
16048
16049
16050 \end_inset
16051 </cell>
16052 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16053 \begin_inset Text
16054
16055 \layout Standard
16056
16057 Object file conversion, checksumming, ...
16058 \end_inset
16059 </cell>
16060 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16061 \begin_inset Text
16062
16063 \layout Standard
16064
16065
16066 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
16067
16068 \end_inset
16069
16070
16071 \end_inset
16072 </cell>
16073 </row>
16074 <row topline="true">
16075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16076 \begin_inset Text
16077
16078 \layout Standard
16079
16080 objdump
16081 \begin_inset LatexCommand \index{objdump (tool)}
16082
16083 \end_inset
16084
16085
16086 \end_inset
16087 </cell>
16088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16089 \begin_inset Text
16090
16091 \layout Standard
16092
16093 Object file conversion, ...
16094 \end_inset
16095 </cell>
16096 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16097 \begin_inset Text
16098
16099 \layout Standard
16100
16101 Part of binutils (should be there anyway)
16102 \end_inset
16103 </cell>
16104 </row>
16105 <row topline="true">
16106 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16107 \begin_inset Text
16108
16109 \layout Standard
16110
16111 doxygen
16112 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
16113
16114 \end_inset
16115
16116
16117 \end_inset
16118 </cell>
16119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16120 \begin_inset Text
16121
16122 \layout Standard
16123
16124 Source code documentation system
16125 \end_inset
16126 </cell>
16127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16128 \begin_inset Text
16129
16130 \layout Standard
16131
16132
16133 \begin_inset LatexCommand \url{http://www.doxygen.org}
16134
16135 \end_inset
16136
16137
16138 \end_inset
16139 </cell>
16140 </row>
16141 <row topline="true">
16142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16143 \begin_inset Text
16144
16145 \layout Standard
16146
16147 kdevelop
16148 \end_inset
16149 </cell>
16150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16151 \begin_inset Text
16152
16153 \layout Standard
16154
16155 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
16156 \end_inset
16157 </cell>
16158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16159 \begin_inset Text
16160
16161 \layout Standard
16162
16163
16164 \begin_inset LatexCommand \url{http://www.kdevelop.org}
16165
16166 \end_inset
16167
16168
16169 \end_inset
16170 </cell>
16171 </row>
16172 <row topline="true">
16173 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16174 \begin_inset Text
16175
16176 \layout Standard
16177
16178 splint
16179 \begin_inset LatexCommand \index{splint (syntax checking tool)}
16180
16181 \end_inset
16182
16183
16184 \end_inset
16185 </cell>
16186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16187 \begin_inset Text
16188
16189 \layout Standard
16190
16191 Statically checks c sources
16192 \end_inset
16193 </cell>
16194 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16195 \begin_inset Text
16196
16197 \layout Standard
16198
16199
16200 \begin_inset LatexCommand \url{http://www.splint.org}
16201
16202 \end_inset
16203
16204
16205 \end_inset
16206 </cell>
16207 </row>
16208 <row topline="true" bottomline="true">
16209 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16210 \begin_inset Text
16211
16212 \layout Standard
16213
16214 ddd
16215 \begin_inset LatexCommand \index{ddd (debugger)}
16216
16217 \end_inset
16218
16219
16220 \end_inset
16221 </cell>
16222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16223 \begin_inset Text
16224
16225 \layout Standard
16226
16227 Debugger, serves nicely as GUI to sdcdb
16228 \begin_inset LatexCommand \index{sdcdb (debugger)}
16229
16230 \end_inset
16231
16232  (Unix only)
16233 \end_inset
16234 </cell>
16235 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16236 \begin_inset Text
16237
16238 \layout Standard
16239
16240
16241 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
16242
16243 \end_inset
16244
16245
16246 \end_inset
16247 </cell>
16248 </row>
16249 </lyxtabular>
16250
16251 \end_inset
16252
16253
16254 \newline
16255
16256 \layout Section
16257
16258 Related documentation / recommended reading
16259 \layout Standard
16260 \align center
16261
16262 \begin_inset  Tabular
16263 <lyxtabular version="3" rows="4" columns="3">
16264 <features>
16265 <column alignment="center" valignment="top" leftline="true" width="0pt">
16266 <column alignment="block" valignment="top" leftline="true" width="30line%">
16267 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
16268 <row topline="true" bottomline="true">
16269 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16270 \begin_inset Text
16271
16272 \layout Standard
16273
16274 Name
16275 \end_inset
16276 </cell>
16277 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16278 \begin_inset Text
16279
16280 \layout Standard
16281
16282 Subject / Title
16283 \end_inset
16284 </cell>
16285 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16286 \begin_inset Text
16287
16288 \layout Standard
16289
16290 Where to get
16291 \end_inset
16292 </cell>
16293 </row>
16294 <row topline="true">
16295 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16296 \begin_inset Text
16297
16298 \layout Standard
16299
16300
16301 \family roman
16302 \series medium
16303 \shape up
16304 \size normal
16305 \emph off
16306 \bar no
16307 \noun off
16308 \color none
16309 c-refcard.pdf
16310 \end_inset
16311 </cell>
16312 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16313 \begin_inset Text
16314
16315 \layout Standard
16316
16317 C Reference Card
16318 \begin_inset LatexCommand \index{C Reference card}
16319
16320 \end_inset
16321
16322 , 2 pages
16323 \end_inset
16324 </cell>
16325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16326 \begin_inset Text
16327
16328 \layout Standard
16329
16330
16331 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
16332
16333 \end_inset
16334
16335
16336 \end_inset
16337 </cell>
16338 </row>
16339 <row topline="true">
16340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16341 \begin_inset Text
16342
16343 \layout Standard
16344
16345 c-faq
16346 \end_inset
16347 </cell>
16348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16349 \begin_inset Text
16350
16351 \layout Standard
16352
16353 C-FAQ-list
16354 \end_inset
16355 </cell>
16356 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16357 \begin_inset Text
16358
16359 \layout Standard
16360
16361
16362 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
16363
16364 \end_inset
16365
16366
16367 \end_inset
16368 </cell>
16369 </row>
16370 <row topline="true" bottomline="true">
16371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16372 \begin_inset Text
16373
16374 \layout Standard
16375
16376 S.
16377  S.
16378  Muchnick
16379 \end_inset
16380 </cell>
16381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16382 \begin_inset Text
16383
16384 \layout Standard
16385
16386 Advanced Compiler Design and Implementation
16387 \end_inset
16388 </cell>
16389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16390 \begin_inset Text
16391
16392 \layout Standard
16393
16394 bookstore (very dedicated, probably read other books first)
16395 \end_inset
16396 </cell>
16397 </row>
16398 </lyxtabular>
16399
16400 \end_inset
16401
16402
16403 \newline
16404
16405 \layout Section
16406
16407 Some Questions
16408 \layout Standard
16409
16410 Some questions answered, some pointers given - it might be time to in turn
16411  ask
16412 \emph on
16413 you
16414 \emph default
16415  some questions:
16416 \layout Itemize
16417
16418 can you solve your project with the selected microcontroller? Would you
16419  find out early or rather late that your target is too small/slow/whatever?
16420  Can you switch to a slightly better device if it doesn't fit?
16421 \layout Itemize
16422
16423 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
16424  and/or another programming language be more adequate? Would an operating
16425  system on the target device help?
16426 \layout Itemize
16427
16428 if you solved the problem, will the marketing department be happy?
16429 \layout Itemize
16430
16431 if the marketing department is happy, will customers be happy?
16432 \layout Itemize
16433
16434 if you're the project manager, marketing department and maybe even the customer
16435  in one person, have you tried to see the project from the outside?
16436 \layout Itemize
16437
16438 is the project done if you think it is done? Or is just that other interface/pro
16439 tocol/feature/configuration/option missing? How about website, manual(s),
16440  internationalization, packaging, labels, electromagnetic compatability/interfer
16441 ence, documentation for production, production test software, update mechanism,
16442  patent issues?
16443 \layout Itemize
16444
16445 is your project adequately positioned in that magic triangle: fame, fortune,
16446  fun?
16447 \layout Standard
16448
16449 Maybe not all answers to these questions are known and some answers may
16450  even be
16451 \emph on
16452 no
16453 \emph default
16454 , nevertheless knowing these questions may help you to avoid burnout
16455 \begin_inset Foot
16456 collapsed false
16457
16458 \layout Standard
16459
16460 burnout is bad for electronic devices, programmers and motorcycle tyres
16461 \end_inset
16462
16463 .
16464  Chances are you didn't want to hear some of them...
16465 \layout Chapter
16466
16467 Support
16468 \begin_inset LatexCommand \index{Support}
16469
16470 \end_inset
16471
16472
16473 \layout Standard
16474
16475 SDCC has grown to be a large project.
16476  The compiler alone (without the preprocessor, assembler and linker) is
16477  well over 100,000 lines of code (blank stripped).
16478  The open source nature of this project is a key to its continued growth
16479  and support.
16480  You gain the benefit and support of many active software developers and
16481  end users.
16482  Is SDCC perfect? No, that's why we need your help.
16483  The developers take pride in fixing reported bugs.
16484  You can help by reporting the bugs and helping other SDCC users.
16485  There are lots of ways to contribute, and we encourage you to take part
16486  in making SDCC a great software package.
16487
16488 \layout Standard
16489
16490 The SDCC project is hosted on the SDCC sourceforge site at
16491 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
16492
16493 \end_inset
16494
16495 .
16496  You'll find the complete set of mailing lists
16497 \begin_inset LatexCommand \index{Mailing list}
16498
16499 \end_inset
16500
16501 , forums, bug reporting system, patch submission
16502 \begin_inset LatexCommand \index{Patch submission}
16503
16504 \end_inset
16505
16506  system, download
16507 \begin_inset LatexCommand \index{download}
16508
16509 \end_inset
16510
16511  area and cvs code repository
16512 \begin_inset LatexCommand \index{cvs code repository}
16513
16514 \end_inset
16515
16516  there.
16517 \layout Section
16518
16519 Reporting Bugs
16520 \begin_inset LatexCommand \index{Bug reporting}
16521
16522 \end_inset
16523
16524
16525 \begin_inset LatexCommand \index{Reporting bugs}
16526
16527 \end_inset
16528
16529
16530 \layout Standard
16531
16532 The recommended way of reporting bugs is using the infrastructure of the
16533  sourceforge site.
16534  You can follow the status of bug reports there and have an overview about
16535  the known bugs.
16536 \layout Standard
16537
16538 Bug reports are automatically forwarded to the developer mailing list and
16539  will be fixed ASAP.
16540  When reporting a bug, it is very useful to include a small test program
16541  (the smaller the better) which reproduces the problem.
16542  If you can isolate the problem by looking at the generated assembly code,
16543  this can be very helpful.
16544  Compiling your program with the -
16545 \begin_inset ERT
16546 status Collapsed
16547
16548 \layout Standard
16549
16550 \backslash
16551 /
16552 \end_inset
16553
16554 -dumpall
16555 \begin_inset LatexCommand \index{-\/-dumpall}
16556
16557 \end_inset
16558
16559  option can sometimes be useful in locating optimization problems.
16560  When reporting a bug please maker sure you:
16561 \layout Enumerate
16562
16563 Attach the code you are compiling with SDCC.
16564
16565 \layout Enumerate
16566
16567 Specify the exact command you use to run SDCC, or attach your Makefile.
16568
16569 \layout Enumerate
16570
16571 Specify the SDCC version (type "
16572 \family sans
16573 \series bold
16574 sdcc -v
16575 \family default
16576 \series default
16577 "), your platform, and operating system.
16578
16579 \layout Enumerate
16580
16581 Provide an exact copy of any error message or incorrect output.
16582
16583 \layout Enumerate
16584
16585 Put something meaningful in the subject of your message.
16586 \layout Standard
16587
16588 Please attempt to include these 5 important parts, as applicable, in all
16589  requests for support or when reporting any problems or bugs with SDCC.
16590  Though this will make your message lengthy, it will greatly improve your
16591  chance that SDCC users and developers will be able to help you.
16592  Some SDCC developers are frustrated by bug reports without code provided
16593  that they can use to reproduce and ultimately fix the problem, so please
16594  be sure to provide sample code if you are reporting a bug!
16595 \layout Standard
16596
16597 Please have a short check that you are using a recent version of SDCC and
16598  the bug is not yet known.
16599  This is the link for reporting bugs:
16600 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
16601
16602 \end_inset
16603
16604 .
16605 \layout Section
16606
16607 Requesting Features
16608 \begin_inset LatexCommand \label{sub:Requesting-Features}
16609
16610 \end_inset
16611
16612
16613 \begin_inset LatexCommand \index{Feature request}
16614
16615 \end_inset
16616
16617
16618 \begin_inset LatexCommand \index{Requesting features}
16619
16620 \end_inset
16621
16622
16623 \layout Standard
16624
16625 Like bug reports feature requests are forwarded to the developer mailing
16626  list.
16627  This is the link for requesting features:
16628 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
16629
16630 \end_inset
16631
16632 .
16633 \layout Section
16634
16635 Submitting patches
16636 \layout Standard
16637
16638 Like bug reports contributed patches are forwarded to the developer mailing
16639  list.
16640  This is the link for submitting patches
16641 \begin_inset LatexCommand \index{Patch submission}
16642
16643 \end_inset
16644
16645 :
16646 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
16647
16648 \end_inset
16649
16650 .
16651 \layout Standard
16652
16653 You need to specify some parameters to the
16654 \family typewriter
16655 diff
16656 \family default
16657  command for the patches to be useful.
16658  If you modified more than one file a patch created f.e.
16659  with
16660 \family sans
16661 \series bold
16662
16663 \begin_inset Quotes sld
16664 \end_inset
16665
16666 diff -Naur unmodified_directory modified_directory >my_changes.patch
16667 \begin_inset Quotes srd
16668 \end_inset
16669
16670
16671 \family default
16672 \series default
16673  will be fine, otherwise
16674 \family sans
16675 \series bold
16676
16677 \begin_inset Quotes sld
16678 \end_inset
16679
16680 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
16681 \begin_inset Quotes srd
16682 \end_inset
16683
16684
16685 \series default
16686
16687 \family default
16688 will do.
16689 \layout Section
16690
16691 Getting Help
16692 \layout Standard
16693
16694 These links should take you directly to the
16695 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
16696
16697 \end_inset
16698
16699
16700 \begin_inset Foot
16701 collapsed false
16702
16703 \layout Standard
16704
16705 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
16706  automated messages (mid 2003)
16707 \end_inset
16708
16709  and the
16710 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
16711
16712 \end_inset
16713
16714 , lists and forums are archived and searchable so if you are lucky someone
16715  already had a similar problem.
16716 \layout Section
16717
16718 ChangeLog
16719 \layout Standard
16720
16721 You can follow the status of the cvs version
16722 \begin_inset LatexCommand \index{version}
16723
16724 \end_inset
16725
16726  of SDCC by watching the Changelog
16727 \begin_inset LatexCommand \index{Changelog}
16728
16729 \end_inset
16730
16731  in the cvs-repository
16732 \newline
16733
16734 \size footnotesize
16735
16736 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
16737
16738 \end_inset
16739
16740 .
16741 \layout Section
16742
16743 Release policy
16744 \begin_inset LatexCommand \index{Release policy}
16745
16746 \end_inset
16747
16748
16749 \layout Standard
16750
16751 Historically there often were long delays between official releases and
16752  the sourceforge download area tends to get not updated at all.
16753  Excuses in the past might have referred to problems with live range analysis,
16754  but as this was fixed a while ago, the current problem is that another
16755  excuse has to be found.
16756  Kidding aside, we have to get better there! On the other hand there are
16757  daily snapshots available at
16758 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
16759
16760 \end_inset
16761
16762 , and you can always build the very last version (hopefully with many bugs
16763  fixed, and features added) from the source code available at
16764 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
16765
16766 \end_inset
16767
16768 .
16769 \layout Section
16770
16771 Examples
16772 \begin_inset LatexCommand \index{Examples}
16773
16774 \end_inset
16775
16776
16777 \layout Standard
16778
16779 You'll find some small examples in the directory
16780 \emph on
16781 sdcc/device/examples/.
16782
16783 \emph default
16784 More examples and libraries are available at
16785 \emph on
16786  The SDCC Open Knowledge Resource
16787 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
16788
16789 \end_inset
16790
16791
16792 \emph default
16793 web site or at
16794 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
16795
16796 \end_inset
16797
16798 .
16799 \layout Comment
16800
16801 I did insert a reference to Paul's web site here although it seems rather
16802  dedicated to a specific 8032 board (I think it's okay because it f.e.
16803  shows LCD/Harddisc interface and has a free 8051 monitor.
16804  Independent 8032 board vendors face hard competition of heavily subsidized
16805  development boards anyway).
16806 \layout Comment
16807
16808 Maybe we should include some links to real world applications.
16809  Preferably pointer to pointers (one for each architecture) so this stays
16810  manageable here?
16811 \layout Section
16812
16813 Quality control
16814 \begin_inset LatexCommand \index{Quality control}
16815
16816 \end_inset
16817
16818
16819 \layout Standard
16820
16821 The compiler is passed through nightly compile and build checks.
16822  The so called
16823 \shape italic
16824 regression tests
16825 \shape default
16826
16827 \begin_inset LatexCommand \index{Regression test}
16828
16829 \end_inset
16830
16831  check that SDCC itself compiles flawlessly on several platforms and checks
16832  the quality of the code generated by SDCC by running the code through simulator
16833 s.
16834  There is a separate document
16835 \shape italic
16836 test_suite.pdf
16837 \begin_inset LatexCommand \index{Test suite}
16838
16839 \end_inset
16840
16841
16842 \shape default
16843  about this.
16844 \layout Standard
16845
16846 You'll find the test code in the directory
16847 \shape italic
16848 sdcc/support/regression
16849 \shape default
16850 .
16851  You can run these tests manually by running
16852 \family sans
16853 make
16854 \family default
16855  in this directory (or f.e.
16856
16857 \family sans
16858 \series bold
16859
16860 \begin_inset Quotes sld
16861 \end_inset
16862
16863 make test-mcs51
16864 \begin_inset Quotes srd
16865 \end_inset
16866
16867
16868 \family default
16869 \series default
16870  if you don't want to run the complete tests).
16871  The test code might also be interesting if you want to look for examples
16872 \begin_inset LatexCommand \index{Examples}
16873
16874 \end_inset
16875
16876  checking corner cases of SDCC or if you plan to submit patches
16877 \begin_inset LatexCommand \index{Patch submission}
16878
16879 \end_inset
16880
16881 .
16882 \layout Standard
16883
16884 The pic port uses a different set of regression tests, you'll find them
16885  in the directory
16886 \shape italic
16887 sdcc/src/regression
16888 \shape default
16889 .
16890 \layout Chapter
16891 \pagebreak_top
16892 SDCC Technical Data
16893 \layout Section
16894
16895 Optimizations
16896 \begin_inset LatexCommand \index{Optimizations}
16897
16898 \end_inset
16899
16900
16901 \layout Standard
16902
16903 SDCC performs a host of standard optimizations in addition to some MCU specific
16904  optimizations.
16905
16906 \layout Subsection
16907
16908 Sub-expression Elimination
16909 \begin_inset LatexCommand \index{Subexpression elimination}
16910
16911 \end_inset
16912
16913
16914 \layout Standard
16915
16916 The compiler does local and
16917 \emph on
16918 g
16919 \emph default
16920 lobal
16921 \emph on
16922 c
16923 \emph default
16924 ommon
16925 \emph on
16926 s
16927 \emph default
16928 ubexpression
16929 \emph on
16930 e
16931 \emph default
16932 limination, e.g.:
16933 \layout Verse
16934
16935
16936 \family typewriter
16937 i = x + y + 1;
16938 \newline
16939 j = x + y;
16940 \layout Standard
16941
16942 will be translated to
16943 \layout Verse
16944
16945
16946 \family typewriter
16947 iTemp = x + y;
16948 \newline
16949 i = iTemp + 1;
16950 \newline
16951 j = iTemp;
16952 \layout Standard
16953
16954 Some subexpressions are not as obvious as the above example, e.g.:
16955 \layout Verse
16956
16957
16958 \family typewriter
16959 a->b[i].c = 10;
16960 \newline
16961 a->b[i].d = 11;
16962 \layout Standard
16963
16964 In this case the address arithmetic a->b[i] will be computed only once;
16965  the equivalent code in C would be.
16966 \layout Verse
16967
16968
16969 \family typewriter
16970 iTemp = a->b[i];
16971 \newline
16972 iTemp.c = 10;
16973 \newline
16974 iTemp.d = 11;
16975 \layout Standard
16976
16977 The compiler will try to keep these temporary variables in registers.
16978 \layout Subsection
16979
16980 Dead-Code Elimination
16981 \begin_inset LatexCommand \index{Dead-code elimination}
16982
16983 \end_inset
16984
16985
16986 \layout Verse
16987
16988
16989 \family typewriter
16990 int global;
16991 \newline
16992
16993 \newline
16994 void f () {
16995 \newline
16996 \SpecialChar ~
16997 \SpecialChar ~
16998 int i;
16999 \newline
17000 \SpecialChar ~
17001 \SpecialChar ~
17002 i = 1; \SpecialChar ~
17003 \SpecialChar ~
17004 \SpecialChar ~
17005 \SpecialChar ~
17006 \SpecialChar ~
17007 /* dead store */
17008 \newline
17009 \SpecialChar ~
17010 \SpecialChar ~
17011 global = 1;\SpecialChar ~
17012 /* dead store */
17013 \newline
17014 \SpecialChar ~
17015 \SpecialChar ~
17016 global = 2;
17017 \newline
17018 \SpecialChar ~
17019 \SpecialChar ~
17020 return;
17021 \newline
17022 \SpecialChar ~
17023 \SpecialChar ~
17024 global = 3;\SpecialChar ~
17025 /* unreachable */
17026 \newline
17027 }
17028 \layout Standard
17029
17030 will be changed to
17031 \layout Verse
17032
17033
17034 \family typewriter
17035 int global;
17036 \newline
17037
17038 \newline
17039 void f () {
17040 \newline
17041 \SpecialChar ~
17042 \SpecialChar ~
17043 global = 2;
17044 \newline
17045 \SpecialChar ~
17046 \SpecialChar ~
17047 return;
17048 \newline
17049 }
17050 \layout Subsection
17051
17052 Copy-Propagation
17053 \begin_inset LatexCommand \index{Copy propagation}
17054
17055 \end_inset
17056
17057
17058 \layout Verse
17059
17060
17061 \family typewriter
17062 int f() {
17063 \newline
17064 \SpecialChar ~
17065 \SpecialChar ~
17066 int i, j;
17067 \newline
17068 \SpecialChar ~
17069 \SpecialChar ~
17070 i = 10;
17071 \newline
17072 \SpecialChar ~
17073 \SpecialChar ~
17074 j = i;
17075 \newline
17076 \SpecialChar ~
17077 \SpecialChar ~
17078 return j;
17079 \newline
17080 }
17081 \layout Standard
17082
17083 will be changed to
17084 \layout Verse
17085
17086
17087 \family typewriter
17088 int f() {
17089 \newline
17090 \SpecialChar ~
17091 \SpecialChar ~
17092 int i, j;
17093 \newline
17094 \SpecialChar ~
17095 \SpecialChar ~
17096 i = 10;
17097 \newline
17098 \SpecialChar ~
17099 \SpecialChar ~
17100 j = 10;
17101 \newline
17102 \SpecialChar ~
17103 \SpecialChar ~
17104 return 10;
17105 \newline
17106 }
17107 \layout Standard
17108
17109 Note: the dead stores created by this copy propagation will be eliminated
17110  by dead-code elimination.
17111 \layout Subsection
17112
17113 Loop Optimizations
17114 \begin_inset LatexCommand \index{Loop optimization}
17115
17116 \end_inset
17117
17118
17119 \layout Standard
17120
17121 Two types of loop optimizations are done by SDCC loop invariant lifting
17122  and strength reduction of loop induction variables.
17123  In addition to the strength reduction the optimizer marks the induction
17124  variables and the register allocator tries to keep the induction variables
17125  in registers for the duration of the loop.
17126  Because of this preference of the register allocator
17127 \begin_inset LatexCommand \index{Register allocation}
17128
17129 \end_inset
17130
17131 , loop induction optimization causes an increase in register pressure, which
17132  may cause unwanted spilling of other temporary variables into the stack
17133 \begin_inset LatexCommand \index{stack}
17134
17135 \end_inset
17136
17137  / data space.
17138  The compiler will generate a warning message when it is forced to allocate
17139  extra space either on the stack or data space.
17140  If this extra space allocation is undesirable then induction optimization
17141  can be eliminated either for the entire source file (with -
17142 \begin_inset ERT
17143 status Collapsed
17144
17145 \layout Standard
17146
17147 \backslash
17148 /
17149 \end_inset
17150
17151 -noinduction option) or for a given function only using #pragma\SpecialChar ~
17152 noinduction
17153 \begin_inset LatexCommand \index{\#pragma noinduction}
17154
17155 \end_inset
17156
17157 .
17158 \newline
17159
17160 \newline
17161 Loop Invariant:
17162 \layout Verse
17163
17164
17165 \family typewriter
17166 for (i = 0 ; i < 100 ; i ++)
17167 \newline
17168 \SpecialChar ~
17169 \SpecialChar ~
17170 \SpecialChar ~
17171 \SpecialChar ~
17172 f += k + l;
17173 \layout Standard
17174
17175 changed to
17176 \layout Verse
17177
17178
17179 \family typewriter
17180 itemp = k + l;
17181 \newline
17182 for (i = 0; i < 100; i++)
17183 \newline
17184 \SpecialChar ~
17185 \SpecialChar ~
17186 \SpecialChar ~
17187 \SpecialChar ~
17188 f += itemp;
17189 \layout Standard
17190
17191 As mentioned previously some loop invariants are not as apparent, all static
17192  address computations are also moved out of the loop.
17193 \newline
17194
17195 \newline
17196 Strength Reduction
17197 \begin_inset LatexCommand \index{Strength reduction}
17198
17199 \end_inset
17200
17201 , this optimization substitutes an expression by a cheaper expression:
17202 \layout Verse
17203
17204
17205 \family typewriter
17206 for (i=0;i < 100; i++)
17207 \newline
17208 \SpecialChar ~
17209 \SpecialChar ~
17210 \SpecialChar ~
17211 \SpecialChar ~
17212 ar[i*5] = i*3;
17213 \layout Standard
17214
17215 changed to
17216 \layout Verse
17217
17218
17219 \family typewriter
17220 itemp1 = 0;
17221 \newline
17222 itemp2 = 0;
17223 \newline
17224 for (i=0;i< 100;i++) {
17225 \newline
17226 \SpecialChar ~
17227 \SpecialChar ~
17228 \SpecialChar ~
17229 \SpecialChar ~
17230 ar[itemp1] = itemp2;
17231 \newline
17232 \SpecialChar ~
17233 \SpecialChar ~
17234 \SpecialChar ~
17235 \SpecialChar ~
17236 itemp1 += 5;
17237 \newline
17238 \SpecialChar ~
17239 \SpecialChar ~
17240 \SpecialChar ~
17241 \SpecialChar ~
17242 itemp2 += 3;
17243 \newline
17244 }
17245 \layout Standard
17246
17247 The more expensive multiplication
17248 \begin_inset LatexCommand \index{Multiplication}
17249
17250 \end_inset
17251
17252  is changed to a less expensive addition.
17253 \layout Subsection
17254
17255 Loop Reversing
17256 \begin_inset LatexCommand \index{Loop reversing}
17257
17258 \end_inset
17259
17260
17261 \layout Standard
17262
17263 This optimization is done to reduce the overhead of checking loop boundaries
17264  for every iteration.
17265  Some simple loops can be reversed and implemented using a
17266 \begin_inset Quotes eld
17267 \end_inset
17268
17269 decrement and jump if not zero
17270 \begin_inset Quotes erd
17271 \end_inset
17272
17273  instruction.
17274  SDCC checks for the following criterion to determine if a loop is reversible
17275  (note: more sophisticated compilers use data-dependency analysis to make
17276  this determination, SDCC uses a more simple minded analysis).
17277 \layout Itemize
17278
17279 The 'for' loop is of the form
17280 \newline
17281
17282 \newline
17283
17284 \family typewriter
17285 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
17286  += 1])
17287 \newline
17288 \SpecialChar ~
17289 \SpecialChar ~
17290 \SpecialChar ~
17291 \SpecialChar ~
17292 <for body>
17293 \layout Itemize
17294
17295 The <for body> does not contain
17296 \begin_inset Quotes eld
17297 \end_inset
17298
17299 continue
17300 \begin_inset Quotes erd
17301 \end_inset
17302
17303  or 'break
17304 \begin_inset Quotes erd
17305 \end_inset
17306
17307 .
17308 \layout Itemize
17309
17310 All goto's are contained within the loop.
17311 \layout Itemize
17312
17313 No function calls within the loop.
17314 \layout Itemize
17315
17316 The loop control variable <sym> is not assigned any value within the loop
17317 \layout Itemize
17318
17319 The loop control variable does NOT participate in any arithmetic operation
17320  within the loop.
17321 \layout Itemize
17322
17323 There are NO switch statements in the loop.
17324 \layout Subsection
17325
17326 Algebraic Simplifications
17327 \layout Standard
17328
17329 SDCC does numerous algebraic simplifications, the following is a small sub-set
17330  of these optimizations.
17331 \layout Verse
17332
17333
17334 \family typewriter
17335 i = j + 0;\SpecialChar ~
17336 \SpecialChar ~
17337 \SpecialChar ~
17338 \SpecialChar ~
17339  /* changed to: */\SpecialChar ~
17340 \SpecialChar ~
17341 \SpecialChar ~
17342 \SpecialChar ~
17343  i = j;
17344 \newline
17345 i /= 2;\SpecialChar ~
17346 \SpecialChar ~
17347 \SpecialChar ~
17348 \SpecialChar ~
17349 \SpecialChar ~
17350 \SpecialChar ~
17351 \SpecialChar ~
17352  /* changed to: */\SpecialChar ~
17353 \SpecialChar ~
17354 \SpecialChar ~
17355 \SpecialChar ~
17356  i >>= 1;
17357 \newline
17358 i = j - j;\SpecialChar ~
17359 \SpecialChar ~
17360 \SpecialChar ~
17361 \SpecialChar ~
17362  /* changed to: */\SpecialChar ~
17363 \SpecialChar ~
17364 \SpecialChar ~
17365 \SpecialChar ~
17366  i = 0;
17367 \newline
17368 i = j / 1;\SpecialChar ~
17369 \SpecialChar ~
17370 \SpecialChar ~
17371 \SpecialChar ~
17372  /* changed to: */\SpecialChar ~
17373 \SpecialChar ~
17374 \SpecialChar ~
17375 \SpecialChar ~
17376  i = j;
17377 \layout Standard
17378
17379 Note the subexpressions
17380 \begin_inset LatexCommand \index{Subexpression}
17381
17382 \end_inset
17383
17384  given above are generally introduced by macro expansions or as a result
17385  of copy/constant propagation.
17386 \layout Subsection
17387
17388 'switch' Statements
17389 \begin_inset LatexCommand \label{sub:'switch'-Statements}
17390
17391 \end_inset
17392
17393
17394 \begin_inset LatexCommand \index{switch statement}
17395
17396 \end_inset
17397
17398
17399 \layout Standard
17400
17401 SDCC changes switch statements to jump tables
17402 \begin_inset LatexCommand \index{jump tables}
17403
17404 \end_inset
17405
17406  when the following conditions are true.
17407
17408 \layout Itemize
17409
17410 The case labels are in numerical sequence, the labels need not be in order,
17411  and the starting number need not be one or zero.
17412 \begin_deeper
17413 \layout Verse
17414
17415
17416 \family typewriter
17417 switch(i) {\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 switch (i) {
17444 \newline
17445 \SpecialChar ~
17446 \SpecialChar ~
17447 \SpecialChar ~
17448 case 4: ...\SpecialChar ~
17449 \SpecialChar ~
17450 \SpecialChar ~
17451 \SpecialChar ~
17452 \SpecialChar ~
17453 \SpecialChar ~
17454 \SpecialChar ~
17455 \SpecialChar ~
17456 \SpecialChar ~
17457 \SpecialChar ~
17458 \SpecialChar ~
17459 \SpecialChar ~
17460 \SpecialChar ~
17461 \SpecialChar ~
17462 \SpecialChar ~
17463 \SpecialChar ~
17464 \SpecialChar ~
17465 \SpecialChar ~
17466 \SpecialChar ~
17467 \SpecialChar ~
17468 \SpecialChar ~
17469 \SpecialChar ~
17470 \SpecialChar ~
17471 \SpecialChar ~
17472 \SpecialChar ~
17473 \SpecialChar ~
17474 case 0: ...
17475
17476 \newline
17477 \SpecialChar ~
17478 \SpecialChar ~
17479 \SpecialChar ~
17480 case 5: ...\SpecialChar ~
17481 \SpecialChar ~
17482 \SpecialChar ~
17483 \SpecialChar ~
17484 \SpecialChar ~
17485 \SpecialChar ~
17486 \SpecialChar ~
17487 \SpecialChar ~
17488 \SpecialChar ~
17489 \SpecialChar ~
17490 \SpecialChar ~
17491 \SpecialChar ~
17492 \SpecialChar ~
17493 \SpecialChar ~
17494 \SpecialChar ~
17495 \SpecialChar ~
17496 \SpecialChar ~
17497 \SpecialChar ~
17498 \SpecialChar ~
17499 \SpecialChar ~
17500 \SpecialChar ~
17501 \SpecialChar ~
17502 \SpecialChar ~
17503 \SpecialChar ~
17504 \SpecialChar ~
17505 \SpecialChar ~
17506 case 1: ...
17507
17508 \newline
17509 \SpecialChar ~
17510 \SpecialChar ~
17511 \SpecialChar ~
17512 case 3: ...\SpecialChar ~
17513 \SpecialChar ~
17514 \SpecialChar ~
17515 \SpecialChar ~
17516 \SpecialChar ~
17517 \SpecialChar ~
17518 \SpecialChar ~
17519 \SpecialChar ~
17520 \SpecialChar ~
17521 \SpecialChar ~
17522 \SpecialChar ~
17523 \SpecialChar ~
17524 \SpecialChar ~
17525 \SpecialChar ~
17526 \SpecialChar ~
17527 \SpecialChar ~
17528 \SpecialChar ~
17529 \SpecialChar ~
17530 \SpecialChar ~
17531 \SpecialChar ~
17532 \SpecialChar ~
17533 \SpecialChar ~
17534 \SpecialChar ~
17535 \SpecialChar ~
17536 \SpecialChar ~
17537 \SpecialChar ~
17538 case 2: ...
17539
17540 \newline
17541 \SpecialChar ~
17542 \SpecialChar ~
17543 \SpecialChar ~
17544 case 6: ...\SpecialChar ~
17545 \SpecialChar ~
17546 \SpecialChar ~
17547 \SpecialChar ~
17548 \SpecialChar ~
17549 \SpecialChar ~
17550 \SpecialChar ~
17551 \SpecialChar ~
17552 \SpecialChar ~
17553 \SpecialChar ~
17554 \SpecialChar ~
17555 \SpecialChar ~
17556 \SpecialChar ~
17557 \SpecialChar ~
17558 \SpecialChar ~
17559 \SpecialChar ~
17560 \SpecialChar ~
17561 \SpecialChar ~
17562 \SpecialChar ~
17563 \SpecialChar ~
17564 \SpecialChar ~
17565 \SpecialChar ~
17566 \SpecialChar ~
17567 \SpecialChar ~
17568 \SpecialChar ~
17569 \SpecialChar ~
17570 case 3: ...
17571
17572 \newline
17573 }\SpecialChar ~
17574 \SpecialChar ~
17575 \SpecialChar ~
17576 \SpecialChar ~
17577 \SpecialChar ~
17578 \SpecialChar ~
17579 \SpecialChar ~
17580 \SpecialChar ~
17581 \SpecialChar ~
17582 \SpecialChar ~
17583 \SpecialChar ~
17584 \SpecialChar ~
17585 \SpecialChar ~
17586 \SpecialChar ~
17587 \SpecialChar ~
17588 \SpecialChar ~
17589 \SpecialChar ~
17590 \SpecialChar ~
17591 \SpecialChar ~
17592 \SpecialChar ~
17593 \SpecialChar ~
17594 \SpecialChar ~
17595 \SpecialChar ~
17596 \SpecialChar ~
17597 \SpecialChar ~
17598 \SpecialChar ~
17599 \SpecialChar ~
17600 \SpecialChar ~
17601 \SpecialChar ~
17602 \SpecialChar ~
17603 \SpecialChar ~
17604 \SpecialChar ~
17605 \SpecialChar ~
17606 \SpecialChar ~
17607 \SpecialChar ~
17608 \SpecialChar ~
17609 }
17610 \layout Standard
17611
17612 Both the above switch statements will be implemented using a jump-table.
17613  The example to the right side is slightly more efficient as the check for
17614  the lower boundary of the jump-table is not needed.
17615 \end_deeper
17616 \layout Itemize
17617
17618 The number of case labels is at least three, since it takes two conditional
17619  statements to handle the boundary conditions.
17620 \layout Itemize
17621
17622 The number of case labels is less than 84, since each label takes 3 bytes
17623  and a jump-table can be utmost 256 bytes long.
17624 \layout Standard
17625
17626 Switch statements which have gaps in the numeric sequence or those that
17627  have more that 84 case labels can be split into more than one switch statement
17628  for efficient code generation, e.g.:
17629 \layout Verse
17630
17631
17632 \family typewriter
17633 switch (i) {
17634 \newline
17635 \SpecialChar ~
17636 \SpecialChar ~
17637 case 1: ...
17638
17639 \newline
17640 \SpecialChar ~
17641 \SpecialChar ~
17642 case 2: ...
17643
17644 \newline
17645 \SpecialChar ~
17646 \SpecialChar ~
17647 case 3: ...
17648
17649 \newline
17650 \SpecialChar ~
17651 \SpecialChar ~
17652 case 4: ...
17653
17654 \newline
17655 \SpecialChar ~
17656 \SpecialChar ~
17657 case 9: ...
17658
17659 \newline
17660 \SpecialChar ~
17661 \SpecialChar ~
17662 case 10: ...
17663
17664 \newline
17665 \SpecialChar ~
17666 \SpecialChar ~
17667 case 11: ...
17668
17669 \newline
17670 \SpecialChar ~
17671 \SpecialChar ~
17672 case 12: ...
17673
17674 \newline
17675 }
17676 \layout Standard
17677
17678 If the above switch statement is broken down into two switch statements
17679 \layout Verse
17680
17681
17682 \family typewriter
17683 switch (i) {
17684 \newline
17685 \SpecialChar ~
17686 \SpecialChar ~
17687 case 1: ...
17688
17689 \newline
17690 \SpecialChar ~
17691 \SpecialChar ~
17692 case 2: ...
17693
17694 \newline
17695 \SpecialChar ~
17696 \SpecialChar ~
17697 case 3: ...
17698
17699 \newline
17700 \SpecialChar ~
17701 \SpecialChar ~
17702 case 4: ...
17703
17704 \newline
17705 }
17706 \layout Standard
17707
17708 and
17709 \layout Verse
17710
17711
17712 \family typewriter
17713 switch (i) {
17714 \newline
17715 \SpecialChar ~
17716 \SpecialChar ~
17717 case 9:\SpecialChar ~
17718 \SpecialChar ~
17719 ...
17720
17721 \newline
17722 \SpecialChar ~
17723 \SpecialChar ~
17724 case 10:\SpecialChar ~
17725 ...
17726
17727 \newline
17728 \SpecialChar ~
17729 \SpecialChar ~
17730 case 11:\SpecialChar ~
17731 ...
17732
17733 \newline
17734 \SpecialChar ~
17735 \SpecialChar ~
17736 case 12:\SpecialChar ~
17737 ...
17738
17739 \newline
17740 }
17741 \layout Standard
17742
17743 then both the switch statements will be implemented using jump-tables whereas
17744  the unmodified switch statement will not be.
17745  You might also consider inserting dummy cases 0 and 5 to 8 in this example.
17746
17747 \newline
17748 The pragma nojtbound
17749 \begin_inset LatexCommand \index{\#pragma nojtbound}
17750
17751 \end_inset
17752
17753  can be used to turn off checking the
17754 \emph on
17755 j
17756 \emph default
17757 ump
17758 \emph on
17759 t
17760 \emph default
17761 able
17762 \emph on
17763 bound
17764 \emph default
17765 aries.
17766  It has no effect if a default label is supplied.
17767  Use of this pragma is dangerous: if the switch argument is not matched
17768  by a case statement the processor will happily jump into Nirvana.
17769 \layout Subsection
17770
17771 Bit-shifting Operations
17772 \begin_inset LatexCommand \index{Bit shifting}
17773
17774 \end_inset
17775
17776 .
17777 \layout Standard
17778
17779 Bit shifting is one of the most frequently used operation in embedded programmin
17780 g.
17781  SDCC tries to implement bit-shift operations in the most efficient way
17782  possible, e.g.:
17783 \layout Verse
17784
17785
17786 \family typewriter
17787 unsigned char i;
17788 \newline
17789 ...
17790
17791 \newline
17792 i >>= 4;
17793 \newline
17794 ...
17795 \layout Standard
17796
17797 generates the following code:
17798 \layout Verse
17799
17800
17801 \family typewriter
17802 mov\SpecialChar ~
17803  a,_i
17804 \newline
17805 swap a
17806 \newline
17807 anl\SpecialChar ~
17808  a,#0x0f
17809 \newline
17810 mov\SpecialChar ~
17811  _i,a
17812 \layout Standard
17813
17814 In general SDCC will never setup a loop if the shift count is known.
17815  Another example:
17816 \layout Verse
17817
17818
17819 \family typewriter
17820 unsigned int i;
17821 \newline
17822 ...
17823
17824 \newline
17825 i >>= 9;
17826 \newline
17827 ...
17828 \layout Standard
17829
17830 will generate:
17831 \layout Verse
17832
17833
17834 \family typewriter
17835 mov\SpecialChar ~
17836 \SpecialChar ~
17837 a,(_i + 1)
17838 \newline
17839 mov\SpecialChar ~
17840 \SpecialChar ~
17841 (_i + 1),#0x00
17842 \newline
17843 clr\SpecialChar ~
17844 \SpecialChar ~
17845 c
17846 \newline
17847 rrc\SpecialChar ~
17848 \SpecialChar ~
17849 a
17850 \newline
17851 mov\SpecialChar ~
17852 \SpecialChar ~
17853 _i,a
17854 \layout Subsection
17855
17856 Bit-rotation
17857 \begin_inset LatexCommand \index{Bit rotation}
17858
17859 \end_inset
17860
17861
17862 \layout Standard
17863
17864 A special case of the bit-shift operation is bit rotation
17865 \begin_inset LatexCommand \index{rotating bits}
17866
17867 \end_inset
17868
17869 , SDCC recognizes the following expression to be a left bit-rotation:
17870 \layout Verse
17871
17872
17873 \family typewriter
17874 \series bold
17875 unsigned
17876 \series default
17877 \SpecialChar ~
17878 \SpecialChar ~
17879 char i;\SpecialChar ~
17880 \SpecialChar ~
17881 \SpecialChar ~
17882 \SpecialChar ~
17883 \SpecialChar ~
17884 \SpecialChar ~
17885 \SpecialChar ~
17886 \SpecialChar ~
17887 \SpecialChar ~
17888 \SpecialChar ~
17889 \SpecialChar ~
17890 /* unsigned is needed for rotation */
17891 \newline
17892 ...
17893
17894 \newline
17895 i = ((i << 1) | (i >> 7));
17896 \family default
17897
17898 \newline
17899
17900 \family typewriter
17901 ...
17902 \layout Standard
17903
17904 will generate the following code:
17905 \layout Verse
17906
17907
17908 \family typewriter
17909 mov\SpecialChar ~
17910 \SpecialChar ~
17911 a,_i
17912 \newline
17913 rl\SpecialChar ~
17914 \SpecialChar ~
17915 \SpecialChar ~
17916 a
17917 \newline
17918 mov\SpecialChar ~
17919 \SpecialChar ~
17920 _i,a
17921 \layout Standard
17922
17923 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
17924 ns of this case will also be recognized as bit-rotation, i.e.:
17925 \layout Verse
17926
17927
17928 \family typewriter
17929 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
17930 \layout Subsection
17931
17932 Nibble and Byte Swapping
17933 \layout Standard
17934
17935 Other special cases of the bit-shift operations are nibble or byte swapping
17936 \begin_inset LatexCommand \index{swapping nibbles/bytes}
17937
17938 \end_inset
17939
17940 , SDCC recognizes the following expressions:
17941 \layout Verse
17942
17943
17944 \family typewriter
17945 \series bold
17946 unsigned
17947 \series default
17948 \SpecialChar ~
17949 \SpecialChar ~
17950 char i;
17951 \newline
17952
17953 \series bold
17954 unsigned
17955 \series default
17956 \SpecialChar ~
17957 \SpecialChar ~
17958 int j;
17959 \newline
17960 ...
17961
17962 \newline
17963 i = ((i << 4) | (i >> 4));
17964 \family default
17965
17966 \newline
17967
17968 \family typewriter
17969 j = ((j << 8) | (j >> 8));
17970 \layout Standard
17971
17972 and generates a swap instruction for the nibble swapping
17973 \begin_inset LatexCommand \index{Nibble swapping}
17974
17975 \end_inset
17976
17977  or move instructions for the byte swapping
17978 \begin_inset LatexCommand \index{Byte swapping}
17979
17980 \end_inset
17981
17982 .
17983  The
17984 \begin_inset Quotes sld
17985 \end_inset
17986
17987 j
17988 \begin_inset Quotes srd
17989 \end_inset
17990
17991  example can be used to convert from little to big-endian or vice versa.
17992  If you want to change the endianness of a
17993 \emph on
17994 signed
17995 \emph default
17996  integer you have to cast to
17997 \family typewriter
17998 (unsigned int)
17999 \family default
18000  first.
18001 \layout Standard
18002
18003 Note that SDCC stores numbers in little-endian
18004 \begin_inset Foot
18005 collapsed false
18006
18007 \layout Standard
18008
18009 Usually 8-bit processors don't care much about endianness.
18010  This is not the case for the standard 8051 which only has an instruction
18011  to increment its
18012 \emph on
18013 dptr
18014 \emph default
18015
18016 \begin_inset LatexCommand \index{DPTR}
18017
18018 \end_inset
18019
18020 -datapointer
18021 \emph on
18022
18023 \emph default
18024 so little-endian is the more efficient byte order.
18025 \end_inset
18026
18027
18028 \begin_inset LatexCommand \index{little-endian}
18029
18030 \end_inset
18031
18032
18033 \begin_inset LatexCommand \index{Endianness}
18034
18035 \end_inset
18036
18037  format (i.e.
18038  lowest order first).
18039 \layout Subsection
18040
18041 Highest Order Bit
18042 \begin_inset LatexCommand \index{Highest Order Bit}
18043
18044 \end_inset
18045
18046
18047 \layout Standard
18048
18049 It is frequently required to obtain the highest order bit of an integral
18050  type (long, int, short or char types).
18051  SDCC recognizes the following expression to yield the highest order bit
18052  and generates optimized code for it, e.g.:
18053 \layout Verse
18054
18055
18056 \family typewriter
18057 unsigned int gint;
18058 \newline
18059
18060 \newline
18061 foo () {
18062 \newline
18063 \SpecialChar ~
18064 \SpecialChar ~
18065 unsigned char hob;
18066 \newline
18067 \SpecialChar ~
18068 \SpecialChar ~
18069 ...
18070
18071 \newline
18072 \SpecialChar ~
18073 \SpecialChar ~
18074 hob = (gint >> 15) & 1;
18075 \newline
18076 \SpecialChar ~
18077 \SpecialChar ~
18078 ..
18079
18080 \newline
18081 }
18082 \layout Standard
18083
18084 will generate the following code:
18085 \layout Verse
18086
18087
18088 \family typewriter
18089 \SpecialChar ~
18090 \SpecialChar ~
18091 \SpecialChar ~
18092 \SpecialChar ~
18093 \SpecialChar ~
18094 \SpecialChar ~
18095 \SpecialChar ~
18096 \SpecialChar ~
18097 \SpecialChar ~
18098 \SpecialChar ~
18099 \SpecialChar ~
18100 \SpecialChar ~
18101 \SpecialChar ~
18102 \SpecialChar ~
18103 \SpecialChar ~
18104 \SpecialChar ~
18105 \SpecialChar ~
18106 \SpecialChar ~
18107 \SpecialChar ~
18108 \SpecialChar ~
18109 \SpecialChar ~
18110 \SpecialChar ~
18111 \SpecialChar ~
18112 \SpecialChar ~
18113 \SpecialChar ~
18114  61 ;\SpecialChar ~
18115  hob.c 7
18116 \newline
18117 000A E5*01\SpecialChar ~
18118 \SpecialChar ~
18119 \SpecialChar ~
18120 \SpecialChar ~
18121 \SpecialChar ~
18122 \SpecialChar ~
18123 \SpecialChar ~
18124 \SpecialChar ~
18125 \SpecialChar ~
18126 \SpecialChar ~
18127 \SpecialChar ~
18128 \SpecialChar ~
18129 \SpecialChar ~
18130 \SpecialChar ~
18131 \SpecialChar ~
18132  62\SpecialChar ~
18133 \SpecialChar ~
18134 \SpecialChar ~
18135 \SpecialChar ~
18136 \SpecialChar ~
18137 \SpecialChar ~
18138 \SpecialChar ~
18139 \SpecialChar ~
18140  mov\SpecialChar ~
18141 \SpecialChar ~
18142  a,(_gint + 1)
18143 \newline
18144 000C 23\SpecialChar ~
18145 \SpecialChar ~
18146 \SpecialChar ~
18147 \SpecialChar ~
18148 \SpecialChar ~
18149 \SpecialChar ~
18150 \SpecialChar ~
18151 \SpecialChar ~
18152 \SpecialChar ~
18153 \SpecialChar ~
18154 \SpecialChar ~
18155 \SpecialChar ~
18156 \SpecialChar ~
18157 \SpecialChar ~
18158 \SpecialChar ~
18159 \SpecialChar ~
18160 \SpecialChar ~
18161 \SpecialChar ~
18162  63\SpecialChar ~
18163 \SpecialChar ~
18164 \SpecialChar ~
18165 \SpecialChar ~
18166 \SpecialChar ~
18167 \SpecialChar ~
18168 \SpecialChar ~
18169 \SpecialChar ~
18170  rl\SpecialChar ~
18171 \SpecialChar ~
18172 \SpecialChar ~
18173  a
18174 \newline
18175 000D 54 01\SpecialChar ~
18176 \SpecialChar ~
18177 \SpecialChar ~
18178 \SpecialChar ~
18179 \SpecialChar ~
18180 \SpecialChar ~
18181 \SpecialChar ~
18182 \SpecialChar ~
18183 \SpecialChar ~
18184 \SpecialChar ~
18185 \SpecialChar ~
18186 \SpecialChar ~
18187 \SpecialChar ~
18188 \SpecialChar ~
18189 \SpecialChar ~
18190  64\SpecialChar ~
18191 \SpecialChar ~
18192 \SpecialChar ~
18193 \SpecialChar ~
18194 \SpecialChar ~
18195 \SpecialChar ~
18196 \SpecialChar ~
18197 \SpecialChar ~
18198  anl\SpecialChar ~
18199 \SpecialChar ~
18200  a,#0x01
18201 \newline
18202 000F F5*02\SpecialChar ~
18203 \SpecialChar ~
18204 \SpecialChar ~
18205 \SpecialChar ~
18206 \SpecialChar ~
18207 \SpecialChar ~
18208 \SpecialChar ~
18209 \SpecialChar ~
18210 \SpecialChar ~
18211 \SpecialChar ~
18212 \SpecialChar ~
18213 \SpecialChar ~
18214 \SpecialChar ~
18215 \SpecialChar ~
18216 \SpecialChar ~
18217  65\SpecialChar ~
18218 \SpecialChar ~
18219 \SpecialChar ~
18220 \SpecialChar ~
18221 \SpecialChar ~
18222 \SpecialChar ~
18223 \SpecialChar ~
18224 \SpecialChar ~
18225  mov\SpecialChar ~
18226 \SpecialChar ~
18227  _foo_hob_1_1,a
18228 \layout Standard
18229
18230 Variations of this case however will
18231 \emph on
18232 not
18233 \emph default
18234  be recognized.
18235  It is a standard C expression, so I heartily recommend this be the only
18236  way to get the highest order bit, (it is portable).
18237  Of course it will be recognized even if it is embedded in other expressions,
18238  e.g.:
18239 \layout Verse
18240
18241
18242 \family typewriter
18243 xyz = gint + ((gint >> 15) & 1);
18244 \layout Standard
18245
18246 will still be recognized.
18247 \layout Subsection
18248
18249 Peephole Optimizer
18250 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
18251
18252 \end_inset
18253
18254
18255 \begin_inset LatexCommand \index{Peephole optimizer}
18256
18257 \end_inset
18258
18259
18260 \layout Standard
18261
18262 The compiler uses a rule based, pattern matching and re-writing mechanism
18263  for peep-hole optimization.
18264  It is inspired by
18265 \emph on
18266 copt
18267 \emph default
18268  a peep-hole optimizer by Christopher W.
18269  Fraser (cwfraser@microsoft.com).
18270  A default set of rules are compiled into the compiler, additional rules
18271  may be added with the
18272 \emph on
18273 -
18274 \begin_inset ERT
18275 status Collapsed
18276
18277 \layout Standard
18278
18279 \backslash
18280 /
18281 \end_inset
18282
18283 -peep-file
18284 \begin_inset LatexCommand \index{-\/-peep-file}
18285
18286 \end_inset
18287
18288  <filename>
18289 \emph default
18290  option.
18291  The rule language is best illustrated with examples.
18292 \layout Verse
18293
18294
18295 \family typewriter
18296 replace {
18297 \newline
18298 \SpecialChar ~
18299 \SpecialChar ~
18300 mov %1,a
18301 \newline
18302 \SpecialChar ~
18303 \SpecialChar ~
18304 mov a,%1
18305 \newline
18306 } by {
18307 \newline
18308 \SpecialChar ~
18309 \SpecialChar ~
18310 mov %1,a
18311 \newline
18312 }
18313 \layout Standard
18314
18315 The above rule will change the following assembly
18316 \begin_inset LatexCommand \index{Assembler routines}
18317
18318 \end_inset
18319
18320  sequence:
18321 \layout Verse
18322
18323
18324 \family typewriter
18325 mov r1,a
18326 \newline
18327 mov a,r1
18328 \layout Standard
18329
18330 to
18331 \layout Verse
18332
18333
18334 \family typewriter
18335 mov r1,a
18336 \layout Standard
18337
18338 Note: All occurrences of a
18339 \emph on
18340 %n
18341 \emph default
18342  (pattern variable) must denote the same string.
18343  With the above rule, the assembly sequence:
18344 \layout Verse
18345
18346
18347 \family typewriter
18348 mov r1,a
18349 \newline
18350 mov a,r2
18351 \layout Standard
18352
18353 will remain unmodified.
18354 \newline
18355
18356 \newline
18357 Other special case optimizations may be added by the user (via
18358 \emph on
18359 -
18360 \begin_inset ERT
18361 status Collapsed
18362
18363 \layout Standard
18364
18365 \backslash
18366 /
18367 \end_inset
18368
18369 -peep-file option
18370 \emph default
18371 ).
18372  E.g.
18373  some variants of the 8051 MCU allow only
18374 \family typewriter
18375 ajmp
18376 \family default
18377  and
18378 \family typewriter
18379 acall
18380 \family default
18381 .
18382  The following two rules will change all
18383 \family typewriter
18384 ljmp
18385 \family default
18386  and
18387 \family typewriter
18388 lcall
18389 \family default
18390  to
18391 \family typewriter
18392 ajmp
18393 \family default
18394  and
18395 \family typewriter
18396 acall
18397 \layout Verse
18398
18399
18400 \family typewriter
18401 replace { lcall %1 } by { acall %1 }
18402 \newline
18403 replace { ljmp %1 } by { ajmp %1 }
18404 \layout Standard
18405
18406 The
18407 \emph on
18408 inline-assembler code
18409 \emph default
18410  is also passed through the peep hole optimizer, thus the peephole optimizer
18411  can also be used as an assembly level macro expander.
18412  The rules themselves are MCU dependent whereas the rule language infra-structur
18413 e is MCU independent.
18414  Peephole optimization rules for other MCU can be easily programmed using
18415  the rule language.
18416 \newline
18417
18418 \newline
18419 The syntax for a rule is as follows:
18420 \layout Verse
18421
18422
18423 \family typewriter
18424 rule := replace [ restart ] '{' <assembly sequence> '
18425 \backslash
18426 n'
18427 \newline
18428 \SpecialChar ~
18429  \SpecialChar ~
18430  \SpecialChar ~
18431  \SpecialChar ~
18432  \SpecialChar ~
18433  \SpecialChar ~
18434  \SpecialChar ~
18435  \SpecialChar ~
18436  \SpecialChar ~
18437  \SpecialChar ~
18438  \SpecialChar ~
18439  \SpecialChar ~
18440  \SpecialChar ~
18441  \SpecialChar ~
18442  '}' by '{' '
18443 \backslash
18444 n'
18445 \newline
18446 \SpecialChar ~
18447  \SpecialChar ~
18448  \SpecialChar ~
18449  \SpecialChar ~
18450  \SpecialChar ~
18451  \SpecialChar ~
18452  \SpecialChar ~
18453  \SpecialChar ~
18454  \SpecialChar ~
18455  \SpecialChar ~
18456  \SpecialChar ~
18457  \SpecialChar ~
18458  \SpecialChar ~
18459  \SpecialChar ~
18460  \SpecialChar ~
18461  \SpecialChar ~
18462  <assembly sequence> '
18463 \backslash
18464 n'
18465 \newline
18466 \SpecialChar ~
18467  \SpecialChar ~
18468  \SpecialChar ~
18469  \SpecialChar ~
18470  \SpecialChar ~
18471  \SpecialChar ~
18472  \SpecialChar ~
18473  \SpecialChar ~
18474  \SpecialChar ~
18475  \SpecialChar ~
18476  \SpecialChar ~
18477  \SpecialChar ~
18478  \SpecialChar ~
18479  \SpecialChar ~
18480  '}' [if <functionName> ] '
18481 \backslash
18482 n'
18483 \layout Standard
18484
18485 <assembly sequence> := assembly instruction (each instruction including
18486  labels must be on a separate line).
18487 \newline
18488
18489 \newline
18490 The optimizer will apply to the rules one by one from the top in the sequence
18491  of their appearance, it will terminate when all rules are exhausted.
18492  If the 'restart' option is specified, then the optimizer will start matching
18493  the rules again from the top, this option for a rule is expensive (performance)
18494 , it is intended to be used in situations where a transformation will trigger
18495  the same rule again.
18496  An example of this (not a good one, it has side effects) is the following
18497  rule:
18498 \layout Verse
18499
18500
18501 \family typewriter
18502 replace restart {
18503 \newline
18504 \SpecialChar ~
18505 \SpecialChar ~
18506 pop %1
18507 \newline
18508 \SpecialChar ~
18509 \SpecialChar ~
18510 push %1 } by {
18511 \newline
18512 \SpecialChar ~
18513 \SpecialChar ~
18514 ; nop
18515 \newline
18516 }
18517 \layout Standard
18518
18519 Note that the replace pattern cannot be a blank, but can be a comment line.
18520  Without the 'restart' option only the innermost 'pop' 'push' pair would
18521  be eliminated, i.e.:
18522 \layout Verse
18523
18524
18525 \family typewriter
18526 pop ar1
18527 \newline
18528 pop ar2
18529 \newline
18530 push ar2
18531 \newline
18532 push ar1
18533 \layout Standard
18534
18535 would result in:
18536 \layout Verse
18537
18538
18539 \family typewriter
18540 pop ar1
18541 \newline
18542 ; nop
18543 \newline
18544 push ar1
18545 \layout Standard
18546
18547
18548 \emph on
18549 with
18550 \emph default
18551  the restart option the rule will be applied again to the resulting code
18552  and then all the pop-push pairs will be eliminated to yield:
18553 \layout Verse
18554
18555
18556 \family typewriter
18557 ; nop
18558 \newline
18559 ; nop
18560 \layout Standard
18561
18562 A conditional function can be attached to a rule.
18563  Attaching rules are somewhat more involved, let me illustrate this with
18564  an example.
18565 \layout Verse
18566
18567
18568 \family typewriter
18569 replace {
18570 \newline
18571 \SpecialChar ~
18572  \SpecialChar ~
18573  \SpecialChar ~
18574 ljmp %5
18575 \newline
18576 %2:
18577 \newline
18578 } by {
18579 \newline
18580 \SpecialChar ~
18581  \SpecialChar ~
18582  \SpecialChar ~
18583 sjmp %5
18584 \newline
18585 %2:
18586 \newline
18587 } if labelInRange
18588 \layout Standard
18589
18590 The optimizer does a look-up of a function name table defined in function
18591
18592 \emph on
18593 callFuncByName
18594 \emph default
18595  in the source file SDCCpeeph.c, with the name
18596 \emph on
18597 labelInRange
18598 \emph default
18599 .
18600  If it finds a corresponding entry the function is called.
18601  Note there can be no parameters specified for these functions, in this
18602  case the use of
18603 \emph on
18604 %5
18605 \emph default
18606  is crucial, since the function
18607 \emph on
18608 labelInRange
18609 \emph default
18610  expects to find the label in that particular variable (the hash table containin
18611 g the variable bindings is passed as a parameter).
18612  If you want to code more such functions, take a close look at the function
18613  labelInRange and the calling mechanism in source file SDCCpeeph.c.
18614  Currently implemented are
18615 \emph on
18616 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
18617  24bitMode, portIsDS390, 24bitModeAndPortDS390
18618 \emph default
18619 and
18620 \emph on
18621  notVolatile
18622 \emph default
18623 .
18624 \layout Standard
18625
18626 I know this whole thing is a little kludgey, but maybe some day we will
18627  have some better means.
18628  If you are looking at this file, you will see the default rules that are
18629  compiled into the compiler, you can add your own rules in the default set
18630  there if you get tired of specifying the -
18631 \begin_inset ERT
18632 status Collapsed
18633
18634 \layout Standard
18635
18636 \backslash
18637 /
18638 \end_inset
18639
18640 -peep-file option.
18641 \layout Section
18642
18643 ANSI-Compliance
18644 \begin_inset LatexCommand \index{ANSI-compliance}
18645
18646 \end_inset
18647
18648
18649 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
18650
18651 \end_inset
18652
18653
18654 \layout Standard
18655
18656 Deviations from the compliance:
18657 \layout Itemize
18658
18659 functions are not always reentrant
18660 \begin_inset LatexCommand \index{reentrant}
18661
18662 \end_inset
18663
18664 .
18665 \layout Itemize
18666
18667 structures cannot be assigned values directly, cannot be passed as function
18668  parameters or assigned to each other and cannot be a return value from
18669  a function, e.g.:
18670 \begin_deeper
18671 \layout Verse
18672
18673
18674 \family typewriter
18675 struct s { ...
18676  };
18677 \newline
18678 struct s s1, s2;
18679 \newline
18680 foo()
18681 \newline
18682 {
18683 \newline
18684 \SpecialChar ~
18685 \SpecialChar ~
18686 \SpecialChar ~
18687 \SpecialChar ~
18688 ...
18689
18690 \newline
18691 \SpecialChar ~
18692 \SpecialChar ~
18693 \SpecialChar ~
18694 \SpecialChar ~
18695 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
18696 \newline
18697 \SpecialChar ~
18698 \SpecialChar ~
18699 \SpecialChar ~
18700 \SpecialChar ~
18701 ...
18702
18703 \newline
18704 }
18705 \newline
18706 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
18707  */
18708 \newline
18709 {
18710 \newline
18711 \SpecialChar ~
18712 \SpecialChar ~
18713 \SpecialChar ~
18714 \SpecialChar ~
18715 struct s rets;
18716 \newline
18717 \SpecialChar ~
18718 \SpecialChar ~
18719 \SpecialChar ~
18720 \SpecialChar ~
18721 ...
18722
18723 \newline
18724 \SpecialChar ~
18725 \SpecialChar ~
18726 \SpecialChar ~
18727 \SpecialChar ~
18728 return rets;/* is invalid in SDCC although allowed in ANSI */
18729 \newline
18730 }
18731 \end_deeper
18732 \layout Itemize
18733
18734 'long long
18735 \begin_inset LatexCommand \index{long long (not supported)}
18736
18737 \end_inset
18738
18739 ' (64 bit integers
18740 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
18741
18742 \end_inset
18743
18744 ) not supported.
18745 \layout Itemize
18746
18747 'double
18748 \begin_inset LatexCommand \index{double (not supported)}
18749
18750 \end_inset
18751
18752 ' precision floating point
18753 \begin_inset LatexCommand \index{Floating point support}
18754
18755 \end_inset
18756
18757 not supported.
18758 \layout Itemize
18759
18760 No support for setjmp
18761 \begin_inset LatexCommand \index{setjmp (not supported)}
18762
18763 \end_inset
18764
18765  and longjmp
18766 \begin_inset LatexCommand \index{longjmp (not supported)}
18767
18768 \end_inset
18769
18770  (for now).
18771 \layout Itemize
18772
18773 Old K&R style
18774 \begin_inset LatexCommand \index{K\&R style}
18775
18776 \end_inset
18777
18778  function declarations are NOT allowed.
18779 \begin_deeper
18780 \layout Verse
18781
18782
18783 \family typewriter
18784 foo(i,j) /* this old style of function declarations */
18785 \newline
18786 int i,j; /* are valid in ANSI but not valid in SDCC */
18787 \newline
18788 {
18789 \newline
18790 \SpecialChar ~
18791 \SpecialChar ~
18792 \SpecialChar ~
18793 \SpecialChar ~
18794 ...
18795
18796 \newline
18797 }
18798 \end_deeper
18799 \layout Itemize
18800
18801 functions declared as pointers
18802 \begin_inset LatexCommand \index{Pointer (to function)}
18803
18804 \end_inset
18805
18806
18807 \begin_inset LatexCommand \index{function pointers}
18808
18809 \end_inset
18810
18811  must be dereferenced during the call.
18812 \begin_deeper
18813 \layout Verse
18814
18815
18816 \family typewriter
18817 int (*foo)();
18818 \newline
18819 ...
18820
18821 \newline
18822 /* has to be called like this */
18823 \newline
18824 (*foo)(); /* ANSI standard allows calls to be made like 'foo()' */
18825 \end_deeper
18826 \layout Section
18827
18828 Cyclomatic Complexity
18829 \begin_inset LatexCommand \index{Cyclomatic complexity}
18830
18831 \end_inset
18832
18833
18834 \layout Standard
18835
18836 Cyclomatic complexity of a function is defined as the number of independent
18837  paths the program can take during execution of the function.
18838  This is an important number since it defines the number test cases you
18839  have to generate to validate the function.
18840  The accepted industry standard for complexity number is 10, if the cyclomatic
18841  complexity reported by SDCC exceeds 10 you should think about simplification
18842  of the function logic.
18843  Note that the complexity level is not related to the number of lines of
18844  code in a function.
18845  Large functions can have low complexity, and small functions can have large
18846  complexity levels.
18847
18848 \newline
18849
18850 \newline
18851 SDCC uses the following formula to compute the complexity:
18852 \newline
18853
18854 \layout Standard
18855
18856 complexity = (number of edges in control flow graph) - (number of nodes
18857  in control flow graph) + 2;
18858 \newline
18859
18860 \newline
18861 Having said that the industry standard is 10, you should be aware that in
18862  some cases it be may unavoidable to have a complexity level of less than
18863  10.
18864  For example if you have switch statement with more than 10 case labels,
18865  each case label adds one to the complexity level.
18866  The complexity level is by no means an absolute measure of the algorithmic
18867  complexity of the function, it does however provide a good starting point
18868  for which functions you might look at for further optimization.
18869 \layout Section
18870
18871 Notes on supported Processors
18872 \layout Subsection
18873
18874 MCS51 variants
18875 \begin_inset LatexCommand \label{sub:MCS51-variants}
18876
18877 \end_inset
18878
18879
18880 \begin_inset LatexCommand \index{MCS51 variants}
18881
18882 \end_inset
18883
18884
18885 \layout Standard
18886
18887 MCS51 processors are available from many vendors and come in many different
18888  flavours.
18889  While they might differ considerably in respect to Special Function Registers
18890  the core MCS51 is usually not modified or is kept compatible.
18891
18892 \layout Subsubsection*
18893
18894 pdata access by SFR
18895 \layout Standard
18896
18897 With the upcome of devices with internal xdata and flash memory devices
18898  using port P2
18899 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
18900
18901 \end_inset
18902
18903  as dedicated I/O port is becoming more popular.
18904  Switching the high byte for pdata
18905 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
18906
18907 \end_inset
18908
18909  access which was formerly done by port P2 is then achieved by a Special
18910  Function Register
18911 \begin_inset LatexCommand \index{sfr}
18912
18913 \end_inset
18914
18915 .
18916  In well-established MCS51 tradition the address of this
18917 \emph on
18918 sfr
18919 \emph default
18920  is where the chip designers decided to put it.
18921  Needless to say that they didn't agree on a common name either.
18922  As pdata addressing is used in the startup code for the initialization
18923  of xdata variables a separate startup code should be used as described
18924  in section
18925 \begin_inset LatexCommand \ref{sub:Startup-Code}
18926
18927 \end_inset
18928
18929 .
18930 \layout Subsubsection*
18931
18932 Other Features available by SFR
18933 \layout Standard
18934
18935 Some MCS51 variants offer features like Double DPTR
18936 \begin_inset LatexCommand \index{DPTR}
18937
18938 \end_inset
18939
18940 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
18941  These are currently not used for the MCS51 port.
18942  If you absolutely need them you can fall back to inline assembly or submit
18943  a patch to SDCC.
18944 \layout Subsection
18945
18946 The Z80 and gbz80 port
18947 \layout Standard
18948
18949 SDCC can target both the Zilog
18950 \begin_inset LatexCommand \index{Z80}
18951
18952 \end_inset
18953
18954  and the Nintendo Gameboy's Z80-like gbz80
18955 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
18956
18957 \end_inset
18958
18959 .
18960  The Z80 port is passed through the same
18961 \emph on
18962 regressions tests
18963 \begin_inset LatexCommand \index{Regression test}
18964
18965 \end_inset
18966
18967
18968 \emph default
18969  as the MCS51 and DS390 ports, so floating point support, support for long
18970  variables and bitfield support is fine.
18971  See mailing lists and forums about interrupt routines.
18972 \layout Standard
18973
18974 As always, the code is the authoritative reference - see z80/ralloc.c and
18975  z80/gen.c.
18976  The stack
18977 \begin_inset LatexCommand \index{stack}
18978
18979 \end_inset
18980
18981  frame is similar to that generated by the IAR Z80 compiler.
18982  IX is used as the base pointer, HL is used as a temporary register, and
18983  BC and DE are available for holding variables.
18984  IY is currently unused.
18985  Return values
18986 \begin_inset LatexCommand \index{return value}
18987
18988 \end_inset
18989
18990  are stored in HL.
18991  One bad side effect of using IX as the base pointer is that a functions
18992  stack frame is limited to 127 bytes - this will be fixed in a later version.
18993 \layout Subsection
18994
18995 The HC08 port
18996 \layout Standard
18997
18998 The port to the Motorola HC08
18999 \begin_inset LatexCommand \index{HC08}
19000
19001 \end_inset
19002
19003  family has been added in October 2003, thank you Erik!
19004 \layout Subsection
19005
19006 The PIC14 port
19007 \layout Standard
19008
19009 The 14bit PIC
19010 \begin_inset LatexCommand \index{PIC14}
19011
19012 \end_inset
19013
19014  port still requires a major effort from the development community.
19015  However it can work for very simple code.
19016 \newline
19017
19018 \newline
19019
19020 \bar under
19021 C code and 14bit PIC code page
19022 \begin_inset LatexCommand \index{code page (pic14)}
19023
19024 \end_inset
19025
19026  and RAM banks
19027 \bar default
19028
19029 \begin_inset LatexCommand \index{RAM bank (pic14)}
19030
19031 \end_inset
19032
19033
19034 \newline
19035 The linker organizes allocation for the code page and RAM banks.
19036  It does not have intimate knowledge of the code flow.
19037  It will put all the code section of a single asm file into a single code
19038  page.
19039  In order to make use of multiple code pages, separate asm files must be
19040  used.
19041  The compiler treats all functions of a single C file as being in the same
19042  code page unless it is non static.
19043  The compiler treats all local variables of a single C file as being in
19044  the same RAM bank unless it is an extern.
19045 \newline
19046
19047 \newline
19048 To get the best follow these guide lines:
19049 \layout Enumerate
19050
19051 make local functions static, as non static functions require code page selection
19052  overhead.
19053 \layout Enumerate
19054
19055 Make local variables static as extern variables require RAM bank selection
19056  overhead.
19057 \layout Enumerate
19058
19059 For devices that have multiple code pages it is more efficient to use the
19060  same number of files as pages, i.e.
19061  for the 16F877 use 4 separate files and i.e.
19062  for the 16F874 use 2 separate files.
19063  This way the linker can put the code for each file into different code
19064  pages and the compiler can allocate reusable variables more efficiently
19065  and there's less page selection overhead.
19066  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
19067  instruction set) use 'unsigned char' whereever possible instead of 'int'.
19068 \layout Standard
19069
19070
19071 \bar under
19072 Creating a device include file
19073 \bar default
19074
19075 \newline
19076 For generating a device include file use the support perl script inc2h.pl
19077  kept in directory support/script.
19078 \newline
19079
19080 \newline
19081
19082 \bar under
19083 Interrupt code
19084 \bar default
19085
19086 \newline
19087 For the interrupt function, use the keyword 'interrupt'
19088 \begin_inset LatexCommand \index{interrupt}
19089
19090 \end_inset
19091
19092  with level number of 0 (PIC14 only has 1 interrupt so this number is only
19093  there to avoid a syntax error - it ought to be fixed).
19094  E.g.:
19095 \layout Verse
19096
19097
19098 \family typewriter
19099 void Intr(void) interrupt 0
19100 \newline
19101 {
19102 \newline
19103 \SpecialChar ~
19104 \SpecialChar ~
19105 T0IF = 0; /* Clear timer interrupt */
19106 \newline
19107 }
19108 \layout Standard
19109
19110
19111 \bar under
19112 Linking and assembling
19113 \bar default
19114
19115 \newline
19116 For assembling you can use either GPUTILS' gpasm.exe or MPLAB's mpasmwin.exe.
19117  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
19118  If you use MPLAB and an interrupt function then the linker script file
19119  vectors section will need to be enlarged to link with mplink.
19120 \newline
19121
19122 \newline
19123 Here is a
19124 \family typewriter
19125 Makefile
19126 \family default
19127  using GPUTILS:
19128 \layout Verse
19129
19130
19131 \family typewriter
19132 .c.o:
19133 \newline
19134 \SpecialChar ~
19135 \SpecialChar ~
19136 \SpecialChar ~
19137 \SpecialChar ~
19138 \SpecialChar ~
19139 \SpecialChar ~
19140 \SpecialChar ~
19141 \SpecialChar ~
19142 sdcc -S -V -mpic14 -p16F877 $<
19143 \newline
19144 \SpecialChar ~
19145 \SpecialChar ~
19146 \SpecialChar ~
19147 \SpecialChar ~
19148 \SpecialChar ~
19149 \SpecialChar ~
19150 \SpecialChar ~
19151 \SpecialChar ~
19152 gpasm -c $*.asm
19153 \newline
19154
19155 \newline
19156 $(PRJ).hex: $(OBJS)
19157 \newline
19158 \SpecialChar ~
19159 \SpecialChar ~
19160 \SpecialChar ~
19161 \SpecialChar ~
19162 \SpecialChar ~
19163 \SpecialChar ~
19164 \SpecialChar ~
19165 \SpecialChar ~
19166 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
19167 \layout Standard
19168
19169 Here is a
19170 \family typewriter
19171 Makefile
19172 \family default
19173  using MPLAB:
19174 \layout Verse
19175
19176
19177 \family typewriter
19178 .c.o:
19179 \newline
19180 \SpecialChar ~
19181 \SpecialChar ~
19182 \SpecialChar ~
19183 \SpecialChar ~
19184 \SpecialChar ~
19185 \SpecialChar ~
19186 \SpecialChar ~
19187 \SpecialChar ~
19188 sdcc -S -V -mpic14 -p16F877 $<
19189 \newline
19190 \SpecialChar ~
19191 \SpecialChar ~
19192 \SpecialChar ~
19193 \SpecialChar ~
19194 \SpecialChar ~
19195 \SpecialChar ~
19196 \SpecialChar ~
19197 \SpecialChar ~
19198 mpasmwin /q /o $*.asm
19199 \newline
19200
19201 \newline
19202 $(PRJ).hex: $(OBJS)
19203 \newline
19204 \SpecialChar ~
19205 \SpecialChar ~
19206 \SpecialChar ~
19207 \SpecialChar ~
19208 \SpecialChar ~
19209 \SpecialChar ~
19210 \SpecialChar ~
19211 \SpecialChar ~
19212 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
19213 \layout Subsection
19214
19215 The PIC16
19216 \begin_inset LatexCommand \index{PIC16}
19217
19218 \end_inset
19219
19220  port
19221 \layout Standard
19222
19223 You'll find some additional notes about this port in the file src/pic16/NOTES.
19224 \layout Section
19225
19226 Retargetting for other Processors
19227 \layout Standard
19228
19229 The issues for retargetting the compiler are far too numerous to be covered
19230  by this document.
19231  What follows is a brief description of each of the seven phases of the
19232  compiler and its MCU dependency.
19233 \layout Itemize
19234
19235 Parsing the source and building the annotated parse tree.
19236  This phase is largely MCU independent (except for the language extensions).
19237  Syntax & semantic checks are also done in this phase, along with some initial
19238  optimizations like back patching labels and the pattern matching optimizations
19239  like bit-rotation etc.
19240 \layout Itemize
19241
19242 The second phase involves generating an intermediate code which can be easy
19243  manipulated during the later phases.
19244  This phase is entirely MCU independent.
19245  The intermediate code generation assumes the target machine has unlimited
19246  number of registers, and designates them with the name iTemp.
19247  The compiler can be made to dump a human readable form of the code generated
19248  by using the -
19249 \begin_inset ERT
19250 status Collapsed
19251
19252 \layout Standard
19253
19254 \backslash
19255 /
19256 \end_inset
19257
19258 -dumpraw option.
19259 \layout Itemize
19260
19261 This phase does the bulk of the standard optimizations and is also MCU independe
19262 nt.
19263  This phase can be broken down into several sub-phases:
19264 \newline
19265
19266 \newline
19267 Break down intermediate code (iCode) into basic blocks.
19268 \newline
19269 Do control flow & data flow analysis on the basic blocks.
19270 \newline
19271 Do local common subexpression elimination, then global subexpression elimination
19272 \newline
19273 Dead code elimination
19274 \newline
19275 Loop optimizations
19276 \newline
19277 If loop optimizations caused any changes then do 'global subexpression eliminati
19278 on' and 'dead code elimination' again.
19279 \layout Itemize
19280
19281 This phase determines the live-ranges; by live range I mean those iTemp
19282  variables defined by the compiler that still survive after all the optimization
19283 s.
19284  Live range analysis
19285 \begin_inset LatexCommand \index{Live range analysis}
19286
19287 \end_inset
19288
19289  is essential for register allocation, since these computation determines
19290  which of these iTemps will be assigned to registers, and for how long.
19291 \layout Itemize
19292
19293 Phase five is register allocation.
19294  There are two parts to this process.
19295 \newline
19296
19297 \newline
19298 The first part I call 'register packing' (for lack of a better term).
19299  In this case several MCU specific expression folding is done to reduce
19300  register pressure.
19301 \newline
19302
19303 \newline
19304 The second part is more MCU independent and deals with allocating registers
19305  to the remaining live ranges.
19306  A lot of MCU specific code does creep into this phase because of the limited
19307  number of index registers available in the 8051.
19308 \layout Itemize
19309
19310 The Code generation phase is (unhappily), entirely MCU dependent and very
19311  little (if any at all) of this code can be reused for other MCU.
19312  However the scheme for allocating a homogenized assembler operand for each
19313  iCode operand may be reused.
19314 \layout Itemize
19315
19316 As mentioned in the optimization section the peep-hole optimizer is rule
19317  based system, which can reprogrammed for other MCUs.
19318 \layout Chapter
19319
19320 Compiler internals
19321 \begin_inset LatexCommand \index{Compiler internals}
19322
19323 \end_inset
19324
19325
19326 \layout Section
19327
19328 The anatomy of the compiler
19329 \begin_inset LatexCommand \label{sub:The-anatomy-of}
19330
19331 \end_inset
19332
19333
19334 \layout Standard
19335
19336
19337 \shape italic
19338 This is an excerpt from an article published in Circuit Cellar Magazine
19339  in august 2000.
19340  It's a little outdated (the compiler is much more efficient now and user/develo
19341 per friendly), but pretty well exposes the guts of it all.
19342 \shape default
19343
19344 \newline
19345
19346 \newline
19347 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
19348  It is fairly easy to retarget for other 8-bit MCU.
19349  Here we take a look at some of the internals of the compiler.
19350
19351 \layout Paragraph*
19352
19353 Parsing
19354 \begin_inset LatexCommand \index{Parsing}
19355
19356 \end_inset
19357
19358
19359 \layout Standard
19360
19361 Parsing the input source file and creating an AST (Annotated Syntax Tree
19362 \begin_inset LatexCommand \index{Annotated syntax tree}
19363
19364 \end_inset
19365
19366 ).
19367  This phase also involves propagating types (annotating each node of the
19368  parse tree with type information) and semantic analysis.
19369  There are some MCU specific parsing rules.
19370  For example the storage classes, the extended storage classes are MCU specific
19371  while there may be a xdata storage class for 8051 there is no such storage
19372  class for z80 or Atmel AVR.
19373  SDCC allows MCU specific storage class extensions, i.e.
19374  xdata will be treated as a storage class specifier when parsing 8051 C
19375  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
19376  C code.
19377 \layout Paragraph*
19378
19379 Generating iCode
19380 \begin_inset LatexCommand \index{iCode}
19381
19382 \end_inset
19383
19384
19385 \layout Standard
19386
19387 Intermediate code generation.
19388  In this phase the AST is broken down into three-operand form (iCode).
19389  These three operand forms are represented as doubly linked lists.
19390  ICode is the term given to the intermediate form generated by the compiler.
19391  ICode example section shows some examples of iCode generated for some simple
19392  C source functions.
19393 \layout Paragraph*
19394
19395 Optimizations
19396 \begin_inset LatexCommand \index{Optimizations}
19397
19398 \end_inset
19399
19400 .
19401 \layout Standard
19402
19403 Bulk of the target independent optimizations is performed in this phase.
19404  The optimizations include constant propagation, common sub-expression eliminati
19405 on, loop invariant code movement, strength reduction of loop induction variables
19406  and dead-code elimination.
19407 \layout Paragraph*
19408
19409 Live range analysis
19410 \begin_inset LatexCommand \index{Live range analysis}
19411
19412 \end_inset
19413
19414
19415 \layout Standard
19416
19417 During intermediate code generation phase, the compiler assumes the target
19418  machine has infinite number of registers and generates a lot of temporary
19419  variables.
19420  The live range computation determines the lifetime of each of these compiler-ge
19421 nerated temporaries.
19422  A picture speaks a thousand words.
19423  ICode example sections show the live range annotations for each of the
19424  operand.
19425  It is important to note here, each iCode is assigned a number in the order
19426  of its execution in the function.
19427  The live ranges are computed in terms of these numbers.
19428  The from number is the number of the iCode which first defines the operand
19429  and the to number signifies the iCode which uses this operand last.
19430 \layout Paragraph*
19431
19432 Register Allocation
19433 \begin_inset LatexCommand \index{Register allocation}
19434
19435 \end_inset
19436
19437
19438 \layout Standard
19439
19440 The register allocation determines the type and number of registers needed
19441  by each operand.
19442  In most MCUs only a few registers can be used for indirect addressing.
19443  In case of 8051 for example the registers R0 & R1 can be used to indirectly
19444  address the internal ram and DPTR to indirectly address the external ram.
19445  The compiler will try to allocate the appropriate register to pointer variables
19446  if it can.
19447  ICode example section shows the operands annotated with the registers assigned
19448  to them.
19449  The compiler will try to keep operands in registers as much as possible;
19450  there are several schemes the compiler uses to do achieve this.
19451  When the compiler runs out of registers the compiler will check to see
19452  if there are any live operands which is not used or defined in the current
19453  basic block being processed, if there are any found then it will push that
19454  operand and use the registers in this block, the operand will then be popped
19455  at the end of the basic block.
19456
19457 \layout Standard
19458
19459 There are other MCU specific considerations in this phase.
19460  Some MCUs have an accumulator; very short-lived operands could be assigned
19461  to the accumulator instead of a general-purpose register.
19462 \layout Paragraph*
19463
19464 Code generation
19465 \layout Standard
19466
19467 Figure II gives a table of iCode operations supported by the compiler.
19468  The code generation involves translating these operations into corresponding
19469  assembly code for the processor.
19470  This sounds overly simple but that is the essence of code generation.
19471  Some of the iCode operations are generated on a MCU specific manner for
19472  example, the z80 port does not use registers to pass parameters so the
19473  SEND and RECV iCode operations will not be generated, and it also does
19474  not support JUMPTABLES.
19475
19476 \newline
19477
19478 \series bold
19479 \shape italic
19480 \color red
19481 <Where is Figure II ?>
19482 \layout Paragraph*
19483
19484 ICode Example
19485 \begin_inset LatexCommand \index{iCode}
19486
19487 \end_inset
19488
19489
19490 \layout Standard
19491
19492 This section shows some details of iCode.
19493  The example C code does not do anything useful; it is used as an example
19494  to illustrate the intermediate code generated by the compiler.
19495 \layout Verse
19496
19497
19498 \family typewriter
19499 1.\SpecialChar ~
19500 xdata int * p;
19501 \newline
19502 2.\SpecialChar ~
19503 int gint;
19504 \newline
19505 3.\SpecialChar ~
19506 /* This function does nothing useful.
19507  It is used
19508 \newline
19509 4.\SpecialChar ~
19510 \SpecialChar ~
19511 \SpecialChar ~
19512 \SpecialChar ~
19513 for the purpose of explaining iCode */
19514 \newline
19515 5.\SpecialChar ~
19516 short function (data int *x)
19517 \newline
19518 6.\SpecialChar ~
19519 {
19520 \newline
19521 7.\SpecialChar ~
19522 \SpecialChar ~
19523 \SpecialChar ~
19524 short i=10; \SpecialChar ~
19525 \SpecialChar ~
19526 /* dead initialization eliminated */
19527 \newline
19528 8.\SpecialChar ~
19529 \SpecialChar ~
19530 \SpecialChar ~
19531 short sum=10; /* dead initialization eliminated */
19532 \newline
19533 9.\SpecialChar ~
19534 \SpecialChar ~
19535 \SpecialChar ~
19536 short mul;
19537 \newline
19538 10.\SpecialChar ~
19539 \SpecialChar ~
19540 int j ;
19541 \newline
19542 11.\SpecialChar ~
19543 \SpecialChar ~
19544 while (*x) *x++ = *p++;
19545 \newline
19546 12.\SpecialChar ~
19547 \SpecialChar ~
19548 \SpecialChar ~
19549 \SpecialChar ~
19550 sum = 0 ;
19551 \newline
19552 13.\SpecialChar ~
19553 \SpecialChar ~
19554 mul = 0;
19555 \newline
19556 14.\SpecialChar ~
19557 \SpecialChar ~
19558 /* compiler detects i,j to be induction variables */
19559 \newline
19560 15.\SpecialChar ~
19561 \SpecialChar ~
19562 for (i = 0, j = 10 ; i < 10 ; i++, j
19563 \family default
19564 -
19565 \begin_inset ERT
19566 status Collapsed
19567
19568 \layout Standard
19569
19570 \backslash
19571 /
19572 \end_inset
19573
19574 -
19575 \family typewriter
19576 ) {
19577 \newline
19578 16.\SpecialChar ~
19579 \SpecialChar ~
19580 \SpecialChar ~
19581 \SpecialChar ~
19582 sum += i;
19583 \newline
19584 17.\SpecialChar ~
19585 \SpecialChar ~
19586 \SpecialChar ~
19587 \SpecialChar ~
19588 mul += i * 3; \SpecialChar ~
19589 \SpecialChar ~
19590 /* this multiplication remains */
19591 \newline
19592 18.\SpecialChar ~
19593 \SpecialChar ~
19594 \SpecialChar ~
19595 \SpecialChar ~
19596 gint += j * 3;\SpecialChar ~
19597 \SpecialChar ~
19598 /* this multiplication changed to addition */
19599 \newline
19600 19.\SpecialChar ~
19601 \SpecialChar ~
19602 }
19603 \newline
19604 20.\SpecialChar ~
19605 \SpecialChar ~
19606 return sum+mul;
19607 \newline
19608 21.\SpecialChar ~
19609 }
19610 \layout Standard
19611
19612 In addition to the operands each iCode contains information about the filename
19613  and line it corresponds to in the source file.
19614  The first field in the listing should be interpreted as follows:
19615 \newline
19616
19617 \shape italic
19618 \size footnotesize
19619 Filename(linenumber: iCode Execution sequence number : ICode hash table
19620  key : loop depth of the iCode).
19621 \shape default
19622 \size default
19623
19624 \newline
19625 Then follows the human readable form of the ICode operation.
19626  Each operand of this triplet form can be of three basic types a) compiler
19627  generated temporary b) user defined variable c) a constant value.
19628  Note that local variables and parameters are replaced by compiler generated
19629  temporaries.
19630  Live ranges
19631 \begin_inset LatexCommand \index{Live range analysis}
19632
19633 \end_inset
19634
19635  are computed only for temporaries (i.e.
19636  live ranges are not computed for global variables).
19637  Registers
19638 \begin_inset LatexCommand \index{Register allocation}
19639
19640 \end_inset
19641
19642  are allocated for temporaries only.
19643  Operands are formatted in the following manner:
19644 \newline
19645
19646 \shape italic
19647 \size footnotesize
19648 Operand Name [lr live-from : live-to ] { type information } [ registers
19649  allocated ].
19650 \shape default
19651 \size default
19652
19653 \newline
19654 As mentioned earlier the live ranges are computed in terms of the execution
19655  sequence number of the iCodes, for example
19656 \newline
19657 the iTemp0 is live from (i.e.
19658  first defined in iCode with execution sequence number 3, and is last used
19659  in the iCode with sequence number 5).
19660  For induction variables such as iTemp21 the live range computation extends
19661  the lifetime from the start to the end of the loop.
19662 \newline
19663 The register allocator used the live range information to allocate registers,
19664  the same registers may be used for different temporaries if their live
19665  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
19666  iTemp17 since their live ranges do not overlap.
19667  In addition the allocator also takes into consideration the type and usage
19668  of a temporary, for example itemp6 is a pointer to near space and is used
19669  as to fetch data from (i.e.
19670  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
19671  Some short lived temporaries are allocated to special registers which have
19672  meaning to the code generator e.g.
19673  iTemp13 is allocated to a pseudo register CC which tells the back end that
19674  the temporary is used only for a conditional jump the code generation makes
19675  use of this information to optimize a compare and jump ICode.
19676 \newline
19677 There are several loop optimizations
19678 \begin_inset LatexCommand \index{Loop optimization}
19679
19680 \end_inset
19681
19682  performed by the compiler.
19683  It can detect induction variables iTemp21(i) and iTemp23(j).
19684  Also note the compiler does selective strength reduction
19685 \begin_inset LatexCommand \index{Strength reduction}
19686
19687 \end_inset
19688
19689 , i.e.
19690  the multiplication of an induction variable in line 18 (gint = j * 3) is
19691  changed to addition, a new temporary iTemp17 is allocated and assigned
19692  a initial value, a constant 3 is then added for each iteration of the loop.
19693  The compiler does not change the multiplication
19694 \begin_inset LatexCommand \index{Multiplication}
19695
19696 \end_inset
19697
19698  in line 17 however since the processor does support an 8 * 8 bit multiplication.
19699 \newline
19700 Note the dead code elimination
19701 \begin_inset LatexCommand \index{Dead-code elimination}
19702
19703 \end_inset
19704
19705  optimization eliminated the dead assignments in line 7 & 8 to I and sum
19706  respectively.
19707 \newline
19708
19709 \layout Standard
19710
19711
19712 \size footnotesize
19713 Sample.c (5:1:0:0) _entry($9) :
19714 \layout Standard
19715
19716
19717 \size footnotesize
19718 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
19719 \layout Standard
19720
19721
19722 \size footnotesize
19723 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
19724 \layout Standard
19725
19726
19727 \size footnotesize
19728 Sample.c(11:4:53:0) preHeaderLbl0($11) :
19729 \layout Standard
19730
19731
19732 \size footnotesize
19733 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
19734  * int}[r2]
19735 \layout Standard
19736
19737
19738 \size footnotesize
19739 Sample.c(11:6:5:1) _whilecontinue_0($1) :
19740 \layout Standard
19741
19742
19743 \size footnotesize
19744 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
19745  int}[r0]]
19746 \layout Standard
19747
19748
19749 \size footnotesize
19750 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
19751 \layout Standard
19752
19753
19754 \size footnotesize
19755 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
19756  * int}
19757 \layout Standard
19758
19759
19760 \size footnotesize
19761 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
19762  {short}
19763 \layout Standard
19764
19765
19766 \size footnotesize
19767 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
19768  * int}[DPTR]]
19769 \layout Standard
19770
19771
19772 \size footnotesize
19773 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
19774 }[r2 r3]
19775 \layout Standard
19776
19777
19778 \size footnotesize
19779 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
19780  * int}[r0] + 0x2 {short}
19781 \layout Standard
19782
19783
19784 \size footnotesize
19785 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
19786 \layout Standard
19787
19788
19789 \size footnotesize
19790 Sample.c(11:17:21:0)_whilebreak_0($3) :
19791 \layout Standard
19792
19793
19794 \size footnotesize
19795 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
19796 \layout Standard
19797
19798
19799 \size footnotesize
19800 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
19801 \layout Standard
19802
19803
19804 \size footnotesize
19805 Sample.c(15:20:54:0)preHeaderLbl1($13) :
19806 \layout Standard
19807
19808
19809 \size footnotesize
19810 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
19811 \layout Standard
19812
19813
19814 \size footnotesize
19815 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
19816 \layout Standard
19817
19818
19819 \size footnotesize
19820 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
19821 \layout Standard
19822
19823
19824 \size footnotesize
19825 Sample.c(15:24:26:1)_forcond_0($4) :
19826 \layout Standard
19827
19828
19829 \size footnotesize
19830 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
19831  < 0xa {short}
19832 \layout Standard
19833
19834
19835 \size footnotesize
19836 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
19837 \layout Standard
19838
19839
19840 \size footnotesize
19841 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
19842  + ITemp21 [lr21:38]{short}[r4]
19843 \layout Standard
19844
19845
19846 \size footnotesize
19847 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
19848  * 0x3 {short}
19849 \layout Standard
19850
19851
19852 \size footnotesize
19853 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
19854  + iTemp15 [lr29:30]{short}[r1]
19855 \layout Standard
19856
19857
19858 \size footnotesize
19859 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
19860  r0]- 0x3 {short}
19861 \layout Standard
19862
19863
19864 \size footnotesize
19865 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
19866 int}[r7 r0]
19867 \layout Standard
19868
19869
19870 \size footnotesize
19871 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
19872  + 0x1 {short}
19873 \layout Standard
19874
19875
19876 \size footnotesize
19877 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
19878  r6]- 0x1 {short}
19879 \layout Standard
19880
19881
19882 \size footnotesize
19883 Sample.c(19:38:47:1) goto _forcond_0($4)
19884 \layout Standard
19885
19886
19887 \size footnotesize
19888 Sample.c(19:39:48:0)_forbreak_0($7) :
19889 \layout Standard
19890
19891
19892 \size footnotesize
19893 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
19894  + ITemp11 [lr19:40]{short}[r3]
19895 \layout Standard
19896
19897
19898 \size footnotesize
19899 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
19900 \layout Standard
19901
19902
19903 \size footnotesize
19904 Sample.c(20:42:51:0)_return($8) :
19905 \layout Standard
19906
19907
19908 \size footnotesize
19909 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
19910 \size default
19911
19912 \newline
19913
19914 \newline
19915 Finally the code generated for this function:
19916 \newline
19917
19918 \layout Standard
19919
19920
19921 \size footnotesize
19922 .area DSEG (DATA)
19923 \layout Standard
19924
19925
19926 \size footnotesize
19927 _p::
19928 \layout Standard
19929
19930
19931 \size footnotesize
19932 \SpecialChar ~
19933 \SpecialChar ~
19934 .ds 2
19935 \layout Standard
19936
19937
19938 \size footnotesize
19939 _gint::
19940 \layout Standard
19941
19942
19943 \size footnotesize
19944 \SpecialChar ~
19945 \SpecialChar ~
19946 .ds 2
19947 \layout Standard
19948
19949
19950 \size footnotesize
19951 ; sample.c 5
19952 \layout Standard
19953
19954
19955 \size footnotesize
19956 ; ----------------------------------------------
19957 \layout Standard
19958
19959
19960 \size footnotesize
19961 ; function function
19962 \layout Standard
19963
19964
19965 \size footnotesize
19966 ; ----------------------------------------------
19967 \layout Standard
19968
19969
19970 \size footnotesize
19971 _function:
19972 \layout Standard
19973
19974
19975 \size footnotesize
19976 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
19977 \layout Standard
19978
19979
19980 \size footnotesize
19981 \SpecialChar ~
19982 \SpecialChar ~
19983 mov r2,dpl
19984 \layout Standard
19985
19986
19987 \size footnotesize
19988 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
19989 \layout Standard
19990
19991
19992 \size footnotesize
19993 \SpecialChar ~
19994 \SpecialChar ~
19995 mov ar0,r2
19996 \layout Standard
19997
19998
19999 \size footnotesize
20000 ;_whilecontinue_0($1) :
20001 \layout Standard
20002
20003
20004 \size footnotesize
20005 00101$:
20006 \layout Standard
20007
20008
20009 \size footnotesize
20010 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
20011 \layout Standard
20012
20013
20014 \size footnotesize
20015 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
20016 \layout Standard
20017
20018
20019 \size footnotesize
20020 \SpecialChar ~
20021 \SpecialChar ~
20022 mov ar2,@r0
20023 \layout Standard
20024
20025
20026 \size footnotesize
20027 \SpecialChar ~
20028 \SpecialChar ~
20029 inc r0
20030 \layout Standard
20031
20032
20033 \size footnotesize
20034 \SpecialChar ~
20035 \SpecialChar ~
20036 mov ar3,@r0
20037 \layout Standard
20038
20039
20040 \size footnotesize
20041 \SpecialChar ~
20042 \SpecialChar ~
20043 dec r0
20044 \layout Standard
20045
20046
20047 \size footnotesize
20048 \SpecialChar ~
20049 \SpecialChar ~
20050 mov a,r2
20051 \layout Standard
20052
20053
20054 \size footnotesize
20055 \SpecialChar ~
20056 \SpecialChar ~
20057 orl a,r3
20058 \layout Standard
20059
20060
20061 \size footnotesize
20062 \SpecialChar ~
20063 \SpecialChar ~
20064 jz 00103$
20065 \layout Standard
20066
20067
20068 \size footnotesize
20069 00114$:
20070 \layout Standard
20071
20072
20073 \size footnotesize
20074 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
20075 \layout Standard
20076
20077
20078 \size footnotesize
20079 \SpecialChar ~
20080 \SpecialChar ~
20081 mov dpl,_p
20082 \layout Standard
20083
20084
20085 \size footnotesize
20086 \SpecialChar ~
20087 \SpecialChar ~
20088 mov dph,(_p + 1)
20089 \layout Standard
20090
20091
20092 \size footnotesize
20093 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
20094 \layout Standard
20095
20096
20097 \size footnotesize
20098 \SpecialChar ~
20099 \SpecialChar ~
20100 mov a,#0x02
20101 \layout Standard
20102
20103
20104 \size footnotesize
20105 \SpecialChar ~
20106 \SpecialChar ~
20107 add a,_p
20108 \layout Standard
20109
20110
20111 \size footnotesize
20112 \SpecialChar ~
20113 \SpecialChar ~
20114 mov _p,a
20115 \layout Standard
20116
20117
20118 \size footnotesize
20119 \SpecialChar ~
20120 \SpecialChar ~
20121 clr a
20122 \layout Standard
20123
20124
20125 \size footnotesize
20126 \SpecialChar ~
20127 \SpecialChar ~
20128 addc a,(_p + 1)
20129 \layout Standard
20130
20131
20132 \size footnotesize
20133 \SpecialChar ~
20134 \SpecialChar ~
20135 mov (_p + 1),a
20136 \layout Standard
20137
20138
20139 \size footnotesize
20140 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
20141 \layout Standard
20142
20143
20144 \size footnotesize
20145 \SpecialChar ~
20146 \SpecialChar ~
20147 movx a,@dptr
20148 \layout Standard
20149
20150
20151 \size footnotesize
20152 \SpecialChar ~
20153 \SpecialChar ~
20154 mov r2,a
20155 \layout Standard
20156
20157
20158 \size footnotesize
20159 \SpecialChar ~
20160 \SpecialChar ~
20161 inc dptr
20162 \layout Standard
20163
20164
20165 \size footnotesize
20166 \SpecialChar ~
20167 \SpecialChar ~
20168 movx a,@dptr
20169 \layout Standard
20170
20171
20172 \size footnotesize
20173 \SpecialChar ~
20174 \SpecialChar ~
20175 mov r3,a
20176 \layout Standard
20177
20178
20179 \size footnotesize
20180 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
20181 \layout Standard
20182
20183
20184 \size footnotesize
20185 \SpecialChar ~
20186 \SpecialChar ~
20187 mov @r0,ar2
20188 \layout Standard
20189
20190
20191 \size footnotesize
20192 \SpecialChar ~
20193 \SpecialChar ~
20194 inc r0
20195 \layout Standard
20196
20197
20198 \size footnotesize
20199 \SpecialChar ~
20200 \SpecialChar ~
20201 mov @r0,ar3
20202 \layout Standard
20203
20204
20205 \size footnotesize
20206 ; iTemp6 [lr5:16]{_near * int}[r0] =
20207 \layout Standard
20208
20209
20210 \size footnotesize
20211 ; iTemp6 [lr5:16]{_near * int}[r0] +
20212 \layout Standard
20213
20214
20215 \size footnotesize
20216 ; 0x2 {short}
20217 \layout Standard
20218
20219
20220 \size footnotesize
20221 \SpecialChar ~
20222 \SpecialChar ~
20223 inc r0
20224 \layout Standard
20225
20226
20227 \size footnotesize
20228 ; goto _whilecontinue_0($1)
20229 \layout Standard
20230
20231
20232 \size footnotesize
20233 \SpecialChar ~
20234 \SpecialChar ~
20235 sjmp 00101$
20236 \layout Standard
20237
20238
20239 \size footnotesize
20240 ; _whilebreak_0($3) :
20241 \layout Standard
20242
20243
20244 \size footnotesize
20245 00103$:
20246 \layout Standard
20247
20248
20249 \size footnotesize
20250 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
20251 \layout Standard
20252
20253
20254 \size footnotesize
20255 \SpecialChar ~
20256 \SpecialChar ~
20257 mov r2,#0x00
20258 \layout Standard
20259
20260
20261 \size footnotesize
20262 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
20263 \layout Standard
20264
20265
20266 \size footnotesize
20267 \SpecialChar ~
20268 \SpecialChar ~
20269 mov r3,#0x00
20270 \layout Standard
20271
20272
20273 \size footnotesize
20274 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
20275 \layout Standard
20276
20277
20278 \size footnotesize
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 mov r4,#0x00
20282 \layout Standard
20283
20284
20285 \size footnotesize
20286 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
20287 \layout Standard
20288
20289
20290 \size footnotesize
20291 \SpecialChar ~
20292 \SpecialChar ~
20293 mov r5,#0x0A
20294 \layout Standard
20295
20296
20297 \size footnotesize
20298 \SpecialChar ~
20299 \SpecialChar ~
20300 mov r6,#0x00
20301 \layout Standard
20302
20303
20304 \size footnotesize
20305 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
20306 \layout Standard
20307
20308
20309 \size footnotesize
20310 \SpecialChar ~
20311 \SpecialChar ~
20312 mov r7,#0x1E
20313 \layout Standard
20314
20315
20316 \size footnotesize
20317 \SpecialChar ~
20318 \SpecialChar ~
20319 mov r0,#0x00
20320 \layout Standard
20321
20322
20323 \size footnotesize
20324 ; _forcond_0($4) :
20325 \layout Standard
20326
20327
20328 \size footnotesize
20329 00104$:
20330 \layout Standard
20331
20332
20333 \size footnotesize
20334 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
20335 \layout Standard
20336
20337
20338 \size footnotesize
20339 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
20340 \layout Standard
20341
20342
20343 \size footnotesize
20344 \SpecialChar ~
20345 \SpecialChar ~
20346 clr c
20347 \layout Standard
20348
20349
20350 \size footnotesize
20351 \SpecialChar ~
20352 \SpecialChar ~
20353 mov a,r4
20354 \layout Standard
20355
20356
20357 \size footnotesize
20358 \SpecialChar ~
20359 \SpecialChar ~
20360 xrl a,#0x80
20361 \layout Standard
20362
20363
20364 \size footnotesize
20365 \SpecialChar ~
20366 \SpecialChar ~
20367 subb a,#0x8a
20368 \layout Standard
20369
20370
20371 \size footnotesize
20372 \SpecialChar ~
20373 \SpecialChar ~
20374 jnc 00107$
20375 \layout Standard
20376
20377
20378 \size footnotesize
20379 00115$:
20380 \layout Standard
20381
20382
20383 \size footnotesize
20384 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
20385 \layout Standard
20386
20387
20388 \size footnotesize
20389 ; iTemp21 [lr21:38]{short}[r4]
20390 \layout Standard
20391
20392
20393 \size footnotesize
20394 \SpecialChar ~
20395 \SpecialChar ~
20396 mov a,r4
20397 \layout Standard
20398
20399
20400 \size footnotesize
20401 \SpecialChar ~
20402 \SpecialChar ~
20403 add a,r2
20404 \layout Standard
20405
20406
20407 \size footnotesize
20408 \SpecialChar ~
20409 \SpecialChar ~
20410 mov r2,a
20411 \layout Standard
20412
20413
20414 \size footnotesize
20415 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
20416 \layout Standard
20417
20418
20419 \size footnotesize
20420 \SpecialChar ~
20421 \SpecialChar ~
20422 mov b,#0x03
20423 \layout Standard
20424
20425
20426 \size footnotesize
20427 \SpecialChar ~
20428 \SpecialChar ~
20429 mov a,r4
20430 \layout Standard
20431
20432
20433 \size footnotesize
20434 \SpecialChar ~
20435 \SpecialChar ~
20436 mul ab
20437 \layout Standard
20438
20439
20440 \size footnotesize
20441 \SpecialChar ~
20442 \SpecialChar ~
20443 mov r1,a
20444 \layout Standard
20445
20446
20447 \size footnotesize
20448 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
20449 \layout Standard
20450
20451
20452 \size footnotesize
20453 ; iTemp15 [lr29:30]{short}[r1]
20454 \layout Standard
20455
20456
20457 \size footnotesize
20458 \SpecialChar ~
20459 \SpecialChar ~
20460 add a,r3
20461 \layout Standard
20462
20463
20464 \size footnotesize
20465 \SpecialChar ~
20466 \SpecialChar ~
20467 mov r3,a
20468 \layout Standard
20469
20470
20471 \size footnotesize
20472 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
20473 \layout Standard
20474
20475
20476 \size footnotesize
20477 \SpecialChar ~
20478 \SpecialChar ~
20479 mov a,r7
20480 \layout Standard
20481
20482
20483 \size footnotesize
20484 \SpecialChar ~
20485 \SpecialChar ~
20486 add a,#0xfd
20487 \layout Standard
20488
20489
20490 \size footnotesize
20491 \SpecialChar ~
20492 \SpecialChar ~
20493 mov r7,a
20494 \layout Standard
20495
20496
20497 \size footnotesize
20498 \SpecialChar ~
20499 \SpecialChar ~
20500 mov a,r0
20501 \layout Standard
20502
20503
20504 \size footnotesize
20505 \SpecialChar ~
20506 \SpecialChar ~
20507 addc a,#0xff
20508 \layout Standard
20509
20510
20511 \size footnotesize
20512 \SpecialChar ~
20513 \SpecialChar ~
20514 mov r0,a
20515 \layout Standard
20516
20517
20518 \size footnotesize
20519 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
20520 \layout Standard
20521
20522
20523 \size footnotesize
20524 \SpecialChar ~
20525 \SpecialChar ~
20526 mov a,r7
20527 \layout Standard
20528
20529
20530 \size footnotesize
20531 \SpecialChar ~
20532 \SpecialChar ~
20533 add a,_gint
20534 \layout Standard
20535
20536
20537 \size footnotesize
20538 \SpecialChar ~
20539 \SpecialChar ~
20540 mov _gint,a
20541 \layout Standard
20542
20543
20544 \size footnotesize
20545 \SpecialChar ~
20546 \SpecialChar ~
20547 mov a,r0
20548 \layout Standard
20549
20550
20551 \size footnotesize
20552 \SpecialChar ~
20553 \SpecialChar ~
20554 addc a,(_gint + 1)
20555 \layout Standard
20556
20557
20558 \size footnotesize
20559 \SpecialChar ~
20560 \SpecialChar ~
20561 mov (_gint + 1),a
20562 \layout Standard
20563
20564
20565 \size footnotesize
20566 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
20567 \layout Standard
20568
20569
20570 \size footnotesize
20571 \SpecialChar ~
20572 \SpecialChar ~
20573 inc r4
20574 \layout Standard
20575
20576
20577 \size footnotesize
20578 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
20579 \layout Standard
20580
20581
20582 \size footnotesize
20583 \SpecialChar ~
20584 \SpecialChar ~
20585 dec r5
20586 \layout Standard
20587
20588
20589 \size footnotesize
20590 \SpecialChar ~
20591 \SpecialChar ~
20592 cjne r5,#0xff,00104$
20593 \layout Standard
20594
20595
20596 \size footnotesize
20597 \SpecialChar ~
20598 \SpecialChar ~
20599 dec r6
20600 \layout Standard
20601
20602
20603 \size footnotesize
20604 ; goto _forcond_0($4)
20605 \layout Standard
20606
20607
20608 \size footnotesize
20609 \SpecialChar ~
20610 \SpecialChar ~
20611 sjmp 00104$
20612 \layout Standard
20613
20614
20615 \size footnotesize
20616 ; _forbreak_0($7) :
20617 \layout Standard
20618
20619
20620 \size footnotesize
20621 00107$:
20622 \layout Standard
20623
20624
20625 \size footnotesize
20626 ; ret iTemp24 [lr40:41]{short}
20627 \layout Standard
20628
20629
20630 \size footnotesize
20631 \SpecialChar ~
20632 \SpecialChar ~
20633 mov a,r3
20634 \layout Standard
20635
20636
20637 \size footnotesize
20638 \SpecialChar ~
20639 \SpecialChar ~
20640 add a,r2
20641 \layout Standard
20642
20643
20644 \size footnotesize
20645 \SpecialChar ~
20646 \SpecialChar ~
20647 mov dpl,a
20648 \layout Standard
20649
20650
20651 \size footnotesize
20652 ; _return($8) :
20653 \layout Standard
20654
20655
20656 \size footnotesize
20657 00108$:
20658 \layout Standard
20659
20660
20661 \size footnotesize
20662 \SpecialChar ~
20663 \SpecialChar ~
20664 ret
20665 \newline
20666
20667 \layout Section
20668
20669 A few words about basic block successors, predecessors and dominators
20670 \layout Standard
20671
20672 Successors are basic blocks
20673 \begin_inset LatexCommand \index{Basic blocks}
20674
20675 \end_inset
20676
20677  that might execute after this basic block.
20678 \newline
20679 Predecessors are basic blocks that might execute before reaching this basic
20680  block.
20681 \newline
20682 Dominators are basic blocks that WILL execute before reaching this basic
20683  block.
20684 \newline
20685
20686 \layout Standard
20687
20688 [basic block 1]
20689 \layout Standard
20690
20691 if (something)
20692 \layout Standard
20693
20694 \SpecialChar ~
20695 \SpecialChar ~
20696 \SpecialChar ~
20697 \SpecialChar ~
20698 [basic block 2]
20699 \layout Standard
20700
20701 else
20702 \layout Standard
20703
20704 \SpecialChar ~
20705 \SpecialChar ~
20706 \SpecialChar ~
20707 \SpecialChar ~
20708 [basic block 3]
20709 \layout Standard
20710
20711 [basic block 4]
20712 \newline
20713
20714 \layout Standard
20715
20716 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
20717 \layout Standard
20718
20719 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
20720 \layout Standard
20721
20722 c) domVect of [BB4] = BB1 ...
20723  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
20724  was executed.
20725 \layout Chapter
20726
20727 Acknowledgments
20728 \layout Standard
20729
20730
20731 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
20732
20733 \end_inset
20734
20735
20736 \newline
20737
20738 \newline
20739
20740 \emph on
20741 Thanks to all the other volunteer developers who have helped with coding,
20742  testing, web-page creation, distribution sets, etc.
20743  You know who you are :-)
20744 \emph default
20745
20746 \newline
20747
20748 \layout Standard
20749
20750 This document was initially written by Sandeep Dutta
20751 \layout Standard
20752
20753 All product names mentioned herein may be trademarks
20754 \begin_inset LatexCommand \index{Trademarks}
20755
20756 \end_inset
20757
20758  of their respective companies.
20759
20760 \layout Section*
20761
20762 Alphabetical index
20763 \layout Standard
20764
20765 To avoid confusion, the installation and building options for SDCC itself
20766  (chapter 2) are not part of the index.
20767 \layout Standard
20768
20769
20770 \begin_inset LatexCommand \printindex{}
20771
20772 \end_inset
20773
20774
20775 \the_end