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
   6
   7 \usepackage[
   8   pdftitle={SDCC Compiler User Guide},
   9   pdfauthor={SDCC development team},
  10   pdfsubject={installation, user manual},
  11   pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
  12                embedded, GPL, HC08, manual, mcs51, PIC, Z80},
  13   colorlinks=true,
  14   linkcolor=blue] {hyperref}
  15 %
  16 \sloppy
  17 \tolerance=500
  18 \emergencystretch=30pt
  19 %
  20 \date{}
  21 \end_preamble
  22 \language english
  23 \inputencoding default
  24 \fontscheme pslatex
  25 \graphics default
  26 \paperfontsize default
  27 \spacing single
  28 \papersize letterpaper
  29 \paperpackage a4
  30 \use_geometry 1
  31 \use_amsmath 0
  32 \use_natbib 0
  33 \use_numerical_citations 0
  34 \paperorientation portrait
  35 \leftmargin 30mm
  36 \topmargin 20mm
  37 \rightmargin 25mm
  38 \bottommargin 20mm
  39 \secnumdepth 3
  40 \tocdepth 3
  41 \paragraph_separation indent
  42 \defskip medskip
  43 \quotes_language swedish
  44 \quotes_times 2
  45 \papercolumns 1
  46 \papersides 1
  47 \paperpagestyle fancy
  48
  49 \layout Comment
  50
  51 Please note: double dashed longoptions (e.g.
  52  --version) are written this way: -
  53 \begin_inset ERT
  54 status Collapsed
  55
  56 \layout Standard
  57
  58 \backslash
  59 /
  60 \end_inset
  61
  62 -
  63 \layout Comment
  64
  65 Two resp.
  66  three consecutive dashes simply result in a long resp.
  67  extra long dash.
  68 \layout Comment
  69
  70 Architecture specific stuff (like memory models, code examples) should maybe
  71  later go
  72 \layout Comment
  73
  74 into seperate sections/chapters/appendices (it is hard to document PIC or
  75  Z80 in
  76 \layout Comment
  77
  78 a 8051 centered document) - for now simply add.
  79 \layout Title
  80
  81 SDCC Compiler User Guide
  82 \layout Date
  83
  84
  85 \size normal
  86 SDCC 2.5.0
  87 \size footnotesize
  88
  89 \newline
  90 $Date$
  91 \newline
  92 $Revision$
  93 \layout Comment
  94
  95 The above strings enclosed in $ are automatically updated by cvs
  96 \layout Standard
  97
  98
  99 \begin_inset LatexCommand \tableofcontents{}
 100
 101 \end_inset
 102
 103
 104 \layout Chapter
 105
 106 Introduction
 107 \layout Section
 108
 109 About SDCC
 110 \layout Standard
 111
 112
 113 \series bold
 114 SDCC
 115 \series default
 116  (
 117 \emph on
 118 S
 119 \emph default
 120 mall
 121 \emph on
 122 D
 123 \emph default
 124 evice
 125 \emph on
 126 C
 127 \emph default
 128
 129 \emph on
 130 C
 131 \emph default
 132 ompiler) is an open source, retargettable, optimizing ANSI-C compiler by
 133
 134 \series bold
 135 Sandeep Dutta
 136 \series default
 137  designed for 8 bit Microprocessors.
 138  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 139  8051, 8052
 140 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 141
 142 \end_inset
 143
 144 , etc.), Dallas DS80C390 variants, Freescale (formerly Motorola) HC08 and
 145  Zilog Z80 based MCUs.
 146  It can be retargetted for other microprocessors, support for Microchip
 147  PIC, Atmel AVR is under development.
 148  The entire source code for the compiler is distributed under GPL.
 149  SDCC uses ASXXXX
 150 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
 151
 152 \end_inset
 153
 154  & ASLINK
 155 \begin_inset LatexCommand \index{aslink}
 156
 157 \end_inset
 158
 159 , an open source retargettable assembler & linker.
 160  SDCC has extensive language extensions suitable for utilizing various microcont
 161 rollers and underlying hardware effectively.
 162
 163 \newline
 164
 165 \newline
 166 In addition to the MCU specific optimizations SDCC also does a host of standard
 167  optimizations like:
 168 \layout Itemize
 169
 170 global sub expression elimination,
 171 \layout Itemize
 172
 173 loop optimizations (loop invariant, strength reduction of induction variables
 174  and loop reversing),
 175 \layout Itemize
 176
 177 constant folding & propagation,
 178 \layout Itemize
 179
 180 copy propagation,
 181 \layout Itemize
 182
 183 dead code elimination
 184 \layout Itemize
 185
 186 jump tables for
 187 \emph on
 188 switch
 189 \emph default
 190  statements.
 191 \layout Standard
 192
 193 For the back-end SDCC uses a global register allocation scheme which should
 194  be well suited for other 8 bit MCUs.
 195
 196 \newline
 197
 198 \newline
 199 The peep hole optimizer uses a rule based substitution mechanism which is
 200  MCU independent.
 201
 202 \newline
 203
 204 \newline
 205 Supported data-types are:
 206 \layout Itemize
 207
 208 char (8 bits, 1 byte),
 209 \layout Itemize
 210
 211 short and int (16 bits, 2 bytes),
 212 \layout Itemize
 213
 214 long (32 bit, 4 bytes)
 215 \layout Itemize
 216
 217 float (4 byte IEEE).
 218
 219 \layout Standard
 220
 221 The compiler also allows
 222 \emph on
 223 inline assembler code
 224 \emph default
 225  to be embedded anywhere in a function.
 226  In addition, routines developed in assembly can also be called.
 227 \newline
 228
 229 \newline
 230 SDCC also provides an option (-
 231 \begin_inset ERT
 232 status Collapsed
 233
 234 \layout Standard
 235
 236 \backslash
 237 /
 238 \end_inset
 239
 240 -cyclomatic) to report the relative complexity of a function.
 241  These functions can then be further optimized, or hand coded in assembly
 242  if needed.
 243
 244 \newline
 245
 246 \newline
 247 SDCC also comes with a companion source level debugger SDCDB, the debugger
 248  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 249
 250 \newline
 251
 252 \newline
 253 The latest version can be downloaded from
 254 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 255
 256 \end_inset
 257
 258 .
 259
 260 \series bold
 261
 262 \series default
 263 \emph on
 264 Please note: the compiler will probably always be some steps ahead of this
 265  documentation
 266 \series bold
 267 \emph default
 268
 269 \begin_inset LatexCommand \index{Status of documentation}
 270
 271 \end_inset
 272
 273
 274 \begin_inset Foot
 275 collapsed false
 276
 277 \layout Standard
 278
 279 Obviously this has pros and cons
 280 \end_inset
 281
 282 .
 283 \layout Section
 284
 285 Open Source
 286 \layout Standard
 287
 288 All packages used in this compiler system are
 289 \emph on
 290 open source
 291 \emph default
 292  and
 293 \emph on
 294 freeware
 295 \emph default
 296 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 297  etc) is distributed with the package.
 298  This documentation is maintained using a freeware word processor (LyX).
 299 \newline
 300 This program is free software; you can redistribute it and/or modify it
 301  under the terms of the GNU General Public License
 302 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 303
 304 \end_inset
 305
 306  as published by the Free Software Foundation; either version 2, or (at
 307  your option) any later version.
 308  This program is distributed in the hope that it will be useful, but WITHOUT
 309  ANY WARRANTY; without even the implied warranty
 310 \begin_inset LatexCommand \index{warranty}
 311
 312 \end_inset
 313
 314  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 315  See the GNU General Public License for more details.
 316  You should have received a copy of the GNU General Public License along
 317  with this program; if not, write to the Free Software Foundation, 59 Temple
 318  Place - Suite 330, Boston, MA 02111-1307, USA.
 319  In other words, you are welcome to use, share and improve this program.
 320  You are forbidden to forbid anyone else to use, share and improve what
 321  you give them.
 322  Help stamp out software-hoarding!
 323 \layout Section
 324
 325 Typographic conventions
 326 \begin_inset LatexCommand \index{Typographic conventions}
 327
 328 \end_inset
 329
 330
 331 \layout Standard
 332
 333 Throughout this manual, we will use the following convention.
 334  Commands you have to type in are printed in
 335 \family sans
 336 \series bold
 337 "sans serif"
 338 \series default
 339 .
 340
 341 \family default
 342  Code samples are printed in
 343 \family typewriter
 344 typewriter font.
 345
 346 \family default
 347  Interesting items and new terms are printed in
 348 \emph on
 349 italic.
 350 \layout Section
 351
 352 Compatibility with previous versions
 353 \layout Standard
 354
 355 This version has numerous bug fixes compared with the previous version.
 356  But we also introduced some incompatibilities with older versions.
 357  Not just for the fun of it, but to make the compiler more stable, efficient
 358  and ANSI compliant
 359 \begin_inset LatexCommand \index{ANSI-compliance}
 360
 361 \end_inset
 362
 363  (see section
 364 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 365
 366 \end_inset
 367
 368  for ANSI-Compliance).
 369
 370 \newline
 371
 372 \layout Itemize
 373
 374 short is now equivalent to int (16 bits), it used to be equivalent to char
 375  (8 bits) which is not ANSI compliant.
 376 \layout Itemize
 377
 378 the default directory for gcc-builds where include, library and documentation
 379  files are stored is now in /usr/local/share.
 380 \layout Itemize
 381
 382 char type parameters to vararg functions are casted to int unless explicitly
 383  casted, e.g.:
 384 \newline
 385
 386 \family typewriter
 387 \SpecialChar ~
 388 \SpecialChar ~
 389 char a=3;
 390 \newline
 391 \SpecialChar ~
 392 \SpecialChar ~
 393 printf ("%d %c
 394 \backslash
 395 n", a, (char)a);
 396 \family default
 397
 398 \newline
 399  will push a as an int and as a char resp.
 400 \layout Itemize
 401
 402 option -
 403 \begin_inset ERT
 404 status Collapsed
 405
 406 \layout Standard
 407
 408 \backslash
 409 /
 410 \end_inset
 411
 412 -regextend has been removed.
 413 \layout Itemize
 414
 415 option -
 416 \begin_inset ERT
 417 status Collapsed
 418
 419 \layout Standard
 420
 421 \backslash
 422 /
 423 \end_inset
 424
 425 -noregparms has been removed.
 426 \layout Itemize
 427
 428 option -
 429 \begin_inset ERT
 430 status Collapsed
 431
 432 \layout Standard
 433
 434 \backslash
 435 /
 436 \end_inset
 437
 438 -stack-after-data has been removed.
 439 \layout Itemize
 440
 441 bit and sbit types now consistently behave like the C99 _Bool type with
 442  respect to type conversion.
 443  The most common incompatibility resulting from this change is related to
 444  bit toggling idioms, e.g.:
 445 \newline
 446
 447 \family typewriter
 448 \SpecialChar ~
 449 \SpecialChar ~
 450 bit b;
 451 \newline
 452 \SpecialChar ~
 453 \SpecialChar ~
 454 b = ~b; /* equivalent to b=1 instead of toggling b */
 455 \newline
 456 \SpecialChar ~
 457 \SpecialChar ~
 458 b = !b; /* toggles b */
 459 \newline
 460
 461 \family default
 462 In previous versions, both forms would have toggled the bit.
 463 \layout Standard
 464
 465
 466 \emph on
 467 <pending: more incompatibilities?>
 468 \layout Section
 469
 470 System Requirements
 471 \layout Standard
 472
 473 What do you need before you start installation of SDCC? A computer, and
 474  a desire to compute.
 475  The preferred method of installation is to compile SDCC from source using
 476  GNU gcc and make.
 477  For Windows some pre-compiled binary distributions are available for your
 478  convenience.
 479  You should have some experience with command line tools and compiler use.
 480 \layout Section
 481
 482 Other Resources
 483 \layout Standard
 484
 485 The SDCC home page at
 486 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 487
 488 \end_inset
 489
 490  is a great place to find distribution sets.
 491  You can also find links to the user mailing lists that offer help or discuss
 492  SDCC with other SDCC users.
 493  Web links to other SDCC related sites can also be found here.
 494  This document can be found in the DOC directory of the source package as
 495  a text or HTML file.
 496  A pdf version of this document is available at
 497 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 498
 499 \end_inset
 500
 501 .
 502  Some of the other tools (simulator and assembler) included with SDCC contain
 503  their own documentation and can be found in the source distribution.
 504  If you want the latest unreleased software, the complete source package
 505  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 506 \layout Section
 507
 508 Wishes for the future
 509 \layout Standard
 510
 511 There are (and always will be) some things that could be done.
 512  Here are some I can think of:
 513 \newline
 514
 515 \layout Standard
 516
 517
 518 \family typewriter
 519 char KernelFunction3(char p) at 0x340;
 520 \newline
 521
 522 \layout Standard
 523
 524
 525 \family typewriter
 526 code banking
 527 \begin_inset LatexCommand \index{code banking (not supported)}
 528
 529 \end_inset
 530
 531  support for mcs51
 532 \newline
 533
 534 \newline
 535
 536 \family default
 537 If you can think of some more, please see the section
 538 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 539
 540 \end_inset
 541
 542  about filing feature requests
 543 \begin_inset LatexCommand \index{Requesting features}
 544
 545 \end_inset
 546
 547
 548 \begin_inset LatexCommand \index{Feature request}
 549
 550 \end_inset
 551
 552 .
 553 \newline
 554
 555 \layout Chapter
 556
 557 Installing SDCC
 558 \begin_inset LatexCommand \index{Installation}
 559
 560 \end_inset
 561
 562
 563 \layout Standard
 564
 565 For most users it is sufficient to skip to either section
 566 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 567
 568 \end_inset
 569
 570  or section
 571 \begin_inset LatexCommand \ref{sub:Windows-Install}
 572
 573 \end_inset
 574
 575 .
 576  More detailled instructions follow below.
 577 \layout Section
 578
 579 Configure Options
 580 \begin_inset LatexCommand \index{Options SDCC configuration}
 581
 582 \end_inset
 583
 584
 585 \layout Standard
 586
 587 The install paths, search paths and other options are defined when running
 588  'configure'.
 589  The defaults can be overridden by:
 590 \layout List
 591 \labelwidthstring 00.00.0000
 592
 593 -
 594 \begin_inset ERT
 595 status Collapsed
 596
 597 \layout Standard
 598
 599 \backslash
 600 /
 601 \end_inset
 602
 603 -prefix see table below
 604 \layout List
 605 \labelwidthstring 00.00.0000
 606
 607 -
 608 \begin_inset ERT
 609 status Collapsed
 610
 611 \layout Standard
 612
 613 \backslash
 614 /
 615 \end_inset
 616
 617 -exec_prefix see table below
 618 \layout List
 619 \labelwidthstring 00.00.0000
 620
 621 -
 622 \begin_inset ERT
 623 status Collapsed
 624
 625 \layout Standard
 626
 627 \backslash
 628 /
 629 \end_inset
 630
 631 -bindir see table below
 632 \layout List
 633 \labelwidthstring 00.00.0000
 634
 635 -
 636 \begin_inset ERT
 637 status Collapsed
 638
 639 \layout Standard
 640
 641 \backslash
 642 /
 643 \end_inset
 644
 645 -datadir see table below
 646 \layout List
 647 \labelwidthstring 00.00.0000
 648
 649 docdir environment variable, see table below
 650 \layout List
 651 \labelwidthstring 00.00.0000
 652
 653 include_dir_suffix environment variable, see table below
 654 \layout List
 655 \labelwidthstring 00.00.0000
 656
 657 lib_dir_suffix environment variable, see table below
 658 \layout List
 659 \labelwidthstring 00.00.0000
 660
 661 sdccconf_h_dir_separator environment variable, either / or
 662 \backslash
 663
 664 \backslash
 665  makes sense here.
 666  This character will only be used in sdccconf.h; don't forget it's a C-header,
 667  therefore a double-backslash is needed there.
 668 \layout List
 669 \labelwidthstring 00.00.0000
 670
 671 -
 672 \begin_inset ERT
 673 status Collapsed
 674
 675 \layout Standard
 676
 677 \backslash
 678 /
 679 \end_inset
 680
 681 -disable-mcs51-port Excludes the Intel mcs51 port
 682 \layout List
 683 \labelwidthstring 00.00.0000
 684
 685 -
 686 \begin_inset ERT
 687 status Collapsed
 688
 689 \layout Standard
 690
 691 \backslash
 692 /
 693 \end_inset
 694
 695 -disable-gbz80-port Excludes the Gameboy gbz80 port
 696 \layout List
 697 \labelwidthstring 00.00.0000
 698
 699 -
 700 \begin_inset ERT
 701 status Collapsed
 702
 703 \layout Standard
 704
 705 \backslash
 706 /
 707 \end_inset
 708
 709 -disable-z80-port Excludes the z80 port
 710 \layout List
 711 \labelwidthstring 00.00.0000
 712
 713 -
 714 \begin_inset ERT
 715 status Collapsed
 716
 717 \layout Standard
 718
 719 \backslash
 720 /
 721 \end_inset
 722
 723 -disable-avr-port Excludes the AVR port
 724 \layout List
 725 \labelwidthstring 00.00.0000
 726
 727 -
 728 \begin_inset ERT
 729 status Collapsed
 730
 731 \layout Standard
 732
 733 \backslash
 734 /
 735 \end_inset
 736
 737 -disable-ds390-port Excludes the DS390 port
 738 \layout List
 739 \labelwidthstring 00.00.0000
 740
 741 -
 742 \begin_inset ERT
 743 status Collapsed
 744
 745 \layout Standard
 746
 747 \backslash
 748 /
 749 \end_inset
 750
 751 -disable-hc08-port Excludes the HC08 port
 752 \layout List
 753 \labelwidthstring 00.00.0000
 754
 755 -
 756 \begin_inset ERT
 757 status Collapsed
 758
 759 \layout Standard
 760
 761 \backslash
 762 /
 763 \end_inset
 764
 765 -disable-pic-port Excludes the PIC port
 766 \layout List
 767 \labelwidthstring 00.00.0000
 768
 769 -
 770 \begin_inset ERT
 771 status Collapsed
 772
 773 \layout Standard
 774
 775 \backslash
 776 /
 777 \end_inset
 778
 779 -disable-xa51-port Excludes the XA51 port
 780 \layout List
 781 \labelwidthstring 00.00.0000
 782
 783 -
 784 \begin_inset ERT
 785 status Collapsed
 786
 787 \layout Standard
 788
 789 \backslash
 790 /
 791 \end_inset
 792
 793 -disable-ucsim Disables configuring and building of ucsim
 794 \layout List
 795 \labelwidthstring 00.00.0000
 796
 797 -
 798 \begin_inset ERT
 799 status Collapsed
 800
 801 \layout Standard
 802
 803 \backslash
 804 /
 805 \end_inset
 806
 807 -disable-device-lib-build Disables automatically building device libraries
 808 \layout List
 809 \labelwidthstring 00.00.0000
 810
 811 -
 812 \begin_inset ERT
 813 status Collapsed
 814
 815 \layout Standard
 816
 817 \backslash
 818 /
 819 \end_inset
 820
 821 -disable-packihx Disables building packihx
 822 \layout List
 823 \labelwidthstring 00.00.0000
 824
 825 -
 826 \begin_inset ERT
 827 status Collapsed
 828
 829 \layout Standard
 830
 831 \backslash
 832 /
 833 \end_inset
 834
 835 -enable-libgc Use the Bohem memory allocator.
 836  Lower runtime footprint.
 837 \layout Standard
 838
 839 Furthermore the environment variables CC, CFLAGS, ...
 840  the tools and their arguments can be influenced.
 841  Please see `configure -
 842 \begin_inset ERT
 843 status Collapsed
 844
 845 \layout Standard
 846
 847 \backslash
 848 /
 849 \end_inset
 850
 851 -help` and the man/info pages of `configure` for details.
 852 \newline
 853
 854 \newline
 855 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 856  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 857 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 858  At the moment it's not possible to change the default settings (it was
 859  simply never required).
 860 \newline
 861
 862 \newline
 863 These configure options are compiled into the binaries, and can only be
 864  changed by rerunning 'configure' and recompiling SDCC.
 865  The configure options are written in
 866 \emph on
 867 italics
 868 \emph default
 869  to distinguish them from run time environment variables (see section search
 870  paths).
 871 \newline
 872
 873 \newline
 874 The settings for
 875 \begin_inset Quotes sld
 876 \end_inset
 877
 878 Win32 builds
 879 \begin_inset Quotes srd
 880 \end_inset
 881
 882  are used by the SDCC team to build the official Win32 binaries.
 883  The SDCC team uses Mingw32 to build the official Windows binaries, because
 884  it's
 885 \layout Enumerate
 886
 887 open source,
 888 \layout Enumerate
 889
 890 a gcc compiler and last but not least
 891 \layout Enumerate
 892
 893 the binaries can be built by cross compiling on Sourceforge's compile farm.
 894 \layout Standard
 895
 896 See the examples, how to pass the Win32 settings to 'configure'.
 897  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 898  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 899  for Win32.
 900 \newline
 901
 902 \newline
 903 These defaults are:
 904 \newline
 905
 906 \layout Standard
 907 \align center
 908
 909 \begin_inset  Tabular
 910 <lyxtabular version="3" rows="8" columns="3">
 911 <features>
 912 <column alignment="block" valignment="top" leftline="true" width="0in">
 913 <column alignment="block" valignment="top" leftline="true" width="0in">
 914 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 915 <row topline="true" bottomline="true">
 916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 917 \begin_inset Text
 918
 919 \layout Standard
 920
 921 Variable
 922 \end_inset
 923 </cell>
 924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 925 \begin_inset Text
 926
 927 \layout Standard
 928
 929 default
 930 \end_inset
 931 </cell>
 932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 933 \begin_inset Text
 934
 935 \layout Standard
 936
 937 Win32 builds
 938 \end_inset
 939 </cell>
 940 </row>
 941 <row topline="true">
 942 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 943 \begin_inset Text
 944
 945 \layout Standard
 946
 947
 948 \emph on
 949 PREFIX
 950 \end_inset
 951 </cell>
 952 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 953 \begin_inset Text
 954
 955 \layout Standard
 956
 957 /usr/local
 958 \end_inset
 959 </cell>
 960 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 961 \begin_inset Text
 962
 963 \layout Standard
 964
 965
 966 \backslash
 967 sdcc
 968 \end_inset
 969 </cell>
 970 </row>
 971 <row topline="true">
 972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 973 \begin_inset Text
 974
 975 \layout Standard
 976
 977
 978 \emph on
 979 EXEC_PREFIX
 980 \end_inset
 981 </cell>
 982 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 983 \begin_inset Text
 984
 985 \layout Standard
 986
 987
 988 \emph on
 989 $PREFIX
 990 \end_inset
 991 </cell>
 992 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 993 \begin_inset Text
 994
 995 \layout Standard
 996
 997
 998 \emph on
 999 $PREFIX
1000 \end_inset
1001 </cell>
1002 </row>
1003 <row topline="true">
1004 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1005 \begin_inset Text
1006
1007 \layout Standard
1008
1009
1010 \emph on
1011 BINDIR
1012 \end_inset
1013 </cell>
1014 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1015 \begin_inset Text
1016
1017 \layout Standard
1018
1019
1020 \emph on
1021 $EXECPREFIX
1022 \emph default
1023 /bin
1024 \end_inset
1025 </cell>
1026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1027 \begin_inset Text
1028
1029 \layout Standard
1030
1031
1032 \emph on
1033 $EXECPREFIX
1034 \emph default
1035
1036 \backslash
1037 bin
1038 \end_inset
1039 </cell>
1040 </row>
1041 <row topline="true">
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 \end_inset
1051 </cell>
1052 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1053 \begin_inset Text
1054
1055 \layout Standard
1056
1057
1058 \emph on
1059 $PREFIX
1060 \emph default
1061 /share
1062 \end_inset
1063 </cell>
1064 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1065 \begin_inset Text
1066
1067 \layout Standard
1068
1069
1070 \emph on
1071 $PREFIX
1072 \end_inset
1073 </cell>
1074 </row>
1075 <row topline="true">
1076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1077 \begin_inset Text
1078
1079 \layout Standard
1080
1081
1082 \emph on
1083 DOCDIR
1084 \end_inset
1085 </cell>
1086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1087 \begin_inset Text
1088
1089 \layout Standard
1090
1091
1092 \emph on
1093 $DATADIR
1094 \emph default
1095 /sdcc/doc
1096 \end_inset
1097 </cell>
1098 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1099 \begin_inset Text
1100
1101 \layout Standard
1102
1103
1104 \emph on
1105 $DATADIR
1106 \emph default
1107
1108 \backslash
1109 doc
1110 \end_inset
1111 </cell>
1112 </row>
1113 <row topline="true">
1114 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1115 \begin_inset Text
1116
1117 \layout Standard
1118
1119
1120 \emph on
1121 INCLUDE_DIR_SUFFIX
1122 \end_inset
1123 </cell>
1124 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1125 \begin_inset Text
1126
1127 \layout Standard
1128
1129 sdcc/include
1130 \end_inset
1131 </cell>
1132 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1133 \begin_inset Text
1134
1135 \layout Standard
1136
1137 include
1138 \end_inset
1139 </cell>
1140 </row>
1141 <row topline="true" bottomline="true">
1142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1143 \begin_inset Text
1144
1145 \layout Standard
1146
1147
1148 \emph on
1149 LIB_DIR_SUFFIX
1150 \end_inset
1151 </cell>
1152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1153 \begin_inset Text
1154
1155 \layout Standard
1156
1157 sdcc/lib
1158 \end_inset
1159 </cell>
1160 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1161 \begin_inset Text
1162
1163 \layout Standard
1164
1165 lib
1166 \end_inset
1167 </cell>
1168 </row>
1169 </lyxtabular>
1170
1171 \end_inset
1172
1173
1174 \newline
1175
1176 \layout Standard
1177 \noindent
1178 'configure' also computes relative paths.
1179  This is needed for full relocatability of a binary package and to complete
1180  search paths (see section search paths below):
1181 \newline
1182
1183 \layout Standard
1184 \align center
1185
1186 \begin_inset  Tabular
1187 <lyxtabular version="3" rows="4" columns="3">
1188 <features>
1189 <column alignment="block" valignment="top" leftline="true" width="0in">
1190 <column alignment="block" valignment="top" leftline="true" width="0in">
1191 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1192 <row topline="true" bottomline="true">
1193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1194 \begin_inset Text
1195
1196 \layout Standard
1197
1198 Variable (computed)
1199 \end_inset
1200 </cell>
1201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1202 \begin_inset Text
1203
1204 \layout Standard
1205
1206 default
1207 \end_inset
1208 </cell>
1209 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1210 \begin_inset Text
1211
1212 \layout Standard
1213
1214 Win32 builds
1215 \end_inset
1216 </cell>
1217 </row>
1218 <row topline="true" bottomline="true">
1219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1220 \begin_inset Text
1221
1222 \layout Standard
1223
1224
1225 \emph on
1226 BIN2DATA_DIR
1227 \end_inset
1228 </cell>
1229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1230 \begin_inset Text
1231
1232 \layout Standard
1233
1234 ../share
1235 \end_inset
1236 </cell>
1237 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1238 \begin_inset Text
1239
1240 \layout Standard
1241
1242 ..
1243 \end_inset
1244 </cell>
1245 </row>
1246 <row bottomline="true">
1247 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1248 \begin_inset Text
1249
1250 \layout Standard
1251
1252
1253 \emph on
1254 PREFIX2BIN_DIR
1255 \end_inset
1256 </cell>
1257 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1258 \begin_inset Text
1259
1260 \layout Standard
1261
1262 bin
1263 \end_inset
1264 </cell>
1265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1266 \begin_inset Text
1267
1268 \layout Standard
1269
1270 bin
1271 \end_inset
1272 </cell>
1273 </row>
1274 <row bottomline="true">
1275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1276 \begin_inset Text
1277
1278 \layout Standard
1279
1280
1281 \emph on
1282 PREFIX2DATA_DIR
1283 \end_inset
1284 </cell>
1285 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1286 \begin_inset Text
1287
1288 \layout Standard
1289
1290 share/sdcc
1291 \end_inset
1292 </cell>
1293 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1294 \begin_inset Text
1295
1296 \layout Standard
1297
1298 \end_inset
1299 </cell>
1300 </row>
1301 </lyxtabular>
1302
1303 \end_inset
1304
1305
1306 \newline
1307
1308 \layout Standard
1309 \noindent
1310 Examples:
1311 \layout LyX-Code
1312
1313 ./configure
1314 \newline
1315 ./configure -
1316 \begin_inset ERT
1317 status Collapsed
1318
1319 \layout Standard
1320
1321 \backslash
1322 /
1323 \end_inset
1324
1325 -prefix=
1326 \begin_inset Quotes srd
1327 \end_inset
1328
1329 /usr/bin
1330 \begin_inset Quotes srd
1331 \end_inset
1332
1333  -
1334 \begin_inset ERT
1335 status Collapsed
1336
1337 \layout Standard
1338
1339 \backslash
1340 /
1341 \end_inset
1342
1343 -datadir=
1344 \begin_inset Quotes srd
1345 \end_inset
1346
1347 /usr/share
1348 \begin_inset Quotes srd
1349 \end_inset
1350
1351
1352 \newline
1353 ./configure -
1354 \begin_inset ERT
1355 status Collapsed
1356
1357 \layout Standard
1358
1359 \backslash
1360 /
1361 \end_inset
1362
1363 -disable-avr-port -
1364 \begin_inset ERT
1365 status Collapsed
1366
1367 \layout Standard
1368
1369 \backslash
1370 /
1371 \end_inset
1372
1373 -disable-xa51-port
1374 \layout Standard
1375
1376 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1377 32'):
1378 \layout LyX-Code
1379
1380 ./configure
1381 \backslash
1382
1383 \newline
1384 CC=
1385 \begin_inset Quotes srd
1386 \end_inset
1387
1388 i586-mingw32msvc-gcc
1389 \begin_inset Quotes srd
1390 \end_inset
1391
1392  CXX=
1393 \begin_inset Quotes srd
1394 \end_inset
1395
1396 i586-mingw32msvc-g++
1397 \begin_inset Quotes srd
1398 \end_inset
1399
1400
1401 \backslash
1402
1403 \newline
1404 RANLIB=
1405 \begin_inset Quotes srd
1406 \end_inset
1407
1408 i586-mingw32msvc-ranlib
1409 \begin_inset Quotes srd
1410 \end_inset
1411
1412
1413 \backslash
1414
1415 \newline
1416 STRIP=
1417 \begin_inset Quotes srd
1418 \end_inset
1419
1420 i586-mingw32msvc-strip
1421 \begin_inset Quotes srd
1422 \end_inset
1423
1424
1425 \backslash
1426
1427 \newline
1428 -
1429 \begin_inset ERT
1430 status Collapsed
1431
1432 \layout Standard
1433
1434 \backslash
1435 /
1436 \end_inset
1437
1438 -prefix=
1439 \begin_inset Quotes srd
1440 \end_inset
1441
1442 /sdcc
1443 \begin_inset Quotes srd
1444 \end_inset
1445
1446
1447 \backslash
1448
1449 \newline
1450 -
1451 \begin_inset ERT
1452 status Collapsed
1453
1454 \layout Standard
1455
1456 \backslash
1457 /
1458 \end_inset
1459
1460 -datadir=
1461 \begin_inset Quotes srd
1462 \end_inset
1463
1464 /sdcc
1465 \begin_inset Quotes srd
1466 \end_inset
1467
1468
1469 \backslash
1470
1471 \newline
1472 docdir=
1473 \begin_inset Quotes srd
1474 \end_inset
1475
1476 /sdcc/doc
1477 \begin_inset Quotes srd
1478 \end_inset
1479
1480
1481 \backslash
1482
1483 \newline
1484 include_dir_suffix=
1485 \begin_inset Quotes srd
1486 \end_inset
1487
1488 include
1489 \begin_inset Quotes srd
1490 \end_inset
1491
1492
1493 \backslash
1494
1495 \newline
1496 lib_dir_suffix=
1497 \begin_inset Quotes srd
1498 \end_inset
1499
1500 lib
1501 \begin_inset Quotes srd
1502 \end_inset
1503
1504
1505 \backslash
1506
1507 \newline
1508 sdccconf_h_dir_separator=
1509 \begin_inset Quotes srd
1510 \end_inset
1511
1512
1513 \backslash
1514
1515 \backslash
1516
1517 \backslash
1518
1519 \backslash
1520
1521 \begin_inset Quotes srd
1522 \end_inset
1523
1524
1525 \backslash
1526
1527 \newline
1528 -
1529 \begin_inset ERT
1530 status Collapsed
1531
1532 \layout Standard
1533
1534 \backslash
1535 /
1536 \end_inset
1537
1538 -disable-device-lib-build
1539 \backslash
1540
1541 \newline
1542 -
1543 \begin_inset ERT
1544 status Collapsed
1545
1546 \layout Standard
1547
1548 \backslash
1549 /
1550 \end_inset
1551
1552 -disable-ucsim
1553 \backslash
1554
1555 \newline
1556 -
1557 \begin_inset ERT
1558 status Collapsed
1559
1560 \layout Standard
1561
1562 \backslash
1563 /
1564 \end_inset
1565
1566 -host=i586-mingw32msvc -
1567 \begin_inset ERT
1568 status Collapsed
1569
1570 \layout Standard
1571
1572 \backslash
1573 /
1574 \end_inset
1575
1576 -build=unknown-unknown-linux-gnu
1577 \layout Standard
1578
1579 To
1580 \begin_inset Quotes sld
1581 \end_inset
1582
1583 cross
1584 \begin_inset Quotes srd
1585 \end_inset
1586
1587 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1588 ):
1589 \layout LyX-Code
1590
1591 ./configure -C
1592 \backslash
1593
1594 \newline
1595 CFLAGS=
1596 \begin_inset Quotes srd
1597 \end_inset
1598
1599 -mno-cygwin -O2
1600 \begin_inset Quotes srd
1601 \end_inset
1602
1603
1604 \backslash
1605
1606 \newline
1607 LDFLAGS=
1608 \begin_inset Quotes srd
1609 \end_inset
1610
1611 -mno-cygwin
1612 \begin_inset Quotes srd
1613 \end_inset
1614
1615
1616 \backslash
1617
1618 \newline
1619 -
1620 \begin_inset ERT
1621 status Collapsed
1622
1623 \layout Standard
1624
1625 \backslash
1626 /
1627 \end_inset
1628
1629 -prefix=
1630 \begin_inset Quotes srd
1631 \end_inset
1632
1633 /sdcc
1634 \begin_inset Quotes srd
1635 \end_inset
1636
1637
1638 \backslash
1639
1640 \newline
1641 -
1642 \begin_inset ERT
1643 status Collapsed
1644
1645 \layout Standard
1646
1647 \backslash
1648 /
1649 \end_inset
1650
1651 -datadir=
1652 \begin_inset Quotes srd
1653 \end_inset
1654
1655 /sdcc
1656 \begin_inset Quotes srd
1657 \end_inset
1658
1659
1660 \backslash
1661
1662 \newline
1663 docdir=
1664 \begin_inset Quotes srd
1665 \end_inset
1666
1667 /sdcc/doc
1668 \begin_inset Quotes srd
1669 \end_inset
1670
1671
1672 \backslash
1673
1674 \newline
1675 include_dir_suffix=
1676 \begin_inset Quotes srd
1677 \end_inset
1678
1679 include
1680 \begin_inset Quotes srd
1681 \end_inset
1682
1683
1684 \backslash
1685
1686 \newline
1687 lib_dir_suffix=
1688 \begin_inset Quotes srd
1689 \end_inset
1690
1691 lib
1692 \begin_inset Quotes srd
1693 \end_inset
1694
1695
1696 \backslash
1697
1698 \newline
1699 sdccconf_h_dir_separator=
1700 \begin_inset Quotes srd
1701 \end_inset
1702
1703
1704 \backslash
1705
1706 \backslash
1707
1708 \backslash
1709
1710 \backslash
1711
1712 \begin_inset Quotes srd
1713 \end_inset
1714
1715
1716 \backslash
1717
1718 \newline
1719 -
1720 \begin_inset ERT
1721 status Collapsed
1722
1723 \layout Standard
1724
1725 \backslash
1726 /
1727 \end_inset
1728
1729 -disable-ucsim
1730 \layout Standard
1731
1732 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1733  The option '-
1734 \begin_inset ERT
1735 status Collapsed
1736
1737 \layout Standard
1738
1739 \backslash
1740 /
1741 \end_inset
1742
1743 -C' turns on caching, which gives a little bit extra speed.
1744  However if options are changed, it can be necessary to delete the config.cache
1745  file.
1746 \layout Section
1747
1748 Install paths
1749 \begin_inset LatexCommand \label{sub:Install-paths}
1750
1751 \end_inset
1752
1753
1754 \begin_inset LatexCommand \index{Install paths}
1755
1756 \end_inset
1757
1758
1759 \layout Standard
1760 \added_space_top medskip \align center
1761
1762 \begin_inset  Tabular
1763 <lyxtabular version="3" rows="5" columns="4">
1764 <features>
1765 <column alignment="center" valignment="top" leftline="true" width="0">
1766 <column alignment="center" valignment="top" leftline="true" width="0">
1767 <column alignment="center" valignment="top" leftline="true" width="0">
1768 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1769 <row topline="true" bottomline="true">
1770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1771 \begin_inset Text
1772
1773 \layout Standard
1774
1775
1776 \series bold
1777 Description
1778 \end_inset
1779 </cell>
1780 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1781 \begin_inset Text
1782
1783 \layout Standard
1784
1785
1786 \series bold
1787 Path
1788 \end_inset
1789 </cell>
1790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1791 \begin_inset Text
1792
1793 \layout Standard
1794
1795
1796 \series bold
1797 Default
1798 \end_inset
1799 </cell>
1800 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1801 \begin_inset Text
1802
1803 \layout Standard
1804
1805
1806 \series bold
1807 Win32 builds
1808 \end_inset
1809 </cell>
1810 </row>
1811 <row topline="true">
1812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1813 \begin_inset Text
1814
1815 \layout Standard
1816
1817 Binary files*
1818 \end_inset
1819 </cell>
1820 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1821 \begin_inset Text
1822
1823 \layout Standard
1824
1825
1826 \emph on
1827 $EXEC_PREFIX
1828 \end_inset
1829 </cell>
1830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1831 \begin_inset Text
1832
1833 \layout Standard
1834
1835 /usr/local/bin
1836 \end_inset
1837 </cell>
1838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1839 \begin_inset Text
1840
1841 \layout Standard
1842
1843
1844 \backslash
1845 sdcc
1846 \backslash
1847 bin
1848 \end_inset
1849 </cell>
1850 </row>
1851 <row topline="true">
1852 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1853 \begin_inset Text
1854
1855 \layout Standard
1856
1857 Include files
1858 \end_inset
1859 </cell>
1860 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1861 \begin_inset Text
1862
1863 \layout Standard
1864
1865
1866 \emph on
1867 $DATADIR/ $INCLUDE_DIR_SUFFIX
1868 \end_inset
1869 </cell>
1870 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1871 \begin_inset Text
1872
1873 \layout Standard
1874
1875 /usr/local/share/sdcc/include
1876 \end_inset
1877 </cell>
1878 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1879 \begin_inset Text
1880
1881 \layout Standard
1882
1883
1884 \backslash
1885 sdcc
1886 \backslash
1887 include
1888 \end_inset
1889 </cell>
1890 </row>
1891 <row topline="true">
1892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1893 \begin_inset Text
1894
1895 \layout Standard
1896
1897 Library file**
1898 \end_inset
1899 </cell>
1900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1901 \begin_inset Text
1902
1903 \layout Standard
1904
1905
1906 \emph on
1907 $DATADIR/$LIB_DIR_SUFFIX
1908 \end_inset
1909 </cell>
1910 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1911 \begin_inset Text
1912
1913 \layout Standard
1914
1915 /usr/local/share/sdcc/lib
1916 \end_inset
1917 </cell>
1918 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1919 \begin_inset Text
1920
1921 \layout Standard
1922
1923
1924 \backslash
1925 sdcc
1926 \backslash
1927 lib
1928 \end_inset
1929 </cell>
1930 </row>
1931 <row topline="true" bottomline="true">
1932 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1933 \begin_inset Text
1934
1935 \layout Standard
1936
1937 Documentation
1938 \end_inset
1939 </cell>
1940 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1941 \begin_inset Text
1942
1943 \layout Standard
1944
1945
1946 \emph on
1947 $DOCDIR
1948 \end_inset
1949 </cell>
1950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1951 \begin_inset Text
1952
1953 \layout Standard
1954
1955 /usr/local/share/sdcc/doc
1956 \end_inset
1957 </cell>
1958 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1959 \begin_inset Text
1960
1961 \layout Standard
1962
1963
1964 \backslash
1965 sdcc
1966 \backslash
1967 doc
1968 \end_inset
1969 </cell>
1970 </row>
1971 </lyxtabular>
1972
1973 \end_inset
1974
1975
1976 \layout Verse
1977
1978
1979 \size footnotesize
1980 *compiler, preprocessor, assembler, and linker
1981 \newline
1982 **the
1983 \shape italic
1984 model
1985 \shape default
1986  is auto-appended by the compiler, e.g.
1987  small, large, z80, ds390 etc
1988 \layout Standard
1989 \noindent
1990 The install paths can still be changed during `make install` with e.g.:
1991 \layout LyX-Code
1992
1993 make install prefix=$(HOME)/local/sdcc
1994 \layout Standard
1995
1996 Of course this doesn't change the search paths compiled into the binaries.
1997 \newline
1998
1999 \newline
2000 Moreover the install path can be changed by defining DESTDIR
2001 \begin_inset LatexCommand \index{DESTDIR}
2002
2003 \end_inset
2004
2005 :
2006 \layout LyX-Code
2007
2008 make install DESTDIR=$(HOME)/sdcc.rpm/
2009 \layout Standard
2010
2011 Please note that DESTDIR must have a trailing slash!
2012 \layout Section
2013
2014 Search Paths
2015 \begin_inset LatexCommand \label{sub:Search-Paths}
2016
2017 \end_inset
2018
2019
2020 \begin_inset LatexCommand \index{Search path}
2021
2022 \end_inset
2023
2024
2025 \layout Standard
2026
2027 Some search paths or parts of them are determined by configure variables
2028  (in
2029 \emph on
2030 italics
2031 \emph default
2032 , see section above).
2033  Further search paths are determined by environment variables during runtime.
2034
2035 \newline
2036 The paths searched when running the compiler are as follows (the first catch
2037  wins):
2038 \newline
2039
2040 \newline
2041 1.
2042  Binary files (preprocessor, assembler and linker)
2043 \newline
2044
2045 \layout Standard
2046 \align center
2047
2048 \begin_inset  Tabular
2049 <lyxtabular version="3" rows="4" columns="3">
2050 <features>
2051 <column alignment="block" valignment="top" leftline="true" width="0in">
2052 <column alignment="block" valignment="top" leftline="true" width="0in">
2053 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2054 <row topline="true" bottomline="true">
2055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2056 \begin_inset Text
2057
2058 \layout Standard
2059
2060 Search path
2061 \end_inset
2062 </cell>
2063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2064 \begin_inset Text
2065
2066 \layout Standard
2067
2068 default
2069 \end_inset
2070 </cell>
2071 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2072 \begin_inset Text
2073
2074 \layout Standard
2075
2076 Win32 builds
2077 \end_inset
2078 </cell>
2079 </row>
2080 <row topline="true">
2081 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2082 \begin_inset Text
2083
2084 \layout Standard
2085
2086 $SDCC_HOME/
2087 \emph on
2088 $PPREFIX2BIN_DIR
2089 \end_inset
2090 </cell>
2091 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2092 \begin_inset Text
2093
2094 \layout Standard
2095
2096 $SDCC_HOME/bin
2097 \end_inset
2098 </cell>
2099 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2100 \begin_inset Text
2101
2102 \layout Standard
2103
2104 $SDCC_HOME
2105 \backslash
2106 bin
2107 \end_inset
2108 </cell>
2109 </row>
2110 <row topline="true">
2111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2112 \begin_inset Text
2113
2114 \layout Standard
2115
2116 Path of argv[0] (if available)
2117 \end_inset
2118 </cell>
2119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2120 \begin_inset Text
2121
2122 \layout Standard
2123
2124 Path of argv[0]
2125 \end_inset
2126 </cell>
2127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2128 \begin_inset Text
2129
2130 \layout Standard
2131
2132 Path of argv[0]
2133 \end_inset
2134 </cell>
2135 </row>
2136 <row topline="true" bottomline="true">
2137 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2138 \begin_inset Text
2139
2140 \layout Standard
2141
2142 $PATH
2143 \end_inset
2144 </cell>
2145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2146 \begin_inset Text
2147
2148 \layout Standard
2149
2150 $PATH
2151 \end_inset
2152 </cell>
2153 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2154 \begin_inset Text
2155
2156 \layout Standard
2157
2158 $PATH
2159 \end_inset
2160 </cell>
2161 </row>
2162 </lyxtabular>
2163
2164 \end_inset
2165
2166
2167 \newline
2168
2169 \layout Standard
2170 \noindent
2171 2.
2172  Include files
2173 \newline
2174
2175 \layout Standard
2176 \align center
2177
2178 \begin_inset  Tabular
2179 <lyxtabular version="3" rows="6" columns="3">
2180 <features>
2181 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2182 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2183 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2184 <row topline="true" bottomline="true">
2185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2186 \begin_inset Text
2187
2188 \layout Standard
2189
2190 Search path
2191 \end_inset
2192 </cell>
2193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2194 \begin_inset Text
2195
2196 \layout Standard
2197
2198 default
2199 \end_inset
2200 </cell>
2201 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2202 \begin_inset Text
2203
2204 \layout Standard
2205
2206 Win32 builds
2207 \end_inset
2208 </cell>
2209 </row>
2210 <row topline="true">
2211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2212 \begin_inset Text
2213
2214 \layout Standard
2215
2216 -
2217 \begin_inset ERT
2218 status Collapsed
2219
2220 \layout Standard
2221
2222 \backslash
2223 /
2224 \end_inset
2225
2226 -I dir
2227 \end_inset
2228 </cell>
2229 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2230 \begin_inset Text
2231
2232 \layout Standard
2233
2234 -
2235 \begin_inset ERT
2236 status Collapsed
2237
2238 \layout Standard
2239
2240 \backslash
2241 /
2242 \end_inset
2243
2244 -I dir
2245 \end_inset
2246 </cell>
2247 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2248 \begin_inset Text
2249
2250 \layout Standard
2251
2252 -
2253 \begin_inset ERT
2254 status Collapsed
2255
2256 \layout Standard
2257
2258 \backslash
2259 /
2260 \end_inset
2261
2262 -I dir
2263 \end_inset
2264 </cell>
2265 </row>
2266 <row topline="true">
2267 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2268 \begin_inset Text
2269
2270 \layout Standard
2271
2272 $SDCC_INCLUDE
2273 \end_inset
2274 </cell>
2275 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2276 \begin_inset Text
2277
2278 \layout Standard
2279
2280 $SDCC_INCLUDE
2281 \end_inset
2282 </cell>
2283 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2284 \begin_inset Text
2285
2286 \layout Standard
2287
2288 $SDCC_INCLUDE
2289 \end_inset
2290 </cell>
2291 </row>
2292 <row topline="true">
2293 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2294 \begin_inset Text
2295
2296 \layout Standard
2297
2298 $SDCC_HOME/
2299 \newline
2300
2301 \emph on
2302 $PREFIX2DATA_DIR/
2303 \newline
2304 $INCLUDE_DIR_SUFFIX
2305 \end_inset
2306 </cell>
2307 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2308 \begin_inset Text
2309
2310 \layout Standard
2311
2312 $SDCC_ HOME/
2313 \newline
2314 share/sdcc/
2315 \newline
2316 include
2317 \end_inset
2318 </cell>
2319 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2320 \begin_inset Text
2321
2322 \layout Standard
2323
2324 $SDCC_HOME
2325 \backslash
2326 include
2327 \end_inset
2328 </cell>
2329 </row>
2330 <row topline="true">
2331 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2332 \begin_inset Text
2333
2334 \layout Standard
2335
2336 path(argv[0])/
2337 \newline
2338
2339 \emph on
2340 $BIN2DATADIR/
2341 \emph default
2342
2343 \newline
2344
2345 \emph on
2346 $INCLUDE_DIR_SUFFIX
2347 \end_inset
2348 </cell>
2349 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2350 \begin_inset Text
2351
2352 \layout Standard
2353
2354 path(argv[0])/
2355 \newline
2356 ../sdcc/include
2357 \newline
2358 \SpecialChar ~
2359 \SpecialChar ~
2360 \SpecialChar ~
2361 \SpecialChar ~
2362 \SpecialChar ~
2363 \SpecialChar ~
2364 \SpecialChar ~
2365 \SpecialChar ~
2366 \SpecialChar ~
2367 \SpecialChar ~
2368 \SpecialChar ~
2369 \SpecialChar ~
2370 \SpecialChar ~
2371 \SpecialChar ~
2372 \SpecialChar ~
2373 \SpecialChar ~
2374 \SpecialChar ~
2375 \SpecialChar ~
2376 \SpecialChar ~
2377 \SpecialChar ~
2378 \SpecialChar ~
2379 \SpecialChar ~
2380 \SpecialChar ~
2381 \SpecialChar ~
2382 \SpecialChar ~
2383 \SpecialChar ~
2384 \SpecialChar ~
2385 \SpecialChar ~
2386 \SpecialChar ~
2387 \SpecialChar ~
2388 \SpecialChar ~
2389 \SpecialChar ~
2390 \SpecialChar ~
2391 \SpecialChar ~
2392 \SpecialChar ~
2393 \SpecialChar ~
2394 \SpecialChar ~
2395 \SpecialChar ~
2396
2397 \end_inset
2398 </cell>
2399 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2400 \begin_inset Text
2401
2402 \layout Standard
2403
2404 path(argv[0])
2405 \backslash
2406 ..
2407 \backslash
2408 include
2409 \end_inset
2410 </cell>
2411 </row>
2412 <row topline="true" bottomline="true">
2413 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2414 \begin_inset Text
2415
2416 \layout Standard
2417
2418
2419 \emph on
2420 $DATADIR/
2421 \emph default
2422
2423 \newline
2424
2425 \emph on
2426 $INCLUDE_DIR_SUFFIX
2427 \end_inset
2428 </cell>
2429 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2430 \begin_inset Text
2431
2432 \layout Standard
2433
2434 /usr/local/share/sdcc/
2435 \newline
2436 include
2437 \end_inset
2438 </cell>
2439 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2440 \begin_inset Text
2441
2442 \layout Standard
2443
2444 (not on Win32)
2445 \end_inset
2446 </cell>
2447 </row>
2448 </lyxtabular>
2449
2450 \end_inset
2451
2452
2453 \newline
2454
2455 \layout Standard
2456 \noindent
2457 The option -
2458 \begin_inset ERT
2459 status Collapsed
2460
2461 \layout Standard
2462
2463 \backslash
2464 /
2465 \end_inset
2466
2467 -nostdinc disables the last two search paths.
2468 \newline
2469
2470 \newline
2471 3.
2472  Library files
2473 \newline
2474
2475 \layout Standard
2476
2477 With the exception of
2478 \begin_inset Quotes sld
2479 \end_inset
2480
2481 -
2482 \begin_inset ERT
2483 status Collapsed
2484
2485 \layout Standard
2486
2487 \backslash
2488 /
2489 \end_inset
2490
2491 -L dir
2492 \begin_inset Quotes srd
2493 \end_inset
2494
2495  the
2496 \shape italic
2497 model
2498 \shape default
2499  is auto-appended by the compiler (e.g.
2500  small, large, z80, ds390 etc.).
2501
2502 \newline
2503
2504 \layout Standard
2505 \align center
2506
2507 \begin_inset  Tabular
2508 <lyxtabular version="3" rows="6" columns="3">
2509 <features>
2510 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2511 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2512 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2513 <row topline="true" bottomline="true">
2514 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2515 \begin_inset Text
2516
2517 \layout Standard
2518
2519 Search path
2520 \end_inset
2521 </cell>
2522 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2523 \begin_inset Text
2524
2525 \layout Standard
2526
2527 default
2528 \end_inset
2529 </cell>
2530 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2531 \begin_inset Text
2532
2533 \layout Standard
2534
2535 Win32 builds
2536 \end_inset
2537 </cell>
2538 </row>
2539 <row topline="true">
2540 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2541 \begin_inset Text
2542
2543 \layout Standard
2544
2545 -
2546 \begin_inset ERT
2547 status Collapsed
2548
2549 \layout Standard
2550
2551 \backslash
2552 /
2553 \end_inset
2554
2555 -L dir
2556 \end_inset
2557 </cell>
2558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2559 \begin_inset Text
2560
2561 \layout Standard
2562
2563 -
2564 \begin_inset ERT
2565 status Collapsed
2566
2567 \layout Standard
2568
2569 \backslash
2570 /
2571 \end_inset
2572
2573 -L dir
2574 \end_inset
2575 </cell>
2576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2577 \begin_inset Text
2578
2579 \layout Standard
2580
2581 -
2582 \begin_inset ERT
2583 status Collapsed
2584
2585 \layout Standard
2586
2587 \backslash
2588 /
2589 \end_inset
2590
2591 -L dir
2592 \end_inset
2593 </cell>
2594 </row>
2595 <row topline="true">
2596 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2597 \begin_inset Text
2598
2599 \layout Standard
2600
2601 $SDCC_LIB/
2602 \newline
2603
2604 \emph on
2605 <model>
2606 \end_inset
2607 </cell>
2608 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2609 \begin_inset Text
2610
2611 \layout Standard
2612
2613 $SDCC_LIB/
2614 \newline
2615
2616 \emph on
2617 <model>
2618 \end_inset
2619 </cell>
2620 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2621 \begin_inset Text
2622
2623 \layout Standard
2624
2625 $SDCC_LIB
2626 \backslash
2627
2628 \newline
2629
2630 \emph on
2631 <model>
2632 \end_inset
2633 </cell>
2634 </row>
2635 <row topline="true">
2636 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2637 \begin_inset Text
2638
2639 \layout Standard
2640
2641 $SDCC_HOME/
2642 \newline
2643
2644 \emph on
2645 $PREFIX2DATA_DIR/
2646 \newline
2647 $LIB_DIR_SUFFIX/<model>
2648 \end_inset
2649 </cell>
2650 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2651 \begin_inset Text
2652
2653 \layout Standard
2654
2655 $SDCC_HOME/
2656 \newline
2657 share/sdcc/
2658 \newline
2659 lib/
2660 \emph on
2661 <model>
2662 \end_inset
2663 </cell>
2664 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2665 \begin_inset Text
2666
2667 \layout Standard
2668
2669 $SDCC_HOME
2670 \backslash
2671 lib
2672 \backslash
2673
2674 \emph on
2675
2676 \newline
2677 <model>
2678 \end_inset
2679 </cell>
2680 </row>
2681 <row topline="true">
2682 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2683 \begin_inset Text
2684
2685 \layout Standard
2686
2687 path(argv[0])/
2688 \newline
2689
2690 \emph on
2691 $BIN2DATADIR/
2692 \emph default
2693
2694 \newline
2695
2696 \emph on
2697 $LIB_DIR_SUFFIX/<model>
2698 \end_inset
2699 </cell>
2700 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2701 \begin_inset Text
2702
2703 \layout Standard
2704
2705 path(argv[0])/
2706 \newline
2707 ../sdcc/lib/
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 \SpecialChar ~
2747 \SpecialChar ~
2748 \SpecialChar ~
2749 \SpecialChar ~
2750
2751 \end_inset
2752 </cell>
2753 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2754 \begin_inset Text
2755
2756 \layout Standard
2757
2758 path(argv[0])
2759 \backslash
2760
2761 \newline
2762 ..
2763 \backslash
2764 lib
2765 \backslash
2766
2767 \emph on
2768 <model>
2769 \newline
2770 \SpecialChar ~
2771 \SpecialChar ~
2772 \SpecialChar ~
2773 \SpecialChar ~
2774 \SpecialChar ~
2775 \SpecialChar ~
2776 \SpecialChar ~
2777 \SpecialChar ~
2778 \SpecialChar ~
2779 \SpecialChar ~
2780 \SpecialChar ~
2781 \SpecialChar ~
2782 \SpecialChar ~
2783 \SpecialChar ~
2784 \SpecialChar ~
2785 \SpecialChar ~
2786 \SpecialChar ~
2787 \SpecialChar ~
2788 \SpecialChar ~
2789 \SpecialChar ~
2790 \SpecialChar ~
2791 \SpecialChar ~
2792 \SpecialChar ~
2793 \SpecialChar ~
2794 \SpecialChar ~
2795 \SpecialChar ~
2796 \SpecialChar ~
2797 \SpecialChar ~
2798 \SpecialChar ~
2799 \SpecialChar ~
2800 \SpecialChar ~
2801 \SpecialChar ~
2802 \SpecialChar ~
2803 \SpecialChar ~
2804 \SpecialChar ~
2805
2806 \end_inset
2807 </cell>
2808 </row>
2809 <row topline="true" bottomline="true">
2810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2811 \begin_inset Text
2812
2813 \layout Standard
2814
2815
2816 \emph on
2817 $DATADIR/
2818 \newline
2819 $LIB_DIR_SUFFIX/<model>
2820 \end_inset
2821 </cell>
2822 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2823 \begin_inset Text
2824
2825 \layout Standard
2826
2827 /usr/local/share/sdcc/
2828 \newline
2829 lib/
2830 \emph on
2831 <model>
2832 \end_inset
2833 </cell>
2834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2835 \begin_inset Text
2836
2837 \layout Standard
2838
2839 (not on Win32)
2840 \end_inset
2841 </cell>
2842 </row>
2843 </lyxtabular>
2844
2845 \end_inset
2846
2847
2848 \newline
2849
2850 \layout Comment
2851
2852 Don't delete any of the stray spaces in the table above without checking
2853  the HTML output (last line)!
2854 \layout Standard
2855
2856 \SpecialChar ~
2857
2858 \newline
2859 The option -
2860 \begin_inset ERT
2861 status Collapsed
2862
2863 \layout Standard
2864
2865 \backslash
2866 /
2867 \end_inset
2868
2869 -nostdlib disables the last two search paths.
2870 \layout Section
2871
2872 Building SDCC
2873 \begin_inset LatexCommand \index{Building SDCC}
2874
2875 \end_inset
2876
2877
2878 \layout Subsection
2879
2880 Building SDCC on Linux
2881 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2882
2883 \end_inset
2884
2885
2886 \layout Enumerate
2887
2888
2889 \series medium
2890 Download the source package
2891 \series default
2892  either from the SDCC CVS repository or from the nightly snapshots
2893 \series medium
2894 , it will be named something like sdcc
2895 \series default
2896 .src
2897 \series medium
2898 .t
2899 \series default
2900 ar.
2901 \series medium
2902 gz
2903 \series default
2904
2905 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2906
2907 \end_inset
2908
2909 .
2910 \layout Enumerate
2911
2912
2913 \series medium
2914 Bring up a command line terminal, such as xterm.
2915 \layout Enumerate
2916
2917
2918 \series medium
2919 Unpack the file using a command like:
2920 \family sans
2921 \series bold
2922 "tar -xvzf sdcc.src.tar.gz
2923 \family default
2924 \series default
2925 "
2926 \series medium
2927 , this will create a sub-directory called sdcc with all of the sources.
2928 \layout Enumerate
2929
2930 Change directory into the main SDCC directory, for example type:
2931 \family sans
2932 \series bold
2933 "cd sdcc
2934 \series default
2935 ".
2936 \layout Enumerate
2937
2938
2939 \series medium
2940 Type
2941 \family sans
2942 \series bold
2943 "./configure
2944 \family default
2945 \series default
2946 ".
2947  This configures the package for compilation on your system.
2948 \layout Enumerate
2949
2950
2951 \series medium
2952 Type
2953 \family sans
2954 \series bold
2955 "make
2956 \family default
2957 \series default
2958 "
2959 \series medium
2960 .
2961
2962 \series default
2963  All of the source packages will compile, this can take a while.
2964 \layout Enumerate
2965
2966
2967 \series medium
2968 Type
2969 \family sans
2970 \series bold
2971 "make install"
2972 \family default
2973 \series default
2974  as root
2975 \series medium
2976 .
2977
2978 \series default
2979  This copies the binary executables, the include files, the libraries and
2980  the documentation to the install directories.
2981  Proceed with section
2982 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
2983
2984 \end_inset
2985
2986 .
2987 \layout Subsection
2988
2989 Building SDCC on OSX 2.x
2990 \layout Standard
2991
2992 Follow the instruction for Linux.
2993 \newline
2994
2995 \newline
2996 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
2997 )) fails to compile SDCC.
2998  Fortunately there's also gcc 2.9.x installed, which works fine.
2999  This compiler can be selected by running 'configure' with:
3000 \layout LyX-Code
3001
3002 ./configure CC=gcc2 CXX=g++2
3003 \layout Subsection
3004
3005 Cross compiling SDCC on Linux for Windows
3006 \layout Standard
3007
3008 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
3009  See section 'Configure Options'.
3010 \layout Subsection
3011
3012 Building SDCC on Windows
3013 \layout Standard
3014
3015 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
3016  built on Windows.
3017  They use Unix-sockets, which are not available on Win32.
3018 \layout Subsection
3019
3020 Building SDCC using Cygwin and Mingw32
3021 \layout Standard
3022
3023 For building and installing a Cygwin executable follow the instructions
3024  for Linux.
3025 \newline
3026
3027 \newline
3028 On Cygwin a
3029 \begin_inset Quotes sld
3030 \end_inset
3031
3032 native
3033 \begin_inset Quotes srd
3034 \end_inset
3035
3036  Win32-binary can be built, which will not need the Cygwin-DLL.
3037  For the necessary 'configure' options see section 'configure options' or
3038  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3039 \newline
3040
3041 \newline
3042 In order to install Cygwin on Windows download setup.exe from
3043 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3044
3045 \end_inset
3046
3047 .
3048  Run it, set the
3049 \begin_inset Quotes sld
3050 \end_inset
3051
3052 default text file type
3053 \begin_inset Quotes srd
3054 \end_inset
3055
3056  to
3057 \begin_inset Quotes sld
3058 \end_inset
3059
3060 unix
3061 \begin_inset Quotes srd
3062 \end_inset
3063
3064  and download/install at least the following packages.
3065  Some packages are selected by default, others will be automatically selected
3066  because of dependencies with the manually selected packages.
3067  Never deselect these packages!
3068 \layout Itemize
3069
3070 flex
3071 \layout Itemize
3072
3073 bison
3074 \layout Itemize
3075
3076 gcc ; version 3.x is fine, no need to use the old 2.9x
3077 \layout Itemize
3078
3079 binutils ; selected with gcc
3080 \layout Itemize
3081
3082 make
3083 \layout Itemize
3084
3085 rxvt ; a nice console, which makes life much easier under windoze (see below)
3086 \layout Itemize
3087
3088 man ; not really needed for building SDCC, but you'll miss it sooner or
3089  later
3090 \layout Itemize
3091
3092 less ; not really needed for building SDCC, but you'll miss it sooner or
3093  later
3094 \layout Itemize
3095
3096 cvs ; only if you use CVS access
3097 \layout Standard
3098
3099 If you want to develop something you'll need:
3100 \layout Itemize
3101
3102 python ; for the regression tests
3103 \layout Itemize
3104
3105 gdb ; the gnu debugger, together with the nice GUI
3106 \begin_inset Quotes sld
3107 \end_inset
3108
3109 insight
3110 \begin_inset Quotes srd
3111 \end_inset
3112
3113
3114 \layout Itemize
3115
3116 openssh ; to access the CF or commit changes
3117 \layout Itemize
3118
3119 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3120  use autoconf-stable!
3121 \layout Standard
3122
3123 rxvt is a nice console with history.
3124  Replace in your cygwin.bat the line
3125 \layout LyX-Code
3126
3127 bash -
3128 \begin_inset ERT
3129 status Collapsed
3130
3131 \layout Standard
3132
3133 \backslash
3134 /
3135 \end_inset
3136
3137 -login -i
3138 \layout Standard
3139
3140 with (one line):
3141 \layout LyX-Code
3142
3143 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3144 \layout LyX-Code
3145
3146      -bg black -fg white -geometry 100x65 -e bash -
3147 \begin_inset ERT
3148 status Collapsed
3149
3150 \layout Standard
3151
3152 \backslash
3153 /
3154 \end_inset
3155
3156 -login
3157 \layout Standard
3158
3159 Text selected with the mouse is automatically copied to the clipboard, pasting
3160  works with shift-insert.
3161 \newline
3162
3163 \newline
3164 The other good tip is to make sure you have no //c/-style paths anywhere,
3165  use /cygdrive/c/ instead.
3166  Using // invokes a network lookup which is very slow.
3167  If you think
3168 \begin_inset Quotes sld
3169 \end_inset
3170
3171 cygdrive
3172 \begin_inset Quotes srd
3173 \end_inset
3174
3175  is too long, you can change it with e.g.
3176 \layout LyX-Code
3177
3178 mount -s -u -c /mnt
3179 \layout Standard
3180
3181 SDCC sources use the unix line ending LF.
3182  Life is much easier, if you store the source tree on a drive which is mounted
3183  in binary mode.
3184  And use an editor which can handle LF-only line endings.
3185  Make sure not to commit files with windows line endings.
3186  The tabulator spacing
3187 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3188
3189 \end_inset
3190
3191  used in the project is 8.
3192  Although a tabulator spacing of 8 is a sensible choice for programmers
3193  (it's a power of 2 and allows to display 8/16 bit signed variables without
3194  loosing columns) the plan is to move towards using only spaces in the source.
3195 \layout Subsection
3196
3197 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3198 \layout Standard
3199
3200
3201 \series medium
3202 Download the source package
3203 \series default
3204  either from the SDCC CVS repository or from the
3205 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3206
3207 \end_inset
3208
3209
3210 \series medium
3211 , it will be named something like sdcc
3212 \series default
3213 .src
3214 \series medium
3215 .tgz.
3216
3217 \series default
3218  SDCC is distributed with all the projects, workspaces, and files you need
3219  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3220  doesn't build under MSVC).
3221  The workspace name is 'sdcc.dsw'.
3222  Please note that as it is now, all the executables are created in a folder
3223  called sdcc
3224 \backslash
3225 bin_vc.
3226  Once built you need to copy the executables from sdcc
3227 \backslash
3228 bin_vc to sdcc
3229 \backslash
3230 bin before running SDCC.
3231
3232 \newline
3233
3234 \newline
3235 WARNING: Visual studio is very picky with line terminations; it expects
3236  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3237  If you are getting a message such as "This makefile was not generated by
3238  Developer Studio etc.
3239  etc.
3240 \begin_inset Quotes srd
3241 \end_inset
3242
3243  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3244  need to convert the Unix style line endings to DOS style line endings.
3245  To do so you can use the
3246 \begin_inset Quotes sld
3247 \end_inset
3248
3249 unix2dos
3250 \begin_inset Quotes srd
3251 \end_inset
3252
3253  utility freely available on the internet.
3254  Doug Hawkins reported in the sdcc-user list that this works:
3255 \newline
3256
3257 \newline
3258 C:
3259 \backslash
3260 Programming
3261 \backslash
3262 SDCC> unix2dos sdcc.dsw
3263 \newline
3264 C:
3265 \backslash
3266 Programming
3267 \backslash
3268 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3269 \newline
3270
3271 \newline
3272 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3273  flex.exe, and gawk.exe.
3274  One good place to get them is
3275 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3276
3277 \end_inset
3278
3279
3280 \newline
3281
3282 \newline
3283 Download the file UnxUtils
3284 \begin_inset LatexCommand \index{UnxUtils}
3285
3286 \end_inset
3287
3288 .zip.
3289  Now you have to install the utilities and setup MSVC so it can locate the
3290  required programs.
3291  Here there are two alternatives (choose one!):
3292 \layout Enumerate
3293
3294 The easy way:
3295 \newline
3296
3297 \newline
3298 a) Extract UnxUtils.zip to your C:
3299 \backslash
3300  hard disk PRESERVING the original paths, otherwise bison won't work.
3301  (If you are using WinZip make certain that 'Use folder names' is selected)
3302 \newline
3303
3304 \newline
3305 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3306  in 'Show directories for:' select 'Executable files', and in the directories
3307  window add a new path: 'C:
3308 \backslash
3309 user
3310 \backslash
3311 local
3312 \backslash
3313 wbin', click ok.
3314 \newline
3315
3316 \newline
3317 (As a side effect, you get a bunch of Unix utilities that could be useful,
3318  such as diff and patch.)
3319 \layout Enumerate
3320
3321 A more compact way:
3322 \newline
3323
3324 \newline
3325 This one avoids extracting a bunch of files you may not use, but requires
3326  some extra work:
3327 \newline
3328
3329 \newline
3330 a) Create a directory were to put the tools needed, or use a directory already
3331  present.
3332  Say for example 'C:
3333 \backslash
3334 util'.
3335 \newline
3336
3337 \newline
3338 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3339  to such directory WITHOUT preserving the original paths.
3340  (If you are using WinZip make certain that 'Use folder names' is not selected)
3341 \newline
3342
3343 \newline
3344 c) Rename bison.exe to '_bison.exe'.
3345 \newline
3346
3347 \newline
3348 d) Create a batch file 'bison.bat' in 'C:
3349 \backslash
3350 util
3351 \backslash
3352 ' and add these lines:
3353 \newline
3354 \SpecialChar ~
3355 \SpecialChar ~
3356 set BISON_SIMPLE=C:
3357 \backslash
3358 util
3359 \backslash
3360 bison.simple
3361 \newline
3362 \SpecialChar ~
3363 \SpecialChar ~
3364 set BISON_HAIRY=C:
3365 \backslash
3366 util
3367 \backslash
3368 bison.hairy
3369 \newline
3370 \SpecialChar ~
3371 \SpecialChar ~
3372 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3373 \newline
3374
3375 \newline
3376 Steps 'c' and 'd' are needed because bison requires by default that the
3377  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3378  '/usr/local/share/' I think.
3379  So it is necessary to tell bison where those files are located if they
3380  are not in such directory.
3381  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3382 \newline
3383
3384 \newline
3385 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3386  in 'Show directories for:' select 'Executable files', and in the directories
3387  window add a new path: 'c:
3388 \backslash
3389 util', click ok.
3390  Note that you can use any other path instead of 'c:
3391 \backslash
3392 util', even the path where the Visual C++ tools are, probably: 'C:
3393 \backslash
3394 Program Files
3395 \backslash
3396 Microsoft Visual Studio
3397 \backslash
3398 Common
3399 \backslash
3400 Tools'.
3401  So you don't have to execute step 'e' :)
3402 \layout Standard
3403
3404 That is it.
3405  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3406  the executables from sdcc
3407 \backslash
3408 bin_vc to sdcc
3409 \backslash
3410 bin, and you can compile using SDCC.
3411 \layout Subsection
3412
3413 Building SDCC Using Borland
3414 \layout Enumerate
3415
3416 From the sdcc directory, run the command "make -f Makefile.bcc".
3417  This should regenerate all the .exe files in the bin directory except for
3418  sdcdb.exe (which currently doesn't build under Borland C++).
3419 \layout Enumerate
3420
3421 If you modify any source files and need to rebuild, be aware that the dependenci
3422 es may not be correctly calculated.
3423  The safest option is to delete all .obj files and run the build again.
3424  From a Cygwin BASH prompt, this can easily be done with the command (be
3425  sure you are in the sdcc directory):
3426 \newline
3427
3428 \newline
3429
3430 \family sans
3431 \series bold
3432 find .
3433
3434 \backslash
3435 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3436 \backslash
3437 ) -print -exec rm {}
3438 \backslash
3439 ;
3440 \family default
3441 \series default
3442
3443 \newline
3444
3445 \newline
3446 or on Windows NT/2000/XP from the command prompt with the command:
3447 \newline
3448
3449 \family sans
3450 \series bold
3451
3452 \newline
3453 del /s *.obj *.lib *.rul
3454 \family default
3455 \series default
3456  from the sdcc directory.
3457 \layout Subsection
3458
3459 Windows Install Using a Binary Package
3460 \begin_inset LatexCommand \label{sub:Windows-Install}
3461
3462 \end_inset
3463
3464
3465 \layout Enumerate
3466
3467 Download the binary package from
3468 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3469
3470 \end_inset
3471
3472  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3473  This should unpack to a group of sub-directories.
3474  An example directory structure after unpacking the mingw32 package is:
3475  c:
3476 \backslash
3477 sdcc
3478 \backslash
3479 bin for the executables, c:
3480 \backslash
3481 sdcc
3482 \backslash
3483 include and c:
3484 \backslash
3485 sdcc
3486 \backslash
3487 lib for the include and libraries.
3488 \layout Enumerate
3489
3490 Adjust your environment variable PATH to include the location of the bin
3491  directory or start sdcc using the full path.
3492 \layout Section
3493
3494 Building the Documentation
3495 \layout Standard
3496
3497 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3498  as changing into the doc directory and typing
3499 \family sans
3500 \series bold
3501
3502 \begin_inset Quotes srd
3503 \end_inset
3504
3505 make
3506 \begin_inset Quotes srd
3507 \end_inset
3508
3509
3510 \family default
3511 \series default
3512  there.
3513  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3514 x).
3515  Using LyX
3516 \begin_inset LatexCommand \url{www.lyx.org}
3517
3518 \end_inset
3519
3520  as editor this is straightforward.
3521  Prebuilt documentation in html and pdf format is available from
3522 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3523
3524 \end_inset
3525
3526 .
3527 \layout Section
3528
3529 Reading the Documentation
3530 \layout Standard
3531
3532 Currently reading the document in pdf format is recommended, as for unknown
3533  reason the hyperlinks are working there whereas in the html version they
3534  are not
3535 \begin_inset Foot
3536 collapsed false
3537
3538 \layout Standard
3539
3540 If you should know why please drop us a note
3541 \end_inset
3542
3543 .
3544  You'll find the pdf version at
3545 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
3546
3547 \end_inset
3548
3549 .
3550 \newline
3551 This documentation is in some aspects different from a commercial documentation:
3552
3553 \layout Itemize
3554
3555 It tries to document SDCC for several processor architectures in one document
3556  (commercially these probably would be separate documents/products).
3557  This document
3558 \begin_inset LatexCommand \index{Status of documentation}
3559
3560 \end_inset
3561
3562  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3563 on about f.e.
3564  Z80, PIC14, PIC16 and HC08.
3565 \layout Itemize
3566
3567 There are many references pointing away from this documentation.
3568  Don't let this distract you.
3569  If there f.e.
3570  was a reference like
3571 \begin_inset LatexCommand \url{www.opencores.org}
3572
3573 \end_inset
3574
3575  together with a statement
3576 \begin_inset Quotes sld
3577 \end_inset
3578
3579 some processors which are targetted by SDCC can be implemented in a
3580 \emph on
3581 f
3582 \emph default
3583 ield
3584 \emph on
3585 p
3586 \emph default
3587 rogrammable
3588 \emph on
3589 g
3590 \emph default
3591 ate
3592 \emph on
3593 a
3594 \emph default
3595 rray
3596 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3597
3598 \end_inset
3599
3600
3601 \begin_inset Quotes srd
3602 \end_inset
3603
3604  we expect you to have a quick look there and come back.
3605  If you read this you are on the right track.
3606 \layout Itemize
3607
3608 Some sections attribute more space to problems, restrictions and warnings
3609  than to the solution.
3610 \layout Itemize
3611
3612 The installation section and the section about the debugger is intimidating.
3613 \layout Itemize
3614
3615 There are still lots of typos and there are more different writing styles
3616  than pictures.
3617 \layout Section
3618
3619 Testing the SDCC Compiler
3620 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3621
3622 \end_inset
3623
3624
3625 \layout Standard
3626
3627 The first thing you should do after installing your SDCC compiler is to
3628  see if it runs.
3629  Type
3630 \family sans
3631 \series bold
3632 "sdcc -
3633 \begin_inset ERT
3634 status Collapsed
3635
3636 \layout Standard
3637
3638 \backslash
3639 /
3640 \end_inset
3641
3642 -version"
3643 \begin_inset LatexCommand \index{version}
3644
3645 \end_inset
3646
3647
3648 \family default
3649 \series default
3650  at the prompt, and the program should run and tell you the version.
3651  If it doesn't run, or gives a message about not finding sdcc program, then
3652  you need to check over your installation.
3653  Make sure that the sdcc bin directory is in your executable search path
3654  defined by the PATH environment setting (
3655 \series medium
3656 see
3657 \series default
3658 section
3659 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3660
3661 \end_inset
3662
3663 \SpecialChar ~
3664
3665 \series medium
3666 Install trouble-shooting for suggestions
3667 \series default
3668 ).
3669  Make sure that the sdcc program is in the bin folder, if not perhaps something
3670  did not install correctly.
3671 \newline
3672
3673 \newline
3674
3675 \series medium
3676 SDCC
3677 \series default
3678 is commonly installed as described in section
3679 \begin_inset Quotes sld
3680 \end_inset
3681
3682 Install and search paths
3683 \begin_inset Quotes srd
3684 \end_inset
3685
3686 .
3687 \newline
3688
3689 \newline
3690
3691 \series medium
3692 Make sure the compiler works on a very simple example.
3693  Type in the following test.c program using your favorite
3694 \series default
3695 ASCII
3696 \series medium
3697 editor:
3698 \layout Verse
3699
3700
3701 \family typewriter
3702 char test;
3703 \newline
3704
3705 \newline
3706 void main(void) {
3707 \newline
3708 \SpecialChar ~
3709 \SpecialChar ~
3710 \SpecialChar ~
3711 \SpecialChar ~
3712 test=0;
3713 \newline
3714 }
3715 \layout Standard
3716
3717
3718 \series medium
3719 Compile this using the following command:
3720 \family sans
3721 \series bold
3722 "sdcc -c test.c".
3723
3724 \family default
3725 \series default
3726
3727 \series medium
3728 If all goes well, the compiler will generate a test.asm and test.rel file.
3729  Congratulations, you've just compiled your first program with SDCC.
3730  We used the -c option to tell SDCC not to link the generated code, just
3731  to keep things simple for this step.
3732 \series default
3733
3734 \newline
3735
3736 \newline
3737
3738 \series medium
3739 The next step is to try it with the linker.
3740  Type in
3741 \family sans
3742 \series bold
3743 "sdcc test.c
3744 \family default
3745 \series default
3746 "
3747 \series medium
3748 .
3749  If all goes well the compiler will link with the libraries and produce
3750  a test.ihx output file.
3751  If this step fails
3752 \series default
3753
3754 \series medium
3755 (no test.ihx, and the linker generates warnings), then the problem is most
3756  likely that
3757 \series default
3758 SDCC
3759 \series medium
3760  cannot find the
3761 \series default
3762 /
3763 \series medium
3764 usr/local/share/sdcc/lib directory
3765 \series default
3766
3767 \series medium
3768 (see
3769 \series default
3770 section
3771 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3772
3773 \end_inset
3774
3775 \SpecialChar ~
3776
3777 \series medium
3778 Install trouble-shooting for suggestions).
3779 \series default
3780
3781 \newline
3782
3783 \newline
3784
3785 \series medium
3786 The final test is to ensure
3787 \series default
3788 SDCC
3789 \series medium
3790  can use the
3791 \series default
3792 standard
3793 \series medium
3794  header files and libraries.
3795  Edit test.c and change it to the following:
3796 \layout Verse
3797
3798
3799 \family typewriter
3800 #include <string.h>
3801 \newline
3802
3803 \newline
3804 char str1[10];
3805 \newline
3806
3807 \newline
3808 void main(void) {
3809 \newline
3810 \SpecialChar ~
3811 \SpecialChar ~
3812 strcpy(str1, "testing");
3813 \newline
3814 }
3815 \layout Standard
3816
3817
3818 \series medium
3819 Compile this by typing
3820 \family sans
3821 \series bold
3822 "sdcc test.c"
3823 \family default
3824 \series medium
3825 .
3826  This should generate a test.ihx output file, and it should give no warnings
3827  such as not finding the string.h file.
3828  If it cannot find the string.h file, then the problem is that
3829 \series default
3830 SDCC
3831 \series medium
3832  cannot find the /usr/local/share/sdcc/include directory
3833 \series default
3834
3835 \series medium
3836 (see the
3837 \series default
3838 section
3839 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3840
3841 \end_inset
3842
3843 \SpecialChar ~
3844
3845 \series medium
3846 Install trouble-shooting section for suggestions).
3847
3848 \series default
3849  Use option
3850 \series bold
3851 -
3852 \begin_inset ERT
3853 status Collapsed
3854
3855 \layout Standard
3856
3857 \backslash
3858 /
3859 \end_inset
3860
3861 -print-search-dirs
3862 \series default
3863
3864 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3865
3866 \end_inset
3867
3868  to find exactly where SDCC is looking for the include and lib files.
3869 \layout Section
3870
3871 Install Trouble-shooting
3872 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3873
3874 \end_inset
3875
3876
3877 \begin_inset LatexCommand \index{Install trouble-shooting}
3878
3879 \end_inset
3880
3881
3882 \layout Subsection
3883
3884 If SDCC does not build correctly
3885 \layout Standard
3886
3887 A thing to try is starting from scratch by unpacking the .tgz source package
3888  again in an empty directory.
3889  Configure it like:
3890 \newline
3891
3892 \newline
3893
3894 \family sans
3895 \series bold
3896 ./configure 2>&1 | tee configure.log
3897 \family default
3898 \series default
3899
3900 \newline
3901
3902 \newline
3903 and build it like:
3904 \newline
3905
3906 \newline
3907
3908 \family sans
3909 \series bold
3910 make 2>&1 | tee make.log
3911 \family default
3912 \series default
3913
3914 \newline
3915
3916 \newline
3917 If anything goes wrong, you can review the log files to locate the problem.
3918  Or a relevant part of this can be attached to an email that could be helpful
3919  when requesting help from the mailing list.
3920 \layout Subsection
3921
3922 What the
3923 \begin_inset Quotes sld
3924 \end_inset
3925
3926 ./configure
3927 \begin_inset Quotes srd
3928 \end_inset
3929
3930  does
3931 \layout Standard
3932
3933 The
3934 \begin_inset Quotes sld
3935 \end_inset
3936
3937 ./configure
3938 \begin_inset Quotes srd
3939 \end_inset
3940
3941  command is a script that analyzes your system and performs some configuration
3942  to ensure the source package compiles on your system.
3943  It will take a few minutes to run, and will compile a few tests to determine
3944  what compiler features are installed.
3945 \layout Subsection
3946
3947 What the
3948 \begin_inset Quotes sld
3949 \end_inset
3950
3951 make
3952 \begin_inset Quotes srd
3953 \end_inset
3954
3955  does
3956 \layout Standard
3957
3958 This runs the GNU make tool, which automatically compiles all the source
3959  packages into the final installed binary executables.
3960 \layout Subsection
3961
3962 What the
3963 \begin_inset Quotes sld
3964 \end_inset
3965
3966 make install
3967 \begin_inset Quotes erd
3968 \end_inset
3969
3970  command does.
3971 \layout Standard
3972
3973 This will install the compiler, other executables libraries and include
3974  files into the appropriate directories.
3975  See sections
3976 \begin_inset LatexCommand \ref{sub:Install-paths}
3977
3978 \end_inset
3979
3980 ,\SpecialChar ~
3981
3982 \begin_inset LatexCommand \ref{sub:Search-Paths}
3983
3984 \end_inset
3985
3986 \SpecialChar ~
3987 about install and search paths.
3988 \newline
3989 On most systems you will need super-user privileges to do this.
3990 \layout Section
3991
3992 Components of SDCC
3993 \layout Standard
3994
3995 SDCC is not just a compiler, but a collection of tools by various developers.
3996  These include linkers, assemblers, simulators and other components.
3997  Here is a summary of some of the components.
3998  Note that the included simulator and assembler have separate documentation
3999  which you can find in the source package in their respective directories.
4000  As SDCC grows to include support for other processors, other packages from
4001  various developers are included and may have their own sets of documentation.
4002 \newline
4003
4004 \newline
4005 You might want to look at the files which are installed in <installdir>.
4006  At the time of this writing, we find the following programs for gcc-builds:
4007 \newline
4008
4009 \newline
4010 In <installdir>/bin:
4011 \layout Itemize
4012
4013 sdcc - The compiler.
4014 \layout Itemize
4015
4016 sdcpp - The C preprocessor.
4017 \layout Itemize
4018
4019 asx8051 - The assembler for 8051 type processors.
4020 \layout Itemize
4021
4022 as-z80
4023 \series bold
4024 ,
4025 \series default
4026 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4027 \layout Itemize
4028
4029 aslink -The linker for 8051 type processors.
4030 \layout Itemize
4031
4032 link-z80
4033 \series bold
4034 ,
4035 \series default
4036 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4037 \layout Itemize
4038
4039 s51 - The ucSim 8051 simulator.
4040 \layout Itemize
4041
4042 sdcdb - The source debugger.
4043 \layout Itemize
4044
4045 packihx - A tool to pack (compress) Intel hex files.
4046 \layout Standard
4047
4048 In <installdir>/share/sdcc/include
4049 \layout Itemize
4050
4051 the include files
4052 \layout Standard
4053
4054 In <installdir>/share/sdcc/lib
4055 \layout Itemize
4056
4057 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4058  relocatables.
4059 \layout Standard
4060
4061 In <installdir>/share/sdcc/doc
4062 \layout Itemize
4063
4064 the documentation
4065 \layout Standard
4066
4067 As development for other processors proceeds, this list will expand to include
4068  executables to support processors like AVR, PIC, etc.
4069 \layout Subsection
4070
4071 sdcc - The Compiler
4072 \layout Standard
4073
4074 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4075  the assembler and linkage editor.
4076 \layout Subsection
4077
4078 sdcpp - The C-Preprocessor
4079 \layout Standard
4080
4081 The preprocessor
4082 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4083
4084 \end_inset
4085
4086  is a modified version of the GNU preprocessor.
4087  The C preprocessor is used to pull in #include sources, process #ifdef
4088  statements, #defines and so on.
4089 \layout Subsection
4090
4091 as
4092 \emph on
4093 xxxx
4094 \emph default
4095 , aslink, link-
4096 \emph on
4097 xxx
4098 \emph default
4099  - The Assemblers and Linkage Editors
4100 \layout Standard
4101
4102 This is retargettable assembler & linkage editor, it was developed by Alan
4103  Baldwin.
4104  John Hartman created the version for 8051, and I (Sandeep) have made some
4105  enhancements and bug fixes for it to work properly with SDCC.
4106 \layout Subsection
4107
4108 s51 - The Simulator
4109 \layout Standard
4110
4111 S51
4112 \begin_inset LatexCommand \index{s51}
4113
4114 \end_inset
4115
4116  is a freeware, opensource simulator developed by Daniel Drotos (
4117 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
4118
4119 \end_inset
4120
4121 ).
4122  The simulator is built as part of the build process.
4123  For more information visit Daniel's web site at:
4124 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4125
4126 \end_inset
4127
4128 .
4129  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4130  XA51 family.
4131 \layout Subsection
4132
4133 sdcdb - Source Level Debugger
4134 \layout Standard
4135
4136 Sdcdb
4137 \begin_inset LatexCommand \index{sdcdb (debugger)}
4138
4139 \end_inset
4140
4141  is the companion source level debugger.
4142  More about sdcdb in section
4143 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4144
4145 \end_inset
4146
4147 .
4148  The current version of the debugger uses Daniel's Simulator S51
4149 \begin_inset LatexCommand \index{s51}
4150
4151 \end_inset
4152
4153 , but can be easily changed to use other simulators.
4154
4155 \layout Chapter
4156
4157 Using SDCC
4158 \layout Section
4159
4160 Compiling
4161 \layout Subsection
4162
4163 Single Source File Projects
4164 \layout Standard
4165
4166 For single source file 8051 projects the process is very simple.
4167  Compile your programs with the following command
4168 \family sans
4169 \series bold
4170 "sdcc sourcefile.c".
4171
4172 \family default
4173 \series default
4174  This will compile, assemble and link your source file.
4175  Output files are as follows:
4176 \layout Itemize
4177
4178 sourcefile.asm
4179 \begin_inset LatexCommand \index{<file>.asm}
4180
4181 \end_inset
4182
4183  - Assembler source
4184 \begin_inset LatexCommand \index{Assembler source}
4185
4186 \end_inset
4187
4188  file created by the compiler
4189 \layout Itemize
4190
4191 sourcefile.lst
4192 \begin_inset LatexCommand \index{<file>.lst}
4193
4194 \end_inset
4195
4196  - Assembler listing
4197 \begin_inset LatexCommand \index{Assembler listing}
4198
4199 \end_inset
4200
4201  file created by the Assembler
4202 \layout Itemize
4203
4204 sourcefile.rst
4205 \begin_inset LatexCommand \index{<file>.rst}
4206
4207 \end_inset
4208
4209  - Assembler listing
4210 \begin_inset LatexCommand \index{Assembler listing}
4211
4212 \end_inset
4213
4214  file updated with linkedit information, created by linkage editor
4215 \layout Itemize
4216
4217 sourcefile.sym
4218 \begin_inset LatexCommand \index{<file>.sym}
4219
4220 \end_inset
4221
4222  - symbol listing
4223 \begin_inset LatexCommand \index{Symbol listing}
4224
4225 \end_inset
4226
4227  for the sourcefile, created by the assembler
4228 \layout Itemize
4229
4230 sourcefile.rel
4231 \begin_inset LatexCommand \index{<file>.rel}
4232
4233 \end_inset
4234
4235  or sourcefile.o
4236 \begin_inset LatexCommand \index{<file>.o}
4237
4238 \end_inset
4239
4240  - Object file
4241 \begin_inset LatexCommand \index{Object file}
4242
4243 \end_inset
4244
4245  created by the assembler, input to Linkage editor
4246 \layout Itemize
4247
4248 sourcefile.map
4249 \begin_inset LatexCommand \index{<file>.map}
4250
4251 \end_inset
4252
4253  - The memory map
4254 \begin_inset LatexCommand \index{Memory map}
4255
4256 \end_inset
4257
4258  for the load module, created by the Linker
4259 \layout Itemize
4260
4261 sourcefile.mem
4262 \begin_inset LatexCommand \index{<file>.mem}
4263
4264 \end_inset
4265
4266  - A file with a summary of the memory usage
4267 \layout Itemize
4268
4269 sourcefile.ihx
4270 \begin_inset LatexCommand \index{<file>.ihx}
4271
4272 \end_inset
4273
4274  - The load module in Intel hex format
4275 \begin_inset LatexCommand \index{Intel hex format}
4276
4277 \end_inset
4278
4279  (you can select the Motorola S19 format
4280 \begin_inset LatexCommand \index{Motorola S19 format}
4281
4282 \end_inset
4283
4284  with -
4285 \begin_inset ERT
4286 status Collapsed
4287
4288 \layout Standard
4289
4290 \backslash
4291 /
4292 \end_inset
4293
4294 -out-fmt-s19
4295 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4296
4297 \end_inset
4298
4299 .
4300  If you need another format you might want to use
4301 \family sans
4302 \shape italic
4303 objdump
4304 \family default
4305 \shape default
4306
4307 \begin_inset LatexCommand \index{objdump (tool)}
4308
4309 \end_inset
4310
4311  or
4312 \family sans
4313 \shape italic
4314  srecord
4315 \family default
4316 \shape default
4317
4318 \begin_inset LatexCommand \index{srecord (tool)}
4319
4320 \end_inset
4321
4322 ).
4323  Both formats are documented in the documentation of srecord
4324 \begin_inset LatexCommand \index{srecord (tool)}
4325
4326 \end_inset
4327
4328
4329 \layout Itemize
4330
4331 sourcefile.adb
4332 \begin_inset LatexCommand \index{<file>.adb}
4333
4334 \end_inset
4335
4336  - An intermediate file containing debug information needed to create the
4337  .cdb file (with -
4338 \begin_inset ERT
4339 status Open
4340
4341 \layout Standard
4342
4343 \backslash
4344 /
4345 \end_inset
4346
4347 -debug
4348 \begin_inset LatexCommand \index{-\/-debug}
4349
4350 \end_inset
4351
4352 )
4353 \layout Itemize
4354
4355 sourcefile.cdb
4356 \begin_inset LatexCommand \index{<file>.cdb}
4357
4358 \end_inset
4359
4360  - An optional file (with -
4361 \begin_inset ERT
4362 status Collapsed
4363
4364 \layout Standard
4365
4366 \backslash
4367 /
4368 \end_inset
4369
4370 -debug) containing debug information.
4371  The format is documented in cdbfileformat.pdf.
4372 \layout Itemize
4373
4374 sourcefile.
4375  - (no extension)
4376 \begin_inset LatexCommand \index{<file> (no extension)}
4377
4378 \end_inset
4379
4380  An optional AOMF or AOMF51
4381 \begin_inset LatexCommand \index{AOMF, AOMF51}
4382
4383 \end_inset
4384
4385  file containing debug information (generated with option -
4386 \begin_inset ERT
4387 status Collapsed
4388
4389 \layout Standard
4390
4391 \backslash
4392 /
4393 \end_inset
4394
4395 -debug).
4396  The (Intel)
4397 \emph on
4398  a
4399 \emph default
4400 bsolute
4401 \emph on
4402 o
4403 \emph default
4404 bject
4405 \emph on
4406 m
4407 \emph default
4408 odule
4409 \emph on
4410 f
4411 \emph default
4412 ormat is commonly used by third party tools (debuggers
4413 \begin_inset LatexCommand \index{Debugger}
4414
4415 \end_inset
4416
4417 , simulators, emulators)
4418 \layout Itemize
4419
4420 sourcefile.dump*
4421 \begin_inset LatexCommand \index{<file>.dump*}
4422
4423 \end_inset
4424
4425  - Dump file to debug the compiler it self (generated with option -
4426 \begin_inset ERT
4427 status Collapsed
4428
4429 \layout Standard
4430
4431 \backslash
4432 /
4433 \end_inset
4434
4435 -dumpall) (see section
4436 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4437
4438 \end_inset
4439
4440 \SpecialChar ~
4441  and section
4442 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4443
4444 \end_inset
4445
4446 \SpecialChar ~
4447
4448 \begin_inset Quotes sld
4449 \end_inset
4450
4451 Anatomy of the compiler
4452 \begin_inset Quotes srd
4453 \end_inset
4454
4455 ).
4456 \layout Subsection
4457
4458 Projects with Multiple Source Files
4459 \layout Standard
4460
4461 SDCC can compile only ONE file at a time.
4462  Let us for example assume that you have a project containing the following
4463  files:
4464 \newline
4465
4466 \newline
4467 foo1.c (contains some functions)
4468 \newline
4469 foo2.c (contains some more functions)
4470 \newline
4471 foomain.c (contains more functions and the function main)
4472 \newline
4473
4474 \size footnotesize
4475
4476 \newline
4477
4478 \size default
4479 The first two files will need to be compiled separately with the commands:
4480 \size footnotesize
4481
4482 \size default
4483
4484 \newline
4485
4486 \newline
4487
4488 \family sans
4489 \series bold
4490 sdcc\SpecialChar ~
4491 -c\SpecialChar ~
4492 foo1.c
4493 \family default
4494 \series default
4495 \size footnotesize
4496
4497 \newline
4498
4499 \family sans
4500 \series bold
4501 \size default
4502 sdcc\SpecialChar ~
4503 -c\SpecialChar ~
4504 foo2.c
4505 \family default
4506 \series default
4507
4508 \newline
4509
4510 \newline
4511 Then compile the source file containing the
4512 \emph on
4513 main()
4514 \emph default
4515  function and link
4516 \begin_inset LatexCommand \index{Linker}
4517
4518 \end_inset
4519
4520  the files together with the following command:
4521 \newline
4522
4523 \newline
4524
4525 \family sans
4526 \series bold
4527 sdcc\SpecialChar ~
4528 foomain.c\SpecialChar ~
4529 foo1.rel\SpecialChar ~
4530 foo2.rel
4531 \family default
4532 \series default
4533
4534 \begin_inset LatexCommand \index{<file>.rel}
4535
4536 \end_inset
4537
4538
4539 \newline
4540
4541 \newline
4542 Alternatively,
4543 \emph on
4544 foomain.c
4545 \emph default
4546 can be separately compiled as well:
4547 \family sans
4548 \series bold
4549
4550 \newline
4551
4552 \newline
4553 sdcc\SpecialChar ~
4554 -c\SpecialChar ~
4555 foomain.c
4556 \newline
4557 sdcc foomain.rel foo1.rel foo2.rel
4558 \newline
4559
4560 \newline
4561
4562 \family default
4563 \series default
4564 The file containing the
4565 \emph on
4566 main()
4567 \emph default
4568  function
4569 \emph on
4570
4571 \emph default
4572 \noun on
4573 must
4574 \noun default
4575  be the
4576 \noun on
4577 first
4578 \noun default
4579  file specified in the command line, since the linkage editor processes
4580  file in the order they are presented to it.
4581  The linker is invoked from SDCC using a script file with extension .lnk
4582 \begin_inset LatexCommand \index{<file>.lnk}
4583
4584 \end_inset
4585
4586 .
4587  You can view this file to troubleshoot linking problems such as those arising
4588  from missing libraries.
4589 \layout Subsection
4590
4591 Projects with Additional Libraries
4592 \begin_inset LatexCommand \index{Libraries}
4593
4594 \end_inset
4595
4596
4597 \layout Standard
4598
4599 Some reusable routines may be compiled into a library, see the documentation
4600  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4601  for how to create a
4602 \emph on
4603 .lib
4604 \begin_inset LatexCommand \index{<file>.lib}
4605
4606 \end_inset
4607
4608
4609 \emph default
4610  library file.
4611  Libraries created in this manner can be included in the command line.
4612  Make sure you include the -L <library-path> option to tell the linker where
4613  to look for these files if they are not in the current directory.
4614  Here is an example, assuming you have the source file
4615 \emph on
4616 foomain.c
4617 \emph default
4618  and a library
4619 \emph on
4620  foolib.lib
4621 \emph default
4622  in the directory
4623 \emph on
4624 mylib
4625 \emph default
4626  (if that is not the same as your current project):
4627 \newline
4628
4629 \newline
4630
4631 \family sans
4632 \series bold
4633 sdcc foomain.c foolib.lib -L mylib
4634 \newline
4635
4636 \newline
4637
4638 \family default
4639 \series default
4640 Note here that
4641 \emph on
4642  mylib
4643 \emph default
4644  must be an absolute path name.
4645 \newline
4646
4647 \newline
4648 The most efficient way to use libraries is to keep separate modules in separate
4649  source files.
4650  The lib file now should name all the modules.rel
4651 \begin_inset LatexCommand \index{<file>.rel}
4652
4653 \end_inset
4654
4655  files.
4656  For an example see the standard library file
4657 \emph on
4658 libsdcc.lib
4659 \emph default
4660  in the directory <installdir>/share/lib/small.
4661 \layout Subsection
4662
4663 Using sdcclib to Create and Manage Libraries
4664 \begin_inset LatexCommand \index{sdcclib}
4665
4666 \end_inset
4667
4668
4669 \layout Standard
4670
4671 Alternatively, instead of having a .rel file for each entry on the library
4672  file as described in the preceding section, sdcclib can be used to embed
4673  all the modules belonging to such library in the library file itself.
4674  This results in a larger library file, but it greatly reduces the number
4675  of disk files accessed by the linker.
4676   Additionally, the packed library file contains an index of all include
4677  modules and symbols that significantly speeds up the linking process.
4678  To display a list of options supported by sdcclib type:
4679 \newline
4680
4681 \layout Standard
4682
4683
4684 \family sans
4685 \series bold
4686 sdcclib -?
4687 \begin_inset LatexCommand \index{sdcclib}
4688
4689 \end_inset
4690
4691
4692 \newline
4693
4694 \newline
4695
4696 \family default
4697 \series default
4698 To create a new library file, start by compiling all the required modules.
4699  For example:
4700 \newline
4701
4702 \layout Standard
4703
4704
4705 \family sans
4706 \series bold
4707 sdcc -c _divsint.c
4708 \layout Standard
4709
4710
4711 \family sans
4712 \series bold
4713 sdcc -c _divuint.c
4714 \layout Standard
4715
4716
4717 \family sans
4718 \series bold
4719 sdcc -c _modsint.c
4720 \layout Standard
4721
4722
4723 \family sans
4724 \series bold
4725 sdcc -c _moduint.c
4726 \layout Standard
4727
4728
4729 \family sans
4730 \series bold
4731 sdcc -c _mulint.c
4732 \newline
4733
4734 \layout Standard
4735
4736 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4737  and _mulint.rel.
4738  The next step is to add the .rel files to the library file:
4739 \newline
4740
4741 \layout Standard
4742
4743
4744 \family sans
4745 \series bold
4746 sdcclib libint.lib _divsint.rel
4747 \family default
4748
4749 \begin_inset LatexCommand \index{sdcclib}
4750
4751 \end_inset
4752
4753
4754 \layout Standard
4755
4756
4757 \family sans
4758 \series bold
4759 sdcclib libint.lib _divuint.rel
4760 \layout Standard
4761
4762
4763 \family sans
4764 \series bold
4765 sdcclib libint.lib _modsint.rel
4766 \layout Standard
4767
4768
4769 \family sans
4770 \series bold
4771 sdcclib libint.lib _moduint.rel
4772 \layout Standard
4773
4774
4775 \family sans
4776 \series bold
4777 sdcclib libint.lib _mulint.rel
4778 \series default
4779
4780 \newline
4781
4782 \layout Standard
4783
4784 If the file already exists in the library, it will be replaced.
4785  To see what modules and symbols are included in the library, options -s
4786  and -m are available.
4787  For example:
4788 \newline
4789
4790 \newline
4791
4792 \family sans
4793 \series bold
4794 sdcclib -s libint.lib
4795 \family default
4796
4797 \begin_inset LatexCommand \index{sdcclib}
4798
4799 \end_inset
4800
4801
4802 \newline
4803
4804 \family typewriter
4805 \series default
4806 _divsint.rel:
4807 \layout Standard
4808
4809
4810 \family typewriter
4811 __divsint_a_1_1
4812 \layout Standard
4813
4814
4815 \family typewriter
4816 __divsint_PARM_2
4817 \layout Standard
4818
4819
4820 \family typewriter
4821 __divsint
4822 \newline
4823 _divuint.rel:
4824 \layout Standard
4825
4826
4827 \family typewriter
4828 __divuint_a_1_1
4829 \layout Standard
4830
4831
4832 \family typewriter
4833 __divuint_PARM_2
4834 \layout Standard
4835
4836
4837 \family typewriter
4838 __divuint_reste_1_1
4839 \layout Standard
4840
4841
4842 \family typewriter
4843 __divuint_count_1_1
4844 \layout Standard
4845
4846
4847 \family typewriter
4848 __divuint
4849 \newline
4850 _modsint.rel:
4851 \layout Standard
4852
4853
4854 \family typewriter
4855 __modsint_a_1_1
4856 \layout Standard
4857
4858
4859 \family typewriter
4860 __modsint_PARM_2
4861 \layout Standard
4862
4863
4864 \family typewriter
4865 __modsint
4866 \newline
4867 _moduint.rel:
4868 \layout Standard
4869
4870
4871 \family typewriter
4872 __moduint_a_1_1
4873 \layout Standard
4874
4875
4876 \family typewriter
4877 __moduint_PARM_2
4878 \layout Standard
4879
4880
4881 \family typewriter
4882 __moduint_count_1_1
4883 \layout Standard
4884
4885
4886 \family typewriter
4887 __moduint
4888 \newline
4889 _mulint.rel:
4890 \layout Standard
4891
4892
4893 \family typewriter
4894 __mulint_PARM_2
4895 \layout Standard
4896
4897
4898 \family typewriter
4899 __mulint
4900 \family default
4901 \series bold
4902
4903 \newline
4904
4905 \layout Standard
4906
4907 If the source files are compiled using -
4908 \begin_inset ERT
4909 status Open
4910
4911 \layout Standard
4912
4913 \backslash
4914 /
4915 \end_inset
4916
4917 -debug
4918 \begin_inset LatexCommand \index{-\/-debug}
4919
4920 \end_inset
4921
4922 , the corresponding debug information file .adb will be include in the library
4923  file as well.
4924  The library files created with sdcclib are plain text files, so they can
4925  be viewed with a text editor.
4926  It is not recomended to modify a library file created with sdcclib using
4927  a text editor, as there are file indexes numbers located accross the file
4928  used by the linker to quickly locate the required module to link.
4929  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
4930  it can be safely deleted, since all the information required for linking
4931  is embedded in the library file itself.
4932  Library files created using sdcclib are used as described in the preceding
4933  sections.
4934 \layout Section
4935
4936 Command Line Options
4937 \begin_inset LatexCommand \index{Command Line Options}
4938
4939 \end_inset
4940
4941
4942 \layout Subsection
4943
4944 Processor Selection Options
4945 \begin_inset LatexCommand \index{Options processor selection}
4946
4947 \end_inset
4948
4949
4950 \begin_inset LatexCommand \index{Processor selection options}
4951
4952 \end_inset
4953
4954
4955 \layout List
4956 \labelwidthstring 00.00.0000
4957
4958
4959 \series bold
4960 -mmcs51
4961 \begin_inset LatexCommand \index{-mmcs51}
4962
4963 \end_inset
4964
4965
4966 \series default
4967  Generate code for the Intel MCS51
4968 \begin_inset LatexCommand \index{MCS51}
4969
4970 \end_inset
4971
4972  family of processors.
4973  This is the default processor target.
4974 \layout List
4975 \labelwidthstring 00.00.0000
4976
4977
4978 \series bold
4979 -mds390
4980 \begin_inset LatexCommand \index{-mds390}
4981
4982 \end_inset
4983
4984
4985 \series default
4986  Generate code for the Dallas DS80C390
4987 \begin_inset LatexCommand \index{DS80C390}
4988
4989 \end_inset
4990
4991  processor.
4992 \layout List
4993 \labelwidthstring 00.00.0000
4994
4995
4996 \series bold
4997 -mds400
4998 \begin_inset LatexCommand \index{-mds400}
4999
5000 \end_inset
5001
5002
5003 \series default
5004  Generate code for the Dallas DS80C400
5005 \begin_inset LatexCommand \index{DS80C400}
5006
5007 \end_inset
5008
5009  processor.
5010 \layout List
5011 \labelwidthstring 00.00.0000
5012
5013
5014 \series bold
5015 -mhc08
5016 \begin_inset LatexCommand \index{-mhc08}
5017
5018 \end_inset
5019
5020
5021 \series default
5022  Generate code for the Freescale/Motorola HC08
5023 \begin_inset LatexCommand \index{HC08}
5024
5025 \end_inset
5026
5027  family of processors.
5028 \layout List
5029 \labelwidthstring 00.00.0000
5030
5031
5032 \series bold
5033 -mz80
5034 \begin_inset LatexCommand \index{-mz80}
5035
5036 \end_inset
5037
5038
5039 \series default
5040  Generate code for the Zilog Z80
5041 \begin_inset LatexCommand \index{Z80}
5042
5043 \end_inset
5044
5045  family of processors.
5046 \layout List
5047 \labelwidthstring 00.00.0000
5048
5049
5050 \series bold
5051 -mgbz80
5052 \begin_inset LatexCommand \index{-mgbz80}
5053
5054 \end_inset
5055
5056
5057 \series default
5058  Generate code for the GameBoy Z80
5059 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5060
5061 \end_inset
5062
5063  processor (Not actively maintained).
5064 \layout List
5065 \labelwidthstring 00.00.0000
5066
5067
5068 \series bold
5069 -mavr
5070 \begin_inset LatexCommand \index{-mavr}
5071
5072 \end_inset
5073
5074
5075 \series default
5076  Generate code for the Atmel AVR
5077 \begin_inset LatexCommand \index{AVR}
5078
5079 \end_inset
5080
5081  processor (In development, not complete).
5082  AVR users should probably have a look at avr-gcc
5083 \begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
5084
5085 \end_inset
5086
5087  or winavr
5088 \begin_inset LatexCommand \url{http://winavr.sourceforge.net}
5089
5090 \end_inset
5091
5092 .
5093 \layout Comment
5094
5095 I think it is fair to direct users there for now.
5096  Open source is also about avoiding unnecessary work .
5097  But I didn't find the 'official' link.
5098 \layout List
5099 \labelwidthstring 00.00.0000
5100
5101
5102 \series bold
5103 -mpic14
5104 \begin_inset LatexCommand \index{-mpic14}
5105
5106 \end_inset
5107
5108
5109 \series default
5110  Generate code for the Microchip PIC 14
5111 \begin_inset LatexCommand \index{PIC14}
5112
5113 \end_inset
5114
5115 -bit processors (p16f84 and variants.
5116  In development, not complete).
5117 \layout Comment
5118
5119 p16f627 p16f628 p16f84 p16f873 p16f877?
5120 \layout List
5121 \labelwidthstring 00.00.0000
5122
5123
5124 \series bold
5125 -mpic16
5126 \begin_inset LatexCommand \index{-mpic16}
5127
5128 \end_inset
5129
5130
5131 \series default
5132  Generate code for the Microchip PIC 16
5133 \begin_inset LatexCommand \index{PIC16}
5134
5135 \end_inset
5136
5137 -bit processors (p18f452 and variants.
5138  In development, not complete).
5139 \layout List
5140 \labelwidthstring 00.00.0000
5141
5142
5143 \series bold
5144 -mtlcs900h
5145 \series default
5146  Generate code for the Toshiba TLCS-900H
5147 \begin_inset LatexCommand \index{TLCS-900H}
5148
5149 \end_inset
5150
5151  processor (Not maintained, not complete).
5152 \layout List
5153 \labelwidthstring 00.00.0000
5154
5155
5156 \series bold
5157 -mxa51
5158 \begin_inset LatexCommand \index{-mxa51}
5159
5160 \end_inset
5161
5162
5163 \series default
5164  Generate code for the Phillips XA51
5165 \begin_inset LatexCommand \index{XA51}
5166
5167 \end_inset
5168
5169  processor (Not maintained, not complete).
5170 \layout Subsection
5171
5172 Preprocessor Options
5173 \begin_inset LatexCommand \index{Options preprocessor}
5174
5175 \end_inset
5176
5177
5178 \begin_inset LatexCommand \index{Preprocessor options}
5179
5180 \end_inset
5181
5182
5183 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5184
5185 \end_inset
5186
5187
5188 \layout List
5189 \labelwidthstring 00.00.0000
5190
5191
5192 \series bold
5193 -I<path>
5194 \begin_inset LatexCommand \index{-I<path>}
5195
5196 \end_inset
5197
5198
5199 \series default
5200  The additional location where the pre processor will look for <..h> or
5201 \begin_inset Quotes eld
5202 \end_inset
5203
5204 ..h
5205 \begin_inset Quotes erd
5206 \end_inset
5207
5208  files.
5209 \layout List
5210 \labelwidthstring 00.00.0000
5211
5212
5213 \series bold
5214 -D<macro[=value]>
5215 \begin_inset LatexCommand \index{-D<macro[=value]>}
5216
5217 \end_inset
5218
5219
5220 \series default
5221  Command line definition of macros.
5222  Passed to the preprocessor.
5223 \layout List
5224 \labelwidthstring 00.00.0000
5225
5226
5227 \series bold
5228 -M
5229 \begin_inset LatexCommand \index{-M}
5230
5231 \end_inset
5232
5233
5234 \series default
5235  Tell the preprocessor to output a rule suitable for make describing the
5236  dependencies of each object file.
5237  For each source file, the preprocessor outputs one make-rule whose target
5238  is the object file name for that source file and whose dependencies are
5239  all the files `#include'd in it.
5240  This rule may be a single line or may be continued with `
5241 \backslash
5242 '-newline if it is long.
5243  The list of rules is printed on standard output instead of the preprocessed
5244  C program.
5245  `-M' implies `-E
5246 \begin_inset LatexCommand \index{-E}
5247
5248 \end_inset
5249
5250 '.
5251 \layout List
5252 \labelwidthstring 00.00.0000
5253
5254
5255 \series bold
5256 -C
5257 \begin_inset LatexCommand \index{-C}
5258
5259 \end_inset
5260
5261
5262 \series default
5263  Tell the preprocessor not to discard comments.
5264  Used with the `-E' option.
5265 \layout List
5266 \labelwidthstring 00.00.0000
5267
5268
5269 \series bold
5270 -MM
5271 \begin_inset LatexCommand \index{-MM}
5272
5273 \end_inset
5274
5275
5276 \size large
5277 \bar under
5278
5279 \series default
5280 \size default
5281 \bar default
5282 Like `-M' but the output mentions only the user header files included with
5283  `#include
5284 \begin_inset Quotes eld
5285 \end_inset
5286
5287 file"'.
5288  System header files included with `#include <file>' are omitted.
5289 \layout List
5290 \labelwidthstring 00.00.0000
5291
5292
5293 \series bold
5294 -Aquestion(answer)
5295 \begin_inset LatexCommand \index{-Aquestion(answer)}
5296
5297 \end_inset
5298
5299
5300 \series default
5301  Assert the answer answer for question, in case it is tested with a preprocessor
5302  conditional such as `#if #question(answer)'.
5303  `-A-' disables the standard assertions that normally describe the target
5304  machine.
5305 \layout List
5306 \labelwidthstring 00.00.0000
5307
5308
5309 \series bold
5310 -Umacro
5311 \begin_inset LatexCommand \index{-Umacro}
5312
5313 \end_inset
5314
5315
5316 \series default
5317  Undefine macro macro.
5318  `-U' options are evaluated after all `-D' options, but before any `-include'
5319  and `-imacros' options.
5320 \layout List
5321 \labelwidthstring 00.00.0000
5322
5323
5324 \series bold
5325 -dM
5326 \begin_inset LatexCommand \index{-dM}
5327
5328 \end_inset
5329
5330
5331 \series default
5332  Tell the preprocessor to output only a list of the macro definitions that
5333  are in effect at the end of preprocessing.
5334  Used with the `-E' option.
5335 \layout List
5336 \labelwidthstring 00.00.0000
5337
5338
5339 \series bold
5340 -dD
5341 \begin_inset LatexCommand \index{-dD}
5342
5343 \end_inset
5344
5345
5346 \series default
5347  Tell the preprocessor to pass all macro definitions into the output, in
5348  their proper sequence in the rest of the output.
5349 \layout List
5350 \labelwidthstring 00.00.0000
5351
5352
5353 \series bold
5354 -dN
5355 \begin_inset LatexCommand \index{-dN}
5356
5357 \end_inset
5358
5359
5360 \size large
5361 \bar under
5362
5363 \series default
5364 \size default
5365 \bar default
5366 Like `-dD' except that the macro arguments and contents are omitted.
5367  Only `#define name' is included in the output.
5368 \layout List
5369 \labelwidthstring 00.00.0000
5370
5371
5372 \series bold
5373 -Wp\SpecialChar ~
5374 preprocessorOption[,preprocessorOption]
5375 \series default
5376
5377 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5378
5379 \end_inset
5380
5381 ...
5382  Pass the preprocessorOption to the preprocessor
5383 \family typewriter
5384 sdcpp
5385 \family default
5386
5387 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5388
5389 \end_inset
5390
5391 .
5392  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5393  Collection (gcc), if you need more dedicated options please refer to the
5394  documentation at
5395 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5396
5397 \end_inset
5398
5399 .
5400 \layout Subsection
5401
5402 Linker Options
5403 \begin_inset LatexCommand \index{Options linker}
5404
5405 \end_inset
5406
5407
5408 \begin_inset LatexCommand \index{Linker options}
5409
5410 \end_inset
5411
5412
5413 \layout List
5414 \labelwidthstring 00.00.0000
5415
5416
5417 \series bold
5418 -L\SpecialChar ~
5419 -
5420 \series default
5421
5422 \begin_inset ERT
5423 status Collapsed
5424
5425 \layout Standard
5426
5427 \backslash
5428 /
5429 \end_inset
5430
5431
5432 \series bold
5433 -lib-path
5434 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5435
5436 \end_inset
5437
5438
5439 \begin_inset LatexCommand \index{-L -\/-lib-path}
5440
5441 \end_inset
5442
5443
5444 \series default
5445 \SpecialChar ~
5446 <absolute path to additional libraries> This option is passed to the linkage
5447  editor's additional libraries
5448 \begin_inset LatexCommand \index{Libraries}
5449
5450 \end_inset
5451
5452  search path.
5453  The path name must be absolute.
5454  Additional library files may be specified in the command line.
5455  See section Compiling programs for more details.
5456 \layout List
5457 \labelwidthstring 00.00.0000
5458
5459
5460 \series bold
5461 -
5462 \begin_inset ERT
5463 status Collapsed
5464
5465 \layout Standard
5466
5467 \backslash
5468 /
5469 \end_inset
5470
5471 -xram-loc
5472 \series default
5473
5474 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5475
5476 \end_inset
5477
5478 \SpecialChar ~
5479 <Value> The start location of the external ram
5480 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5481
5482 \end_inset
5483
5484 , default value is 0.
5485  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5486 \begin_inset ERT
5487 status Collapsed
5488
5489 \layout Standard
5490
5491 \backslash
5492 /
5493 \end_inset
5494
5495 -xram-loc 0x8000 or -
5496 \begin_inset ERT
5497 status Collapsed
5498
5499 \layout Standard
5500
5501 \backslash
5502 /
5503 \end_inset
5504
5505 -xram-loc 32768.
5506 \layout List
5507 \labelwidthstring 00.00.0000
5508
5509
5510 \series bold
5511 -
5512 \begin_inset ERT
5513 status Collapsed
5514
5515 \layout Standard
5516
5517 \backslash
5518 /
5519 \end_inset
5520
5521 -code-loc
5522 \series default
5523
5524 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5525
5526 \end_inset
5527
5528 \SpecialChar ~
5529 <Value> The start location of the code
5530 \begin_inset LatexCommand \index{code}
5531
5532 \end_inset
5533
5534  segment, default value 0.
5535  Note when this option is used the interrupt vector table is also relocated
5536  to the given address.
5537  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5538 \begin_inset ERT
5539 status Collapsed
5540
5541 \layout Standard
5542
5543 \backslash
5544 /
5545 \end_inset
5546
5547 -code-loc 0x8000 or -
5548 \begin_inset ERT
5549 status Collapsed
5550
5551 \layout Standard
5552
5553 \backslash
5554 /
5555 \end_inset
5556
5557 -code-loc 32768.
5558 \layout List
5559 \labelwidthstring 00.00.0000
5560
5561
5562 \series bold
5563 -
5564 \begin_inset ERT
5565 status Collapsed
5566
5567 \layout Standard
5568
5569 \backslash
5570 /
5571 \end_inset
5572
5573 -stack-loc
5574 \series default
5575
5576 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5577
5578 \end_inset
5579
5580 \SpecialChar ~
5581 <Value> By default the stack
5582 \begin_inset LatexCommand \index{stack}
5583
5584 \end_inset
5585
5586  is placed after the data segment.
5587  Using this option the stack can be placed anywhere in the internal memory
5588  space of the 8051.
5589  The value entered can be in Hexadecimal or Decimal format, e.g.
5590  -
5591 \begin_inset ERT
5592 status Collapsed
5593
5594 \layout Standard
5595
5596 \backslash
5597 /
5598 \end_inset
5599
5600 -stack-loc 0x20 or -
5601 \begin_inset ERT
5602 status Collapsed
5603
5604 \layout Standard
5605
5606 \backslash
5607 /
5608 \end_inset
5609
5610 -stack-loc 32.
5611  Since the sp register is incremented before a push or call, the initial
5612  sp will be set to one byte prior the provided value.
5613  The provided value should not overlap any other memory areas such as used
5614  register banks or the data segment and with enough space for the current
5615  application.
5616  The
5617 \series bold
5618 -
5619 \begin_inset ERT
5620 status Collapsed
5621
5622 \layout Standard
5623
5624 \backslash
5625 /
5626 \end_inset
5627
5628 -pack-iram
5629 \series default
5630 \SpecialChar ~
5631
5632 \begin_inset LatexCommand \index{-\/-pack-iram}
5633
5634 \end_inset
5635
5636  option (which is now a default setting) will override this setting, so
5637  you should also specify the .
5638
5639 \series bold
5640 -
5641 \begin_inset ERT
5642 status Collapsed
5643
5644 \layout Standard
5645
5646 \backslash
5647 /
5648 \end_inset
5649
5650 -no-pack-iram
5651 \series default
5652 \SpecialChar ~
5653
5654 \begin_inset LatexCommand \index{-\/-no-pack-iram}
5655
5656 \end_inset
5657
5658  option if you need to manually place the stack.
5659 \layout List
5660 \labelwidthstring 00.00.0000
5661
5662
5663 \series bold
5664 -
5665 \begin_inset ERT
5666 status Collapsed
5667
5668 \layout Standard
5669
5670 \backslash
5671 /
5672 \end_inset
5673
5674 -data-loc
5675 \series default
5676
5677 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5678
5679 \end_inset
5680
5681 \SpecialChar ~
5682 <Value> The start location of the internal ram data
5683 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5684
5685 \end_inset
5686
5687  segment.
5688  The value entered can be in Hexadecimal or Decimal format, eg.
5689  -
5690 \begin_inset ERT
5691 status Collapsed
5692
5693 \layout Standard
5694
5695 \backslash
5696 /
5697 \end_inset
5698
5699 -data-loc 0x20 or -
5700 \begin_inset ERT
5701 status Collapsed
5702
5703 \layout Standard
5704
5705 \backslash
5706 /
5707 \end_inset
5708
5709 -data-loc 32.
5710  (By default, the start location of the internal ram data segment  is set
5711  as low as possible in memory, taking into account the used register banks
5712  and the bit segment at address 0x20.
5713  For example if register banks 0 and 1 are used without bit variables, the
5714  data segment will be set, if -
5715 \begin_inset ERT
5716 status Collapsed
5717
5718 \layout Standard
5719
5720 \backslash
5721 /
5722 \end_inset
5723
5724 -data-loc is not used, to location 0x10.)
5725 \layout List
5726 \labelwidthstring 00.00.0000
5727
5728
5729 \series bold
5730 -
5731 \begin_inset ERT
5732 status Collapsed
5733
5734 \layout Standard
5735
5736 \backslash
5737 /
5738 \end_inset
5739
5740 -idata-loc
5741 \series default
5742
5743 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5744
5745 \end_inset
5746
5747 \SpecialChar ~
5748 <Value> The start location of the indirectly addressable internal ram
5749 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5750
5751 \end_inset
5752
5753  of the 8051, default value is 0x80.
5754  The value entered can be in Hexadecimal or Decimal format, eg.
5755  -
5756 \begin_inset ERT
5757 status Collapsed
5758
5759 \layout Standard
5760
5761 \backslash
5762 /
5763 \end_inset
5764
5765 -idata-loc 0x88 or -
5766 \begin_inset ERT
5767 status Collapsed
5768
5769 \layout Standard
5770
5771 \backslash
5772 /
5773 \end_inset
5774
5775 -idata-loc 136.
5776 \layout List
5777 \labelwidthstring 00.00.0000
5778
5779
5780 \series bold
5781 -
5782 \begin_inset ERT
5783 status Collapsed
5784
5785 \layout Standard
5786
5787 \backslash
5788 /
5789 \end_inset
5790
5791 -bit-loc
5792 \series default
5793 \SpecialChar ~
5794 <Value> The start location of the bit
5795 \begin_inset LatexCommand \index{bit}
5796
5797 \end_inset
5798
5799  addressable internal ram of the 8051.
5800  This is
5801 \emph on
5802 not
5803 \emph default
5804  implemented yet.
5805  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5806 -bBSEG=<Value>.
5807 \layout List
5808 \labelwidthstring 00.00.0000
5809
5810
5811 \series bold
5812 -
5813 \begin_inset ERT
5814 status Collapsed
5815
5816 \layout Standard
5817
5818 \backslash
5819 /
5820 \end_inset
5821
5822 -out-fmt-ihx
5823 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5824
5825 \end_inset
5826
5827
5828 \bar under
5829
5830 \series default
5831 \bar default
5832 The linker output (final object code) is in Intel Hex format.
5833 \begin_inset LatexCommand \index{Intel hex format}
5834
5835 \end_inset
5836
5837  This is the default option.
5838  The format itself is documented in the documentation of srecord
5839 \begin_inset LatexCommand \index{srecord (tool)}
5840
5841 \end_inset
5842
5843 .
5844 \layout List
5845 \labelwidthstring 00.00.0000
5846
5847
5848 \series bold
5849 -
5850 \begin_inset ERT
5851 status Collapsed
5852
5853 \layout Standard
5854
5855 \backslash
5856 /
5857 \end_inset
5858
5859 -out-fmt-s19
5860 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5861
5862 \end_inset
5863
5864
5865 \bar under
5866
5867 \series default
5868 \bar default
5869 The linker output (final object code) is in Motorola S19 format
5870 \begin_inset LatexCommand \index{Motorola S19 format}
5871
5872 \end_inset
5873
5874 .
5875  The format itself is documented in the documentation of srecord.
5876 \layout List
5877 \labelwidthstring 00.00.0000
5878
5879
5880 \series bold
5881 -
5882 \begin_inset ERT
5883 status Collapsed
5884
5885 \layout Standard
5886
5887 \backslash
5888 /
5889 \end_inset
5890
5891 -out-fmt-elf
5892 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5893
5894 \end_inset
5895
5896
5897 \bar under
5898
5899 \series default
5900 \bar default
5901 The linker output (final object code) is in ELF format
5902 \begin_inset LatexCommand \index{ELF format}
5903
5904 \end_inset
5905
5906 .
5907  (Currently only supported for the HC08 processors)
5908 \layout List
5909 \labelwidthstring 00.00.0000
5910
5911
5912 \series bold
5913 -Wl\SpecialChar ~
5914 linkOption[,linkOption]
5915 \series default
5916
5917 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5918
5919 \end_inset
5920
5921 ...
5922  Pass the linkOption to the linker.
5923  See file sdcc/as/doc/asxhtm.html for more on linker options.
5924 \layout Subsection
5925
5926 MCS51 Options
5927 \begin_inset LatexCommand \index{Options MCS51}
5928
5929 \end_inset
5930
5931
5932 \begin_inset LatexCommand \index{MCS51 options}
5933
5934 \end_inset
5935
5936
5937 \layout List
5938 \labelwidthstring 00.00.0000
5939
5940
5941 \series bold
5942 -
5943 \begin_inset ERT
5944 status Collapsed
5945
5946 \layout Standard
5947
5948 \backslash
5949 /
5950 \end_inset
5951
5952 -model-small
5953 \begin_inset LatexCommand \index{-\/-model-small}
5954
5955 \end_inset
5956
5957
5958 \series default
5959 \size large
5960 \emph on
5961
5962 \size default
5963 \emph default
5964 Generate code for Small Model programs, see section Memory Models for more
5965  details.
5966  This is the default model.
5967 \layout List
5968 \labelwidthstring 00.00.0000
5969
5970
5971 \series bold
5972 -
5973 \begin_inset ERT
5974 status Collapsed
5975
5976 \layout Standard
5977
5978 \backslash
5979 /
5980 \end_inset
5981
5982 -model-large
5983 \begin_inset LatexCommand \index{-\/-model-large}
5984
5985 \end_inset
5986
5987
5988 \series default
5989  Generate code for Large model programs, see section Memory Models for more
5990  details.
5991  If this option is used all source files in the project have to be compiled
5992  with this option.
5993 \layout List
5994 \labelwidthstring 00.00.0000
5995
5996
5997 \series bold
5998 -
5999 \begin_inset ERT
6000 status Collapsed
6001
6002 \layout Standard
6003
6004 \backslash
6005 /
6006 \end_inset
6007
6008 -xstack
6009 \begin_inset LatexCommand \index{-\/-xstack}
6010
6011 \end_inset
6012
6013
6014 \series default
6015  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
6016  variables and passing parameters.
6017  See section
6018 \begin_inset LatexCommand \ref{sub:External-Stack}
6019
6020 \end_inset
6021
6022 \SpecialChar ~
6023  External Stack for more details.
6024 \layout List
6025 \labelwidthstring 00.00.0000
6026
6027
6028 \series bold
6029 -
6030 \begin_inset ERT
6031 status Collapsed
6032
6033 \layout Standard
6034
6035 \backslash
6036 /
6037 \end_inset
6038
6039 -iram-size
6040 \series default
6041 \SpecialChar ~
6042 <Value>
6043 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
6044
6045 \end_inset
6046
6047  Causes the linker to check if the internal ram usage is within limits of
6048  the given value.
6049 \layout List
6050 \labelwidthstring 00.00.0000
6051
6052
6053 \series bold
6054 -
6055 \begin_inset ERT
6056 status Collapsed
6057
6058 \layout Standard
6059
6060 \backslash
6061 /
6062 \end_inset
6063
6064 -xram-size
6065 \series default
6066 \SpecialChar ~
6067 <Value>
6068 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
6069
6070 \end_inset
6071
6072  Causes the linker to check if the external ram usage is within limits of
6073  the given value.
6074 \layout List
6075 \labelwidthstring 00.00.0000
6076
6077
6078 \series bold
6079 -
6080 \begin_inset ERT
6081 status Collapsed
6082
6083 \layout Standard
6084
6085 \backslash
6086 /
6087 \end_inset
6088
6089 -code-size
6090 \series default
6091 \SpecialChar ~
6092 <Value>
6093 \begin_inset LatexCommand \index{-\/-code-size <Value>}
6094
6095 \end_inset
6096
6097  Causes the linker to check if the code memory usage is within limits of
6098  the given value.
6099 \layout List
6100 \labelwidthstring 00.00.0000
6101
6102
6103 \series bold
6104 -
6105 \begin_inset ERT
6106 status Collapsed
6107
6108 \layout Standard
6109
6110 \backslash
6111 /
6112 \end_inset
6113
6114 -stack-size
6115 \series default
6116 \SpecialChar ~
6117 <Value>
6118 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6119
6120 \end_inset
6121
6122  Causes the linker to check if there is at minimum <Value> bytes for stack.
6123 \layout List
6124 \labelwidthstring 00.00.0000
6125
6126
6127 \series bold
6128 -
6129 \begin_inset ERT
6130 status Collapsed
6131
6132 \layout Standard
6133
6134 \backslash
6135 /
6136 \end_inset
6137
6138 -pack-iram
6139 \series default
6140 \SpecialChar ~
6141
6142 \begin_inset LatexCommand \index{-\/-pack-iram}
6143
6144 \end_inset
6145
6146  Causes the linker to use unused register banks for data variables and pack
6147  data, idata and stack together.
6148  This is the default now.
6149 \layout List
6150 \labelwidthstring 00.00.0000
6151
6152
6153 \series bold
6154 -
6155 \begin_inset ERT
6156 status Collapsed
6157
6158 \layout Standard
6159
6160 \backslash
6161 /
6162 \end_inset
6163
6164 -no-pack-iram
6165 \series default
6166 \SpecialChar ~
6167
6168 \begin_inset LatexCommand \index{-\/-no-pack-iram}
6169
6170 \end_inset
6171
6172  Causes the linker to use old style for allocating memory areas.
6173 \layout Subsection
6174
6175 DS390 / DS400 Options
6176 \begin_inset LatexCommand \index{Options DS390}
6177
6178 \end_inset
6179
6180
6181 \begin_inset LatexCommand \index{DS390 options}
6182
6183 \end_inset
6184
6185
6186 \layout List
6187 \labelwidthstring 00.00.0000
6188
6189
6190 \series bold
6191 -
6192 \begin_inset ERT
6193 status Collapsed
6194
6195 \layout Standard
6196
6197 \backslash
6198 /
6199 \end_inset
6200
6201 -model-flat24
6202 \series default
6203
6204 \begin_inset LatexCommand \index{-\/-model-flat24}
6205
6206 \end_inset
6207
6208
6209 \size large
6210 \emph on
6211
6212 \size default
6213 \emph default
6214 Generate 24-bit flat mode code.
6215  This is the one and only that the ds390 code generator supports right now
6216  and is default when using
6217 \emph on
6218 -mds390
6219 \emph default
6220 .
6221  See section Memory Models for more details.
6222 \layout List
6223 \labelwidthstring 00.00.0000
6224
6225
6226 \series bold
6227 -
6228 \begin_inset ERT
6229 status Collapsed
6230
6231 \layout Standard
6232
6233 \backslash
6234 /
6235 \end_inset
6236
6237 -protect-sp-update
6238 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6239
6240 \end_inset
6241
6242
6243 \series default
6244  disable interrupts during ESP:SP updates.
6245 \layout List
6246 \labelwidthstring 00.00.0000
6247
6248
6249 \series bold
6250 -
6251 \begin_inset ERT
6252 status Collapsed
6253
6254 \layout Standard
6255
6256 \backslash
6257 /
6258 \end_inset
6259
6260 -stack-10bit
6261 \series default
6262
6263 \begin_inset LatexCommand \index{-\/-stack-10bit}
6264
6265 \end_inset
6266
6267  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6268  This is the one and only that the ds390 code generator supports right now
6269  and is default when using
6270 \emph on
6271 -mds390
6272 \emph default
6273 .
6274  In this mode, the stack is located in the lower 1K of the internal RAM,
6275  which is mapped to 0x400000.
6276  Note that the support is incomplete, since it still uses a single byte
6277  as the stack pointer.
6278  This means that only the lower 256 bytes of the potential 1K stack space
6279  will actually be used.
6280  However, this does allow you to reclaim the precious 256 bytes of low RAM
6281  for use for the DATA and IDATA segments.
6282  The compiler will not generate any code to put the processor into 10 bit
6283  stack mode.
6284  It is important to ensure that the processor is in this mode before calling
6285  any re-entrant functions compiled with this option.
6286  In principle, this should work with the
6287 \emph on
6288 -
6289 \begin_inset ERT
6290 status Collapsed
6291
6292 \layout Standard
6293
6294 \backslash
6295 /
6296 \end_inset
6297
6298 -stack-auto
6299 \begin_inset LatexCommand \index{-\/-stack-auto}
6300
6301 \end_inset
6302
6303
6304 \emph default
6305  option, but that has not been tested.
6306  It is incompatible with the
6307 \emph on
6308 -
6309 \begin_inset ERT
6310 status Collapsed
6311
6312 \layout Standard
6313
6314 \backslash
6315 /
6316 \end_inset
6317
6318 -xstack
6319 \begin_inset LatexCommand \index{-\/-xstack}
6320
6321 \end_inset
6322
6323
6324 \emph default
6325  option.
6326  It also only makes sense if the processor is in 24 bit contiguous addressing
6327  mode (see the
6328 \emph on
6329 -
6330 \begin_inset ERT
6331 status Collapsed
6332
6333 \layout Standard
6334
6335 \backslash
6336 /
6337 \end_inset
6338
6339 -model-flat24 option
6340 \emph default
6341 ).
6342 \layout List
6343 \labelwidthstring 00.00.0000
6344
6345
6346 \series bold
6347 -
6348 \begin_inset ERT
6349 status Collapsed
6350
6351 \layout Standard
6352
6353 \backslash
6354 /
6355 \end_inset
6356
6357 -stack-probe
6358 \begin_inset LatexCommand \index{-\/-stack-probe}
6359
6360 \end_inset
6361
6362
6363 \series default
6364  insert call to function __stack_probe at each function prologue.
6365 \layout List
6366 \labelwidthstring 00.00.0000
6367
6368
6369 \series bold
6370 -
6371 \begin_inset ERT
6372 status Collapsed
6373
6374 \layout Standard
6375
6376 \backslash
6377 /
6378 \end_inset
6379
6380 -tini-libid
6381 \begin_inset LatexCommand \index{-\/-tini-libid}
6382
6383 \end_inset
6384
6385
6386 \series default
6387  <nnnn> LibraryID used in -mTININative.
6388
6389 \layout List
6390 \labelwidthstring 00.00.0000
6391
6392
6393 \series bold
6394 -
6395 \begin_inset ERT
6396 status Collapsed
6397
6398 \layout Standard
6399
6400 \backslash
6401 /
6402 \end_inset
6403
6404 -use-accelerator
6405 \begin_inset LatexCommand \index{-\/-use-accelerator}
6406
6407 \end_inset
6408
6409
6410 \series default
6411  generate code for DS390 Arithmetic Accelerator.
6412
6413 \layout Subsection
6414
6415 Z80 Options
6416 \begin_inset LatexCommand \index{Options Z80}
6417
6418 \end_inset
6419
6420
6421 \begin_inset LatexCommand \index{Z80 options}
6422
6423 \end_inset
6424
6425
6426 \layout List
6427 \labelwidthstring 00.00.0000
6428
6429
6430 \series bold
6431 -
6432 \begin_inset ERT
6433 status Collapsed
6434
6435 \layout Standard
6436
6437 \backslash
6438 /
6439 \end_inset
6440
6441 -callee-saves-bc
6442 \series default
6443
6444 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6445
6446 \end_inset
6447
6448
6449 \size large
6450 \emph on
6451
6452 \size default
6453 \emph default
6454 Force a called function to always save BC.
6455 \layout List
6456 \labelwidthstring 00.00.0000
6457
6458
6459 \series bold
6460 -
6461 \begin_inset ERT
6462 status Collapsed
6463
6464 \layout Standard
6465
6466 \backslash
6467 /
6468 \end_inset
6469
6470 -no-std-crt0
6471 \series default
6472
6473 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6474
6475 \end_inset
6476
6477  When linking, skip the standard crt0.o object file.
6478  You must provide your own crt0.o for your system when linking.
6479
6480 \layout Subsection
6481
6482 Optimization Options
6483 \begin_inset LatexCommand \index{Options optimization}
6484
6485 \end_inset
6486
6487
6488 \begin_inset LatexCommand \index{Optimization options}
6489
6490 \end_inset
6491
6492
6493 \layout List
6494 \labelwidthstring 00.00.0000
6495
6496
6497 \series bold
6498 -
6499 \begin_inset ERT
6500 status Collapsed
6501
6502 \layout Standard
6503
6504 \backslash
6505 /
6506 \end_inset
6507
6508 -nogcse
6509 \begin_inset LatexCommand \index{-\/-nogcse}
6510
6511 \end_inset
6512
6513
6514 \series default
6515  Will not do global subexpression elimination, this option may be used when
6516  the compiler creates undesirably large stack/data spaces to store compiler
6517  temporaries.
6518  A warning message will be generated when this happens and the compiler
6519  will indicate the number of extra bytes it allocated.
6520  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6521 nogcse
6522 \begin_inset LatexCommand \index{\#pragma nogcse}
6523
6524 \end_inset
6525
6526  can be used to turn off global subexpression elimination
6527 \begin_inset LatexCommand \index{Subexpression elimination}
6528
6529 \end_inset
6530
6531  for a given function only.
6532 \layout List
6533 \labelwidthstring 00.00.0000
6534
6535
6536 \series bold
6537 -
6538 \begin_inset ERT
6539 status Collapsed
6540
6541 \layout Standard
6542
6543 \backslash
6544 /
6545 \end_inset
6546
6547 -noinvariant
6548 \begin_inset LatexCommand \index{-\/-noinvariant}
6549
6550 \end_inset
6551
6552
6553 \series default
6554  Will not do loop invariant optimizations, this may be turned off for reasons
6555  explained for the previous option.
6556  For more details of loop optimizations performed see Loop Invariants in
6557  section
6558 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6559
6560 \end_inset
6561
6562 .
6563  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6564 noinvariant
6565 \begin_inset LatexCommand \index{\#pragma noinvariant}
6566
6567 \end_inset
6568
6569  can be used to turn off invariant optimizations for a given function only.
6570 \layout List
6571 \labelwidthstring 00.00.0000
6572
6573
6574 \series bold
6575 -
6576 \begin_inset ERT
6577 status Collapsed
6578
6579 \layout Standard
6580
6581 \backslash
6582 /
6583 \end_inset
6584
6585 -noinduction
6586 \begin_inset LatexCommand \index{-\/-noinduction}
6587
6588 \end_inset
6589
6590
6591 \series default
6592  Will not do loop induction optimizations, see section strength reduction
6593  for more details.
6594  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6595 noinduction
6596 \begin_inset LatexCommand \index{\#pragma noinduction}
6597
6598 \end_inset
6599
6600  can be used to turn off induction optimizations for a given function only.
6601 \layout List
6602 \labelwidthstring 00.00.0000
6603
6604
6605 \series bold
6606 -
6607 \begin_inset ERT
6608 status Collapsed
6609
6610 \layout Standard
6611
6612 \backslash
6613 /
6614 \end_inset
6615
6616 -nojtbound
6617 \begin_inset LatexCommand \index{-\/-nojtbound}
6618
6619 \end_inset
6620
6621
6622 \size large
6623 \bar under
6624
6625 \series default
6626 \size default
6627 \bar default
6628  Will not generate boundary condition check when switch statements
6629 \begin_inset LatexCommand \index{switch statement}
6630
6631 \end_inset
6632
6633  are implemented using jump-tables.
6634  See section
6635 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6636
6637 \end_inset
6638
6639 \SpecialChar ~
6640 Switch Statements for more details.
6641  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6642 nojtbound
6643 \begin_inset LatexCommand \index{\#pragma nojtbound}
6644
6645 \end_inset
6646
6647  can be used to turn off boundary checking for jump tables for a given function
6648  only.
6649 \layout List
6650 \labelwidthstring 00.00.0000
6651
6652
6653 \series bold
6654 -
6655 \begin_inset ERT
6656 status Collapsed
6657
6658 \layout Standard
6659
6660 \backslash
6661 /
6662 \end_inset
6663
6664 -noloopreverse
6665 \begin_inset LatexCommand \index{-\/-noloopreverse}
6666
6667 \end_inset
6668
6669
6670 \series default
6671 \size large
6672
6673 \size default
6674 Will not do loop reversal
6675 \begin_inset LatexCommand \index{Loop reversing}
6676
6677 \end_inset
6678
6679 optimization.
6680 \layout List
6681 \labelwidthstring 00.00.0000
6682
6683 -
6684 \begin_inset ERT
6685 status Collapsed
6686
6687 \layout Standard
6688
6689 \backslash
6690 /
6691 \end_inset
6692
6693 -
6694 \series bold
6695 nolabelopt
6696 \series default
6697
6698 \begin_inset LatexCommand \index{-\/-nolabelopt }
6699
6700 \end_inset
6701
6702 Will not optimize labels (makes the dumpfiles more readable).
6703 \layout List
6704 \labelwidthstring 00.00.0000
6705
6706
6707 \series bold
6708 -
6709 \begin_inset ERT
6710 status Collapsed
6711
6712 \layout Standard
6713
6714 \backslash
6715 /
6716 \end_inset
6717
6718 -no-xinit-opt
6719 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6720
6721 \end_inset
6722
6723
6724 \series default
6725  Will not memcpy initialized data from code space into xdata space.
6726  This saves a few bytes in code space if you don't have initialized data.
6727 \layout List
6728 \labelwidthstring 00.00.0000
6729
6730
6731 \series bold
6732 -
6733 \begin_inset ERT
6734 status Collapsed
6735
6736 \layout Standard
6737
6738 \backslash
6739 /
6740 \end_inset
6741
6742 -nooverlay
6743 \begin_inset LatexCommand \index{-\/-nooverlay}
6744
6745 \end_inset
6746
6747
6748 \series default
6749   The compiler will not overlay parameters and local variables of any function,
6750  see section Parameters and local variables for more details.
6751 \layout List
6752 \labelwidthstring 00.00.0000
6753
6754
6755 \series bold
6756 -
6757 \begin_inset ERT
6758 status Collapsed
6759
6760 \layout Standard
6761
6762 \backslash
6763 /
6764 \end_inset
6765
6766 -no-peep
6767 \begin_inset LatexCommand \index{-\/-no-peep}
6768
6769 \end_inset
6770
6771
6772 \series default
6773  Disable peep-hole optimization.
6774 \layout List
6775 \labelwidthstring 00.00.0000
6776
6777
6778 \series bold
6779 -
6780 \begin_inset ERT
6781 status Collapsed
6782
6783 \layout Standard
6784
6785 \backslash
6786 /
6787 \end_inset
6788
6789 -peep-file
6790 \series default
6791
6792 \begin_inset LatexCommand \index{-\/-peep-file}
6793
6794 \end_inset
6795
6796 \SpecialChar ~
6797 <filename> This option can be used to use additional rules to be used by
6798  the peep hole optimizer.
6799  See section
6800 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6801
6802 \end_inset
6803
6804 \SpecialChar ~
6805 Peep Hole optimizations for details on how to write these rules.
6806 \layout List
6807 \labelwidthstring 00.00.0000
6808
6809
6810 \series bold
6811 -
6812 \begin_inset ERT
6813 status Collapsed
6814
6815 \layout Standard
6816
6817 \backslash
6818 /
6819 \end_inset
6820
6821 -peep-asm
6822 \begin_inset LatexCommand \index{-\/-peep-asm}
6823
6824 \end_inset
6825
6826
6827 \series default
6828  Pass the inline assembler code through the peep hole optimizer.
6829  This can cause unexpected changes to inline assembler code, please go through
6830  the peephole optimizer
6831 \begin_inset LatexCommand \index{Peephole optimizer}
6832
6833 \end_inset
6834
6835  rules defined in the source file tree '<target>/peeph.def' before using
6836  this option.
6837 \layout List
6838 \labelwidthstring 00.00.0000
6839
6840
6841 \series bold
6842 -
6843 \begin_inset ERT
6844 status Collapsed
6845
6846 \layout Standard
6847
6848 \backslash
6849 /
6850 \end_inset
6851
6852 -opt-code-speed
6853 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6854
6855 \end_inset
6856
6857
6858 \series default
6859  The compiler will optimize code generation towards fast code, possibly
6860  at the expense of code size.
6861 \layout List
6862 \labelwidthstring 00.00.0000
6863
6864
6865 \series bold
6866 -
6867 \begin_inset ERT
6868 status Collapsed
6869
6870 \layout Standard
6871
6872 \backslash
6873 /
6874 \end_inset
6875
6876 -opt-code-size
6877 \begin_inset LatexCommand \index{-\/-opt-code-size}
6878
6879 \end_inset
6880
6881
6882 \series default
6883  The compiler will optimize code generation towards compact code, possibly
6884  at the expense of code speed.
6885 \layout Subsection
6886
6887 Other Options
6888 \begin_inset LatexCommand \index{Options other}
6889
6890 \end_inset
6891
6892
6893 \layout List
6894 \labelwidthstring 00.00.0000
6895
6896
6897 \series bold
6898 -c\SpecialChar ~
6899 -
6900 \begin_inset ERT
6901 status Collapsed
6902
6903 \layout Standard
6904
6905 \backslash
6906 /
6907 \end_inset
6908
6909 -compile-only
6910 \begin_inset LatexCommand \index{-\/-compile-only}
6911
6912 \end_inset
6913
6914
6915 \begin_inset LatexCommand \index{-c -\/-compile-only}
6916
6917 \end_inset
6918
6919
6920 \series default
6921  will compile and assemble the source, but will not call the linkage editor.
6922 \layout List
6923 \labelwidthstring 00.00.0000
6924
6925
6926 \series bold
6927 -
6928 \series default
6929
6930 \begin_inset ERT
6931 status Collapsed
6932
6933 \layout Standard
6934
6935 \backslash
6936 /
6937 \end_inset
6938
6939
6940 \series bold
6941 -c1mode
6942 \begin_inset LatexCommand \index{-\/-c1mode}
6943
6944 \end_inset
6945
6946
6947 \series default
6948  reads the preprocessed source from standard input and compiles it.
6949  The file name for the assembler output must be specified using the -o option.
6950 \layout List
6951 \labelwidthstring 00.00.0000
6952
6953
6954 \series bold
6955 -E
6956 \begin_inset LatexCommand \index{-E}
6957
6958 \end_inset
6959
6960
6961 \series default
6962  Run only the C preprocessor.
6963  Preprocess all the C source files specified and output the results to standard
6964  output.
6965 \layout List
6966 \labelwidthstring 00.00.0000
6967
6968
6969 \series bold
6970 -o\SpecialChar ~
6971 <path/file>
6972 \begin_inset LatexCommand \index{-o <path/file>}
6973
6974 \end_inset
6975
6976
6977 \series default
6978 The output path resp.
6979  file where everything will be placed.
6980  If the parameter is a path, it must have a trailing slash (or backslash
6981  for the Windows binaries) to be recognized as a path.
6982
6983 \layout List
6984 \labelwidthstring 00.00.0000
6985
6986
6987 \series bold
6988 -
6989 \begin_inset ERT
6990 status Collapsed
6991
6992 \layout Standard
6993
6994 \backslash
6995 /
6996 \end_inset
6997
6998 -stack-auto
6999 \begin_inset LatexCommand \index{-\/-stack-auto}
7000
7001 \end_inset
7002
7003
7004 \series default
7005 \size large
7006 \emph on
7007
7008 \size default
7009 \emph default
7010 All functions in the source file will be compiled as
7011 \emph on
7012 reentrant
7013 \emph default
7014
7015 \begin_inset LatexCommand \index{reentrant}
7016
7017 \end_inset
7018
7019 , i.e.
7020  the parameters and local variables will be allocated on the stack
7021 \begin_inset LatexCommand \index{stack}
7022
7023 \end_inset
7024
7025 .
7026  See section
7027 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
7028
7029 \end_inset
7030
7031  Parameters and Local Variables for more details.
7032  If this option is used all source files in the project should be compiled
7033  with this option.
7034  It automatically implies --int-long-reent and --float-reent.
7035
7036 \layout List
7037 \labelwidthstring 00.00.0000
7038
7039
7040 \series bold
7041 -
7042 \begin_inset ERT
7043 status Collapsed
7044
7045 \layout Standard
7046
7047 \backslash
7048 /
7049 \end_inset
7050
7051 -callee-saves
7052 \begin_inset LatexCommand \index{-\/-callee-saves}
7053
7054 \end_inset
7055
7056  function1[,function2][,function3]....
7057
7058 \series default
7059  The compiler by default uses a caller saves convention for register saving
7060  across function calls, however this can cause unnecessary register pushing
7061  & popping when calling small functions from larger functions.
7062  This option can be used to switch the register saving convention for the
7063  function names specified.
7064  The compiler will not save registers when calling these functions, no extra
7065  code will be generated at the entry & exit (function prologue
7066 \series bold
7067
7068 \begin_inset LatexCommand \index{function prologue}
7069
7070 \end_inset
7071
7072
7073 \series default
7074  & epilogue
7075 \series bold
7076
7077 \begin_inset LatexCommand \index{function epilogue}
7078
7079 \end_inset
7080
7081
7082 \series default
7083 ) for these functions to save & restore the registers used by these functions,
7084  this can SUBSTANTIALLY reduce code & improve run time performance of the
7085  generated code.
7086  In the future the compiler (with inter procedural analysis) will be able
7087  to determine the appropriate scheme to use for each function call.
7088  DO NOT use this option for built-in functions such as _mulint..., if this
7089  option is used for a library function the appropriate library function
7090  needs to be recompiled with the same option.
7091  If the project consists of multiple source files then all the source file
7092  should be compiled with the same -
7093 \begin_inset ERT
7094 status Collapsed
7095
7096 \layout Standard
7097
7098 \backslash
7099 /
7100 \end_inset
7101
7102 -callee-saves option string.
7103  Also see #pragma\SpecialChar ~
7104 callee_saves
7105 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7106
7107 \end_inset
7108
7109 .
7110 \layout List
7111 \labelwidthstring 00.00.0000
7112
7113
7114 \series bold
7115 -
7116 \begin_inset ERT
7117 status Collapsed
7118
7119 \layout Standard
7120
7121 \backslash
7122 /
7123 \end_inset
7124
7125 -debug
7126 \begin_inset LatexCommand \index{-\/-debug}
7127
7128 \end_inset
7129
7130
7131 \bar under
7132
7133 \series default
7134 \bar default
7135 When this option is used the compiler will generate debug information.
7136  The debug information collected in a file with .cdb extension can be used
7137  with the SDCDB.
7138  For more information see documentation for SDCDB.
7139  Another file with no extension contains debug information in AOMF or AOMF51
7140 \begin_inset LatexCommand \index{AOMF, AOMF51}
7141
7142 \end_inset
7143
7144  format which is commonly used by third party tools.
7145 \layout List
7146 \labelwidthstring 00.00.0000
7147
7148
7149 \series bold
7150 -S
7151 \begin_inset LatexCommand \index{-S}
7152
7153 \end_inset
7154
7155
7156 \size large
7157 \bar under
7158
7159 \series default
7160 \size default
7161 \bar default
7162 Stop after the stage of compilation proper; do not assemble.
7163  The output is an assembler code file for the input file specified.
7164 \layout List
7165 \labelwidthstring 00.00.0000
7166
7167
7168 \series bold
7169 -
7170 \begin_inset ERT
7171 status Collapsed
7172
7173 \layout Standard
7174
7175 \backslash
7176 /
7177 \end_inset
7178
7179 -int-long-reent
7180 \begin_inset LatexCommand \index{-\/-int-long-reent}
7181
7182 \end_inset
7183
7184
7185 \series default
7186  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7187  Note by default these libraries are compiled as non-reentrant.
7188  See section Installation for more details.
7189 \layout List
7190 \labelwidthstring 00.00.0000
7191
7192
7193 \series bold
7194 -
7195 \begin_inset ERT
7196 status Collapsed
7197
7198 \layout Standard
7199
7200 \backslash
7201 /
7202 \end_inset
7203
7204 -cyclomatic
7205 \begin_inset LatexCommand \index{-\/-cyclomatic}
7206
7207 \end_inset
7208
7209
7210 \bar under
7211
7212 \series default
7213 \bar default
7214 This option will cause the compiler to generate an information message for
7215  each function in the source file.
7216  The message contains some
7217 \emph on
7218 important
7219 \emph default
7220  information about the function.
7221  The number of edges and nodes the compiler detected in the control flow
7222  graph of the function, and most importantly the
7223 \emph on
7224 cyclomatic complexity
7225 \begin_inset LatexCommand \index{Cyclomatic complexity}
7226
7227 \end_inset
7228
7229
7230 \emph default
7231  see section on Cyclomatic Complexity for more details.
7232 \layout List
7233 \labelwidthstring 00.00.0000
7234
7235
7236 \series bold
7237 -
7238 \begin_inset ERT
7239 status Collapsed
7240
7241 \layout Standard
7242
7243 \backslash
7244 /
7245 \end_inset
7246
7247 -float-reent
7248 \begin_inset LatexCommand \index{-\/-float-reent}
7249
7250 \end_inset
7251
7252
7253 \series default
7254  Floating point library is compiled as reentrant
7255 \begin_inset LatexCommand \index{reentrant}
7256
7257 \end_inset
7258
7259 .
7260  See section Installation for more details.
7261 \layout List
7262 \labelwidthstring 00.00.0000
7263
7264
7265 \series bold
7266 -
7267 \begin_inset ERT
7268 status Collapsed
7269
7270 \layout Standard
7271
7272 \backslash
7273 /
7274 \end_inset
7275
7276 -main-return
7277 \begin_inset LatexCommand \index{-\/-main-return}
7278
7279 \end_inset
7280
7281
7282 \series default
7283  This option can be used if the code generated is called by a monitor program
7284  or if the main routine includes an endless loop.
7285  This option might result in slightly smaller code and save two bytes of
7286  stack space.
7287  The return from the 'main'
7288 \begin_inset LatexCommand \index{main return}
7289
7290 \end_inset
7291
7292  function will return to the function calling main.
7293  The default setting is to lock up i.e.
7294  generate a '
7295 \family typewriter
7296 sjmp .
7297 \family default
7298 '.
7299 \layout List
7300 \labelwidthstring 00.00.0000
7301
7302
7303 \series bold
7304 -
7305 \begin_inset ERT
7306 status Collapsed
7307
7308 \layout Standard
7309
7310 \backslash
7311 /
7312 \end_inset
7313
7314 -nostdinc
7315 \begin_inset LatexCommand \index{-\/-nostdinc}
7316
7317 \end_inset
7318
7319
7320 \series default
7321  This will prevent the compiler from passing on the default include path
7322  to the preprocessor.
7323 \layout List
7324 \labelwidthstring 00.00.0000
7325
7326
7327 \series bold
7328 -
7329 \begin_inset ERT
7330 status Collapsed
7331
7332 \layout Standard
7333
7334 \backslash
7335 /
7336 \end_inset
7337
7338 -nostdlib
7339 \begin_inset LatexCommand \index{-\/-nostdlib}
7340
7341 \end_inset
7342
7343
7344 \series default
7345  This will prevent the compiler from passing on the default library
7346 \begin_inset LatexCommand \index{Libraries}
7347
7348 \end_inset
7349
7350  path to the linker.
7351 \layout List
7352 \labelwidthstring 00.00.0000
7353
7354
7355 \series bold
7356 -
7357 \begin_inset ERT
7358 status Collapsed
7359
7360 \layout Standard
7361
7362 \backslash
7363 /
7364 \end_inset
7365
7366 -verbose
7367 \begin_inset LatexCommand \index{-\/-verbose}
7368
7369 \end_inset
7370
7371
7372 \series default
7373  Shows the various actions the compiler is performing.
7374 \layout List
7375 \labelwidthstring 00.00.0000
7376
7377
7378 \series bold
7379 -V
7380 \begin_inset LatexCommand \index{-V}
7381
7382 \end_inset
7383
7384
7385 \series default
7386  Shows the actual commands the compiler is executing.
7387 \layout List
7388 \labelwidthstring 00.00.0000
7389
7390
7391 \series bold
7392 -
7393 \begin_inset ERT
7394 status Collapsed
7395
7396 \layout Standard
7397
7398 \backslash
7399 /
7400 \end_inset
7401
7402 -no-c-code-in-asm
7403 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7404
7405 \end_inset
7406
7407
7408 \series default
7409  Hides your ugly and inefficient c-code from the asm file, so you can always
7410  blame the compiler :)
7411 \layout List
7412 \labelwidthstring 00.00.0000
7413
7414
7415 \series bold
7416 -
7417 \begin_inset ERT
7418 status Collapsed
7419
7420 \layout Standard
7421
7422 \backslash
7423 /
7424 \end_inset
7425
7426 -no-peep-comments
7427 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7428
7429 \end_inset
7430
7431
7432 \series default
7433  Will not include peep-hole comments in the generated files.
7434 \layout List
7435 \labelwidthstring 00.00.0000
7436
7437
7438 \series bold
7439 -
7440 \begin_inset ERT
7441 status Collapsed
7442
7443 \layout Standard
7444
7445 \backslash
7446 /
7447 \end_inset
7448
7449 -i-code-in-asm
7450 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7451
7452 \end_inset
7453
7454
7455 \series default
7456  Include i-codes in the asm file.
7457  Sounds like noise but is most helpful for debugging the compiler itself.
7458 \layout List
7459 \labelwidthstring 00.00.0000
7460
7461
7462 \series bold
7463 -
7464 \begin_inset ERT
7465 status Collapsed
7466
7467 \layout Standard
7468
7469 \backslash
7470 /
7471 \end_inset
7472
7473 -less-pedantic
7474 \begin_inset LatexCommand \index{-\/-less-pedantic}
7475
7476 \end_inset
7477
7478
7479 \series default
7480  Disable some of the more pedantic warnings
7481 \begin_inset LatexCommand \index{Warnings}
7482
7483 \end_inset
7484
7485  (jwk burps: please be more specific here, please!).
7486  If you want rather more than less warnings you should consider using a
7487  separate tool dedicated to syntax checking like splint
7488 \begin_inset LatexCommand \url{www.splint.org}
7489
7490 \end_inset
7491
7492 .
7493 \layout List
7494 \labelwidthstring 00.00.0000
7495
7496
7497 \series bold
7498 -
7499 \begin_inset ERT
7500 status Collapsed
7501
7502 \layout Standard
7503
7504 \backslash
7505 /
7506 \end_inset
7507
7508 -disable-warning\SpecialChar ~
7509 <nnnn>
7510 \begin_inset LatexCommand \index{-\/-disable-warning}
7511
7512 \end_inset
7513
7514
7515 \series default
7516  Disable specific warning with number <nnnn>.
7517 \layout List
7518 \labelwidthstring 00.00.0000
7519
7520
7521 \series bold
7522 -
7523 \begin_inset ERT
7524 status Collapsed
7525
7526 \layout Standard
7527
7528 \backslash
7529 /
7530 \end_inset
7531
7532 -print-search-dirs
7533 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7534
7535 \end_inset
7536
7537
7538 \series default
7539  Display the directories in the compiler's search path
7540 \layout List
7541 \labelwidthstring 00.00.0000
7542
7543
7544 \series bold
7545 -
7546 \begin_inset ERT
7547 status Collapsed
7548
7549 \layout Standard
7550
7551 \backslash
7552 /
7553 \end_inset
7554
7555 -vc
7556 \begin_inset LatexCommand \index{-\/-vc}
7557
7558 \end_inset
7559
7560
7561 \series default
7562  Display errors and warnings using MSVC style, so you can use SDCC with
7563  visual studio.
7564 \layout List
7565 \labelwidthstring 00.00.0000
7566
7567
7568 \series bold
7569 -
7570 \begin_inset ERT
7571 status Collapsed
7572
7573 \layout Standard
7574
7575 \backslash
7576 /
7577 \end_inset
7578
7579 -use-stdout
7580 \begin_inset LatexCommand \index{-\/-use-stdout}
7581
7582 \end_inset
7583
7584
7585 \series default
7586  Send errors and warnings to stdout instead of stderr.
7587 \layout List
7588 \labelwidthstring 00.00.0000
7589
7590
7591 \series bold
7592 -Wa\SpecialChar ~
7593 asmOption[,asmOption]
7594 \series default
7595
7596 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7597
7598 \end_inset
7599
7600 ...
7601  Pass the asmOption to the assembler
7602 \begin_inset LatexCommand \index{Options assembler}
7603
7604 \end_inset
7605
7606
7607 \begin_inset LatexCommand \index{Assembler options}
7608
7609 \end_inset
7610
7611 .
7612  See file sdcc/as/doc/asxhtm.html for assembler options.
7613 \layout List
7614 \labelwidthstring 00.00.0000
7615
7616
7617 \series bold
7618 -
7619 \begin_inset ERT
7620 status Collapsed
7621
7622 \layout Standard
7623
7624 \backslash
7625 /
7626 \end_inset
7627
7628 -std-sdcc89
7629 \begin_inset LatexCommand \index{-\/-std-sdcc89}
7630
7631 \end_inset
7632
7633
7634 \series default
7635  Generally follow the C89 standard, but allow SDCC features that conflict
7636  with the standard (default).
7637 \layout List
7638 \labelwidthstring 00.00.0000
7639
7640
7641 \series bold
7642 -
7643 \begin_inset ERT
7644 status Collapsed
7645
7646 \layout Standard
7647
7648 \backslash
7649 /
7650 \end_inset
7651
7652 -std-c89
7653 \begin_inset LatexCommand \index{-\/-std-c89}
7654
7655 \end_inset
7656
7657
7658 \series default
7659  Follow the C89 standard and disable SDCC features that conflict with the
7660  standard.
7661 \layout List
7662 \labelwidthstring 00.00.0000
7663
7664
7665 \series bold
7666 -
7667 \begin_inset ERT
7668 status Collapsed
7669
7670 \layout Standard
7671
7672 \backslash
7673 /
7674 \end_inset
7675
7676 -std-sdcc99
7677 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7678
7679 \end_inset
7680
7681
7682 \series default
7683  Generally follow the C99 standard, but allow SDCC features that conflict
7684  with the standard (incomplete support).
7685 \layout List
7686 \labelwidthstring 00.00.0000
7687
7688
7689 \series bold
7690 -
7691 \begin_inset ERT
7692 status Collapsed
7693
7694 \layout Standard
7695
7696 \backslash
7697 /
7698 \end_inset
7699
7700 -std-c99
7701 \begin_inset LatexCommand \index{-\/-std-sdcc99}
7702
7703 \end_inset
7704
7705
7706 \series default
7707  Follow the C99 standard and disable SDCC features that conflict with the
7708  standard (incomplete support).
7709 \layout Subsection
7710
7711 Intermediate Dump Options
7712 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7713
7714 \end_inset
7715
7716
7717 \begin_inset LatexCommand \index{Options intermediate dump}
7718
7719 \end_inset
7720
7721
7722 \begin_inset LatexCommand \index{Intermediate dump options}
7723
7724 \end_inset
7725
7726
7727 \layout Standard
7728
7729 The following options are provided for the purpose of retargetting and debugging
7730  the compiler.
7731  These provided a means to dump the intermediate code (iCode
7732 \begin_inset LatexCommand \index{iCode}
7733
7734 \end_inset
7735
7736 ) generated by the compiler in human readable form at various stages of
7737  the compilation process.
7738  More on iCodes see chapter
7739 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7740
7741 \end_inset
7742
7743
7744 \begin_inset Quotes srd
7745 \end_inset
7746
7747 The anatomy of the compiler
7748 \begin_inset Quotes srd
7749 \end_inset
7750
7751 .
7752 \layout List
7753 \labelwidthstring 00.00.0000
7754
7755
7756 \series bold
7757 -
7758 \begin_inset ERT
7759 status Collapsed
7760
7761 \layout Standard
7762
7763 \backslash
7764 /
7765 \end_inset
7766
7767 -dumpraw
7768 \begin_inset LatexCommand \index{-\/-dumpraw}
7769
7770 \end_inset
7771
7772
7773 \series default
7774  This option will cause the compiler to dump the intermediate code into
7775  a file of named
7776 \emph on
7777 <source filename>.dumpraw
7778 \emph default
7779  just after the intermediate code has been generated for a function, i.e.
7780  before any optimizations are done.
7781  The basic blocks
7782 \begin_inset LatexCommand \index{Basic blocks}
7783
7784 \end_inset
7785
7786  at this stage ordered in the depth first number, so they may not be in
7787  sequence of execution.
7788 \layout List
7789 \labelwidthstring 00.00.0000
7790
7791
7792 \series bold
7793 -
7794 \begin_inset ERT
7795 status Collapsed
7796
7797 \layout Standard
7798
7799 \backslash
7800 /
7801 \end_inset
7802
7803 -dumpgcse
7804 \begin_inset LatexCommand \index{-\/-dumpgcse}
7805
7806 \end_inset
7807
7808
7809 \series default
7810  Will create a dump of iCode's, after global subexpression elimination
7811 \begin_inset LatexCommand \index{Global subexpression elimination}
7812
7813 \end_inset
7814
7815 , into a file named
7816 \emph on
7817 <source filename>.dumpgcse.
7818 \layout List
7819 \labelwidthstring 00.00.0000
7820
7821
7822 \series bold
7823 -
7824 \begin_inset ERT
7825 status Collapsed
7826
7827 \layout Standard
7828
7829 \backslash
7830 /
7831 \end_inset
7832
7833 -dumpdeadcode
7834 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
7835
7836 \end_inset
7837
7838
7839 \series default
7840  Will create a dump of iCode's, after deadcode elimination
7841 \begin_inset LatexCommand \index{Dead-code elimination}
7842
7843 \end_inset
7844
7845 , into a file named
7846 \emph on
7847 <source filename>.dumpdeadcode.
7848 \layout List
7849 \labelwidthstring 00.00.0000
7850
7851
7852 \series bold
7853 -
7854 \begin_inset ERT
7855 status Collapsed
7856
7857 \layout Standard
7858
7859 \backslash
7860 /
7861 \end_inset
7862
7863 -dumploop
7864 \begin_inset LatexCommand \index{-\/-dumploop}
7865
7866 \end_inset
7867
7868
7869 \series default
7870 \size large
7871
7872 \size default
7873 Will create a dump of iCode's, after loop optimizations
7874 \begin_inset LatexCommand \index{Loop optimization}
7875
7876 \end_inset
7877
7878 , into a file named
7879 \emph on
7880 <source filename>.dumploop.
7881 \layout List
7882 \labelwidthstring 00.00.0000
7883
7884
7885 \series bold
7886 -
7887 \begin_inset ERT
7888 status Collapsed
7889
7890 \layout Standard
7891
7892 \backslash
7893 /
7894 \end_inset
7895
7896 -dumprange
7897 \begin_inset LatexCommand \index{-\/-dumprange}
7898
7899 \end_inset
7900
7901
7902 \series default
7903 \size large
7904
7905 \size default
7906 Will create a dump of iCode's, after live range analysis
7907 \begin_inset LatexCommand \index{Live range analysis}
7908
7909 \end_inset
7910
7911 , into a file named
7912 \emph on
7913 <source filename>.dumprange.
7914 \layout List
7915 \labelwidthstring 00.00.0000
7916
7917
7918 \series bold
7919 -
7920 \begin_inset ERT
7921 status Collapsed
7922
7923 \layout Standard
7924
7925 \backslash
7926 /
7927 \end_inset
7928
7929 -dumlrange
7930 \begin_inset LatexCommand \index{-\/-dumlrange}
7931
7932 \end_inset
7933
7934
7935 \series default
7936  Will dump the life ranges
7937 \begin_inset LatexCommand \index{Live range analysis}
7938
7939 \end_inset
7940
7941  for all symbols.
7942 \layout List
7943 \labelwidthstring 00.00.0000
7944
7945
7946 \series bold
7947 -
7948 \begin_inset ERT
7949 status Collapsed
7950
7951 \layout Standard
7952
7953 \backslash
7954 /
7955 \end_inset
7956
7957 -dumpregassign
7958 \begin_inset LatexCommand \index{-\/-dumpregassign}
7959
7960 \end_inset
7961
7962
7963 \bar under
7964
7965 \series default
7966 \bar default
7967 Will create a dump of iCode's, after register assignment
7968 \begin_inset LatexCommand \index{Register assignment}
7969
7970 \end_inset
7971
7972 , into a file named
7973 \emph on
7974 <source filename>.dumprassgn.
7975 \layout List
7976 \labelwidthstring 00.00.0000
7977
7978
7979 \series bold
7980 -
7981 \begin_inset ERT
7982 status Collapsed
7983
7984 \layout Standard
7985
7986 \backslash
7987 /
7988 \end_inset
7989
7990 -dumplrange
7991 \begin_inset LatexCommand \index{-\/-dumplrange}
7992
7993 \end_inset
7994
7995
7996 \series default
7997  Will create a dump of the live ranges of iTemp's
7998 \layout List
7999 \labelwidthstring 00.00.0000
8000
8001
8002 \series bold
8003 -
8004 \begin_inset ERT
8005 status Collapsed
8006
8007 \layout Standard
8008
8009 \backslash
8010 /
8011 \end_inset
8012
8013 -dumpall
8014 \begin_inset LatexCommand \index{-\/-dumpall}
8015
8016 \end_inset
8017
8018
8019 \size large
8020 \bar under
8021
8022 \series default
8023 \size default
8024 \bar default
8025 Will cause all the above mentioned dumps to be created.
8026 \layout Subsection
8027
8028 Redirecting output on Windows Shells
8029 \layout Standard
8030
8031 By default SDCC writes it's error messages to
8032 \begin_inset Quotes sld
8033 \end_inset
8034
8035 standard error
8036 \begin_inset Quotes srd
8037 \end_inset
8038
8039 .
8040  To force all messages to
8041 \begin_inset Quotes sld
8042 \end_inset
8043
8044 standard output
8045 \begin_inset Quotes srd
8046 \end_inset
8047
8048  use
8049 \series bold
8050 -
8051 \series default
8052 \emph on
8053
8054 \begin_inset ERT
8055 status Collapsed
8056
8057 \layout Standard
8058
8059 \backslash
8060 /
8061 \end_inset
8062
8063
8064 \series bold
8065 \emph default
8066 -
8067 \series default
8068 use-stdout
8069 \begin_inset LatexCommand \index{-\/-use-stdout}
8070
8071 \end_inset
8072
8073 .
8074  Additionally, if you happen to have visual studio installed in your windows
8075  machine, you can use it to compile your sources using a custom build and
8076  the SDCC -
8077 \emph on
8078
8079 \begin_inset ERT
8080 status Collapsed
8081
8082 \layout Standard
8083
8084 \backslash
8085 /
8086 \end_inset
8087
8088
8089 \emph default
8090 -vc
8091 \begin_inset LatexCommand \index{-\/-vc}
8092
8093 \end_inset
8094
8095  option.
8096  Something like this should work:
8097 \newline
8098
8099 \newline
8100
8101 \series bold
8102 c:
8103 \backslash
8104 sdcc
8105 \backslash
8106 bin
8107 \backslash
8108 sdcc.exe -
8109 \series default
8110 \emph on
8111
8112 \begin_inset ERT
8113 status Collapsed
8114
8115 \layout Standard
8116
8117 \backslash
8118 /
8119 \end_inset
8120
8121
8122 \series bold
8123 \emph default
8124 -vc -
8125 \series default
8126 \emph on
8127
8128 \begin_inset ERT
8129 status Collapsed
8130
8131 \layout Standard
8132
8133 \backslash
8134 /
8135 \end_inset
8136
8137
8138 \series bold
8139 \emph default
8140 -model-large -c $(InputPath)
8141 \layout Section
8142
8143 Environment variables
8144 \begin_inset LatexCommand \index{Environment variables}
8145
8146 \end_inset
8147
8148
8149 \layout Standard
8150
8151 SDCC recognizes the following environment variables:
8152 \layout List
8153 \labelwidthstring 00.00.0000
8154
8155
8156 \series bold
8157 SDCC_LEAVE_SIGNALS
8158 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
8159
8160 \end_inset
8161
8162
8163 \series default
8164  SDCC installs a signal handler
8165 \begin_inset LatexCommand \index{signal handler}
8166
8167 \end_inset
8168
8169  to be able to delete temporary files after an user break (^C) or an exception.
8170  If this environment variable is set, SDCC won't install the signal handler
8171  in order to be able to debug SDCC.
8172 \layout List
8173 \labelwidthstring 00.00.0000
8174
8175
8176 \series bold
8177 TMP,\SpecialChar ~
8178 TEMP,\SpecialChar ~
8179 TMPDIR
8180 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
8181
8182 \end_inset
8183
8184
8185 \series default
8186  Path, where temporary files will be created.
8187  The order of the variables is the search order.
8188  In a standard *nix environment these variables are not set, and there's
8189  no need to set them.
8190  On Windows it's recommended to set one of them.
8191 \layout List
8192 \labelwidthstring 00.00.0000
8193
8194
8195 \series bold
8196 SDCC_HOME
8197 \begin_inset LatexCommand \index{SDCC\_HOME}
8198
8199 \end_inset
8200
8201
8202 \series default
8203  Path, see section
8204 \begin_inset LatexCommand \ref{sub:Install-paths}
8205
8206 \end_inset
8207
8208 \SpecialChar ~
8209
8210 \begin_inset Quotes sld
8211 \end_inset
8212
8213  Install Paths
8214 \begin_inset Quotes srd
8215 \end_inset
8216
8217 .
8218 \layout List
8219 \labelwidthstring 00.00.0000
8220
8221
8222 \series bold
8223 SDCC_INCLUDE
8224 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8225
8226 \end_inset
8227
8228
8229 \series default
8230  Path, see section
8231 \begin_inset LatexCommand \ref{sub:Search-Paths}
8232
8233 \end_inset
8234
8235 \SpecialChar ~
8236
8237 \begin_inset Quotes sld
8238 \end_inset
8239
8240 Search Paths
8241 \begin_inset Quotes srd
8242 \end_inset
8243
8244 .
8245 \layout List
8246 \labelwidthstring 00.00.0000
8247
8248
8249 \series bold
8250 SDCC_LIB
8251 \begin_inset LatexCommand \index{SDCC\_LIB}
8252
8253 \end_inset
8254
8255
8256 \series default
8257  Path, see section
8258 \begin_inset LatexCommand \ref{sub:Search-Paths}
8259
8260 \end_inset
8261
8262 \SpecialChar ~
8263
8264 \begin_inset Quotes sld
8265 \end_inset
8266
8267 Search Paths
8268 \begin_inset Quotes srd
8269 \end_inset
8270
8271 ..
8272 \layout Standard
8273
8274 There are some more environment variables recognized by SDCC, but these
8275  are solely used for debugging purposes.
8276  They can change or disappear very quickly, and will never be documented.
8277 \layout Section
8278
8279 Storage Class Language Extensions
8280 \layout Subsection
8281
8282 MCS51/DS390 Storage Class
8283 \begin_inset LatexCommand \index{Storage class}
8284
8285 \end_inset
8286
8287  Language Extensions
8288 \layout Standard
8289
8290 In addition to the ANSI storage classes SDCC allows the following MCS51
8291  specific storage classes:
8292 \layout Subsubsection
8293
8294 data
8295 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8296
8297 \end_inset
8298
8299  / near
8300 \begin_inset LatexCommand \index{near (storage class)}
8301
8302 \end_inset
8303
8304
8305 \layout Standard
8306
8307 This is the
8308 \series bold
8309 default
8310 \series default
8311  storage class for the Small Memory model (
8312 \emph on
8313 data
8314 \emph default
8315  and
8316 \emph on
8317 near
8318 \emph default
8319  can be used synonymously).
8320  Variables declared with this storage class will be allocated in the directly
8321  addressable portion of the internal RAM of a 8051, e.g.:
8322 \layout Verse
8323
8324
8325 \family typewriter
8326 data unsigned char test_data;
8327 \layout Standard
8328
8329 Writing 0x01 to this variable generates the assembly code:
8330 \layout Verse
8331
8332
8333 \family typewriter
8334 75*00 01\SpecialChar ~
8335 \SpecialChar ~
8336 \SpecialChar ~
8337 mov\SpecialChar ~
8338 \SpecialChar ~
8339 _test_data,#0x01
8340 \layout Subsubsection
8341
8342 xdata
8343 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8344
8345 \end_inset
8346
8347  / far
8348 \begin_inset LatexCommand \index{far (storage class)}
8349
8350 \end_inset
8351
8352
8353 \layout Standard
8354
8355 Variables declared with this storage class will be placed in the external
8356  RAM.
8357  This is the
8358 \series bold
8359 default
8360 \series default
8361  storage class for the Large Memory model, e.g.:
8362 \layout Verse
8363
8364
8365 \family typewriter
8366 xdata unsigned char test_xdata;
8367 \layout Standard
8368
8369 Writing 0x01 to this variable generates the assembly code:
8370 \layout Verse
8371
8372
8373 \family typewriter
8374 90s00r00\SpecialChar ~
8375 \SpecialChar ~
8376 \SpecialChar ~
8377 mov\SpecialChar ~
8378 \SpecialChar ~
8379 dptr,#_test_xdata
8380 \newline
8381 74\SpecialChar ~
8382 01\SpecialChar ~
8383 \SpecialChar ~
8384 \SpecialChar ~
8385 \SpecialChar ~
8386 \SpecialChar ~
8387 \SpecialChar ~
8388 mov\SpecialChar ~
8389 \SpecialChar ~
8390 a,#0x01
8391 \newline
8392 F0\SpecialChar ~
8393 \SpecialChar ~
8394 \SpecialChar ~
8395 \SpecialChar ~
8396 \SpecialChar ~
8397 \SpecialChar ~
8398 \SpecialChar ~
8399 \SpecialChar ~
8400 \SpecialChar ~
8401 movx\SpecialChar ~
8402 @dptr,a
8403 \layout Subsubsection
8404
8405 idata
8406 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8407
8408 \end_inset
8409
8410
8411 \layout Standard
8412
8413 Variables declared with this storage class will be allocated into the indirectly
8414  addressable portion of the internal ram of a 8051, e.g.:
8415 \layout Verse
8416
8417
8418 \family typewriter
8419 idata unsigned char test_idata;
8420 \layout Standard
8421
8422 Writing 0x01 to this variable generates the assembly code:
8423 \layout Verse
8424
8425
8426 \family typewriter
8427 78r00\SpecialChar ~
8428 \SpecialChar ~
8429 \SpecialChar ~
8430 \SpecialChar ~
8431 \SpecialChar ~
8432 \SpecialChar ~
8433 \SpecialChar ~
8434 mov\SpecialChar ~
8435 \SpecialChar ~
8436 r0,#_test_idata
8437 \newline
8438 76\SpecialChar ~
8439 01\SpecialChar ~
8440 \SpecialChar ~
8441 \SpecialChar ~
8442 \SpecialChar ~
8443 \SpecialChar ~
8444 \SpecialChar ~
8445 \SpecialChar ~
8446 mov\SpecialChar ~
8447 \SpecialChar ~
8448 @r0,#0x01
8449 \layout Standard
8450
8451 Please note, the first 128 byte of idata physically access the same RAM
8452  as the data memory.
8453  The original 8051 had 128 byte idata memory, nowadays most devices have
8454  256 byte idata memory.
8455  The stack
8456 \begin_inset LatexCommand \index{stack}
8457
8458 \end_inset
8459
8460  is located in idata memory.
8461 \layout Subsubsection
8462
8463 pdata
8464 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8465
8466 \end_inset
8467
8468
8469 \layout Standard
8470
8471 Paged xdata access is just as straightforward as using the other addressing
8472  modes of a 8051.
8473  It is typically located at the start of xdata and has a maximum size of
8474  256 bytes.
8475  The following example writes 0x01 to the address pointed to.
8476  Please note, pdata access physically accesses xdata memory.
8477  The high byte of the address is determined by port P2
8478 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8479
8480 \end_inset
8481
8482 (or in case of some 8051 variants by a separate Special Function Register,
8483  see section
8484 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8485
8486 \end_inset
8487
8488 ).
8489 \layout Verse
8490
8491
8492 \family typewriter
8493 pdata unsigned char *test_pdata_ptr;
8494 \newline
8495
8496 \newline
8497 void main()
8498 \newline
8499 {
8500 \newline
8501 \SpecialChar ~
8502 \SpecialChar ~
8503 \SpecialChar ~
8504 \SpecialChar ~
8505 test_pdata_ptr = (pdata *)0xfe;
8506 \newline
8507 \SpecialChar ~
8508 \SpecialChar ~
8509 \SpecialChar ~
8510 \SpecialChar ~
8511 *test_pdata_ptr = 1;
8512 \newline
8513 }
8514 \layout Standard
8515
8516 Generates the assembly code:
8517 \layout Verse
8518
8519
8520 \family typewriter
8521 75*01 FE\SpecialChar ~
8522 \SpecialChar ~
8523 \SpecialChar ~
8524 mov\SpecialChar ~
8525  _test_pdata_ptr,#0xFE
8526 \newline
8527 78 FE\SpecialChar ~
8528 \SpecialChar ~
8529 \SpecialChar ~
8530 \SpecialChar ~
8531 \SpecialChar ~
8532 \SpecialChar ~
8533 mov\SpecialChar ~
8534  r0,#0xFE
8535 \newline
8536 74 01\SpecialChar ~
8537 \SpecialChar ~
8538 \SpecialChar ~
8539 \SpecialChar ~
8540 \SpecialChar ~
8541 \SpecialChar ~
8542 mov\SpecialChar ~
8543  a,#0x01
8544 \newline
8545 F2\SpecialChar ~
8546 \SpecialChar ~
8547 \SpecialChar ~
8548 \SpecialChar ~
8549 \SpecialChar ~
8550 \SpecialChar ~
8551 \SpecialChar ~
8552 \SpecialChar ~
8553 \SpecialChar ~
8554 movx @r0,a
8555 \layout Standard
8556
8557 If the -
8558 \begin_inset ERT
8559 status Collapsed
8560
8561 \layout Standard
8562
8563 \backslash
8564 /
8565 \end_inset
8566
8567 -xstack
8568 \begin_inset LatexCommand \index{-\/-xstack}
8569
8570 \end_inset
8571
8572  option is used the pdata memory area is followed by the xstack memory area
8573  and the sum of their sizes is limited to 256 bytes.
8574 \layout Subsubsection
8575
8576 code
8577 \begin_inset LatexCommand \index{code}
8578
8579 \end_inset
8580
8581
8582 \layout Standard
8583
8584 'Variables' declared with this storage class will be placed in the code
8585  memory:
8586 \layout Verse
8587
8588
8589 \family typewriter
8590 code unsigned char test_code;
8591 \layout Standard
8592
8593 Read access to this variable generates the assembly code:
8594 \layout Verse
8595
8596
8597 \family typewriter
8598 90s00r6F\SpecialChar ~
8599 \SpecialChar ~
8600 \SpecialChar ~
8601 mov dptr,#_test_code
8602 \newline
8603 E4\SpecialChar ~
8604 \SpecialChar ~
8605 \SpecialChar ~
8606 \SpecialChar ~
8607 \SpecialChar ~
8608 \SpecialChar ~
8609 \SpecialChar ~
8610 \SpecialChar ~
8611 \SpecialChar ~
8612 clr a
8613 \newline
8614 93\SpecialChar ~
8615 \SpecialChar ~
8616 \SpecialChar ~
8617 \SpecialChar ~
8618 \SpecialChar ~
8619 \SpecialChar ~
8620 \SpecialChar ~
8621 \SpecialChar ~
8622 \SpecialChar ~
8623 movc a,@a+dptr
8624 \layout Standard
8625
8626
8627 \family typewriter
8628 char
8629 \family default
8630  indexed arrays of characters in code memory can be accessed efficiently:
8631 \layout Verse
8632
8633
8634 \family typewriter
8635 code char test_array[] = {'c','h','e','a','p'};
8636 \layout Standard
8637
8638 Read access to this array using an 8-bit unsigned index generates the assembly
8639  code:
8640 \layout Verse
8641
8642
8643 \family typewriter
8644 E5*00\SpecialChar ~
8645 \SpecialChar ~
8646 \SpecialChar ~
8647 \SpecialChar ~
8648 \SpecialChar ~
8649 \SpecialChar ~
8650 mov a,_index
8651 \layout Verse
8652
8653
8654 \family typewriter
8655 90s00r41\SpecialChar ~
8656 \SpecialChar ~
8657 \SpecialChar ~
8658 mov dptr,#_test_array
8659 \layout Verse
8660
8661
8662 \family typewriter
8663 93\SpecialChar ~
8664 \SpecialChar ~
8665 \SpecialChar ~
8666 \SpecialChar ~
8667 \SpecialChar ~
8668 \SpecialChar ~
8669 \SpecialChar ~
8670 \SpecialChar ~
8671 \SpecialChar ~
8672 movc a,@a+dptr
8673 \layout Subsubsection
8674
8675 bit
8676 \begin_inset LatexCommand \index{bit}
8677
8678 \end_inset
8679
8680
8681 \layout Standard
8682
8683 This is a data-type and a storage class specifier.
8684  When a variable is declared as a bit, it is allocated into the bit addressable
8685  memory of 8051, e.g.:
8686 \layout Verse
8687
8688
8689 \family typewriter
8690 bit test_bit;
8691 \layout Standard
8692
8693 Writing 1 to this variable generates the assembly code:
8694 \layout Verse
8695
8696
8697 \family typewriter
8698 D2*00\SpecialChar ~
8699 \SpecialChar ~
8700 \SpecialChar ~
8701 \SpecialChar ~
8702 \SpecialChar ~
8703 \SpecialChar ~
8704 \SpecialChar ~
8705 setb\SpecialChar ~
8706 _test_bit
8707 \layout Standard
8708
8709 The bit addressable memory consists of 128 bits which are located from 0x20
8710  to 0x2f in data memory.
8711
8712 \newline
8713 Apart from this 8051 specific storage class most architectures support ANSI-C
8714  bitfields
8715 \begin_inset LatexCommand \index{bitfields}
8716
8717 \end_inset
8718
8719
8720 \begin_inset Foot
8721 collapsed false
8722
8723 \layout Standard
8724
8725 Not really meant as examples, but nevertheless showing what bitfields are
8726  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8727 \end_inset
8728
8729 .
8730  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8731  signed modifier are implemented as unsigned.
8732 \layout Subsubsection
8733
8734 sfr
8735 \begin_inset LatexCommand \index{sfr}
8736
8737 \end_inset
8738
8739  / sbit
8740 \begin_inset LatexCommand \index{sbit}
8741
8742 \end_inset
8743
8744
8745 \layout Standard
8746
8747 Like the bit keyword,
8748 \emph on
8749 sfr / sbit
8750 \emph default
8751 signifies both a data-type and storage class, they are used to describe
8752  the
8753 \emph on
8754 s
8755 \emph default
8756 pecial
8757 \emph on
8758 f
8759 \emph default
8760 unction
8761 \emph on
8762 r
8763 \emph default
8764 egisters and
8765 \emph on
8766 s
8767 \emph default
8768 pecial
8769 \emph on
8770 bit
8771 \emph default
8772  variables of a 8051, eg:
8773 \layout Verse
8774
8775
8776 \family typewriter
8777 sfr at
8778 \begin_inset LatexCommand \index{at}
8779
8780 \end_inset
8781
8782  0x80 P0;\SpecialChar ~
8783  /* special function register P0 at location 0x80 */
8784 \newline
8785 sbit at 0xd7 CY; /* CY (Carry Flag
8786 \begin_inset LatexCommand \index{Flags}
8787
8788 \end_inset
8789
8790
8791 \begin_inset LatexCommand \index{Carry flag}
8792
8793 \end_inset
8794
8795 ) */
8796 \layout Standard
8797
8798 Special function registers which are located on an address dividable by
8799  8 are bit-addressable, an
8800 \emph on
8801  sbit
8802 \emph default
8803  addresses a specific bit within these sfr.
8804 \layout Subsubsection
8805
8806 Pointers
8807 \begin_inset LatexCommand \index{Pointer}
8808
8809 \end_inset
8810
8811  to MCS51/DS390 specific memory spaces
8812 \layout Standard
8813
8814 SDCC allows (via language extensions) pointers to explicitly point to any
8815  of the memory spaces
8816 \begin_inset LatexCommand \index{Memory model}
8817
8818 \end_inset
8819
8820  of the 8051.
8821  In addition to the explicit pointers, the compiler uses (by default) generic
8822  pointers which can be used to point to any of the memory spaces.
8823 \newline
8824
8825 \newline
8826 Pointer declaration examples:
8827 \layout Verse
8828
8829
8830 \family typewriter
8831 /* pointer physically in internal ram pointing to object in external ram
8832  */
8833 \newline
8834 xdata unsigned char * data p;
8835 \newline
8836
8837 \newline
8838 /* pointer physically in external ram pointing to object in internal ram
8839  */
8840 \newline
8841 data unsigned char * xdata p;
8842 \newline
8843
8844 \newline
8845 /* pointer physically in code rom pointing to data in xdata space */
8846 \newline
8847 xdata unsigned char * code p;
8848 \newline
8849
8850 \newline
8851 /* pointer physically in code space pointing to data in code space */
8852 \newline
8853 code unsigned char * code p;
8854 \newline
8855
8856 \newline
8857 /* the following is a generic pointer physically located in xdata space
8858  */
8859 \newline
8860 char * xdata p;
8861 \layout Standard
8862
8863 Well you get the idea.
8864
8865 \newline
8866
8867 \newline
8868 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
8869 \emph on
8870 generic
8871 \emph default
8872  pointers.
8873
8874 \size small
8875
8876 \newline
8877
8878 \newline
8879
8880 \size default
8881 The highest order byte of the
8882 \emph on
8883 generic
8884 \emph default
8885  pointers contains the data space information.
8886  Assembler support routines are called whenever data is stored or retrieved
8887  using
8888 \emph on
8889 generic
8890 \emph default
8891  pointers.
8892  These are useful for developing reusable library
8893 \begin_inset LatexCommand \index{Libraries}
8894
8895 \end_inset
8896
8897  routines.
8898  Explicitly specifying the pointer type will generate the most efficient
8899  code.
8900 \layout Subsubsection
8901
8902 Notes on MCS51 memory
8903 \begin_inset LatexCommand \index{MCS51 memory}
8904
8905 \end_inset
8906
8907  layout
8908 \layout Standard
8909
8910 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
8911  RAM memory which is structured as follows:
8912 \newline
8913
8914 \newline
8915 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
8916
8917 \newline
8918 - Bytes 20-2F - 16 bytes to hold 128 bit
8919 \begin_inset LatexCommand \index{bit}
8920
8921 \end_inset
8922
8923  variables and,
8924 \newline
8925 - Bytes 30-7F - 80 bytes for general purpose use.
8926 \newline
8927
8928 \layout Standard
8929
8930 Additionally some members of the MCS51 family may have up to 128 bytes of
8931  additional, indirectly addressable, internal RAM memory (
8932 \emph on
8933 idata
8934 \emph default
8935
8936 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8937
8938 \end_inset
8939
8940 ).
8941  Furthermore, some chips may have some built in external memory (
8942 \emph on
8943 xdata
8944 \emph default
8945
8946 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8947
8948 \end_inset
8949
8950 ) which should not be confused with the internal, directly addressable RAM
8951  memory (
8952 \emph on
8953 data
8954 \emph default
8955
8956 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8957
8958 \end_inset
8959
8960 ).
8961  Sometimes this built in
8962 \emph on
8963 xdata
8964 \emph default
8965  memory has to be activated before using it (you can probably find this
8966  information on the datasheet of the microcontroller your are using, see
8967  also section
8968 \begin_inset LatexCommand \ref{sub:Startup-Code}
8969
8970 \end_inset
8971
8972 \SpecialChar ~
8973 Startup-Code).
8974 \layout Standard
8975
8976 Normally SDCC will only use the first bank
8977 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
8978
8979 \end_inset
8980
8981  of registers (register bank 0), but it is possible to specify that other
8982  banks of registers should be used in interrupt
8983 \begin_inset LatexCommand \index{interrupt}
8984
8985 \end_inset
8986
8987  routines.
8988  By default, the compiler will place the stack after the last byte of allocated
8989  memory for variables.
8990  For example, if the first 2 banks of registers are used, and only four
8991  bytes are used for
8992 \emph on
8993 data
8994 \emph default
8995  variables, it will position the base of the internal stack at address 20
8996  (0x14).
8997  This implies that as the stack
8998 \begin_inset LatexCommand \index{stack}
8999
9000 \end_inset
9001
9002  grows, it will use up the remaining register banks, and the 16 bytes used
9003  by the 128 bit variables, and 80 bytes for general purpose use.
9004  If any bit variables are used, the data variables will be placed in unused
9005  register banks and after the byte holding the last bit variable.
9006  For example, if register banks 0 and 1 are used, and there are 9 bit variables
9007  (two bytes used),
9008 \emph on
9009 data
9010 \emph default
9011  variables will be placed starting from address 0x10 to 0x20 and continue
9012  at address 0x22.
9013  You can also use -
9014 \begin_inset ERT
9015 status Collapsed
9016
9017 \layout Standard
9018
9019 \backslash
9020 /
9021 \end_inset
9022
9023 -data-loc
9024 \begin_inset LatexCommand \index{-\/-data-loc<Value>}
9025
9026 \end_inset
9027
9028  to specify the start address of the
9029 \emph on
9030 data
9031 \emph default
9032  and -
9033 \begin_inset ERT
9034 status Collapsed
9035
9036 \layout Standard
9037
9038 \backslash
9039 /
9040 \end_inset
9041
9042 -iram-size to specify the size of the total internal RAM (
9043 \emph on
9044 data
9045 \emph default
9046 +
9047 \emph on
9048 idata
9049 \emph default
9050 ).
9051
9052 \layout Standard
9053
9054 By default the 8051 linker will place the stack after the last byte of (i)data
9055  variables.
9056  Option -
9057 \begin_inset ERT
9058 status Collapsed
9059
9060 \layout Standard
9061
9062 \backslash
9063 /
9064 \end_inset
9065
9066 -stack-loc
9067 \begin_inset LatexCommand \index{-\/-stack-loc<Value>}
9068
9069 \end_inset
9070
9071  allows you to specify the start of the stack, i.e.
9072  you could start it after any data in the general purpose area.
9073  If your microcontroller has additional indirectly addressable internal
9074  RAM (
9075 \emph on
9076 idata
9077 \emph default
9078 ) you can place the stack on it.
9079  You may also need to use -
9080 \begin_inset ERT
9081 status Collapsed
9082
9083 \layout Standard
9084
9085 \backslash
9086 /
9087 \end_inset
9088
9089 -xdata-loc
9090 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
9091
9092 \end_inset
9093
9094  to set the start address of the external RAM (
9095 \emph on
9096 xdata
9097 \emph default
9098 ) and -
9099 \begin_inset ERT
9100 status Collapsed
9101
9102 \layout Standard
9103
9104 \backslash
9105 /
9106 \end_inset
9107
9108 -xram-size
9109 \begin_inset LatexCommand \index{-\/-data-loc}
9110
9111 \end_inset
9112
9113  to specify its size.
9114  Same goes for the code memory, using -
9115 \begin_inset ERT
9116 status Collapsed
9117
9118 \layout Standard
9119
9120 \backslash
9121 /
9122 \end_inset
9123
9124 -code-loc
9125 \begin_inset LatexCommand \index{-\/-data-loc}
9126
9127 \end_inset
9128
9129  and -
9130 \begin_inset ERT
9131 status Collapsed
9132
9133 \layout Standard
9134
9135 \backslash
9136 /
9137 \end_inset
9138
9139 -code-size
9140 \begin_inset LatexCommand \index{-\/-data-loc}
9141
9142 \end_inset
9143
9144 .
9145  If in doubt, don't specify any options and see if the resulting memory
9146  layout is appropriate, then you can adjust it.
9147 \layout Standard
9148
9149 The linker generates two files with memory allocation information.
9150  The first, with extension .map
9151 \begin_inset LatexCommand \index{<file>.map}
9152
9153 \end_inset
9154
9155  shows all the variables and segments.
9156  The second with extension .mem
9157 \begin_inset LatexCommand \index{<file>.mem}
9158
9159 \end_inset
9160
9161  shows the final memory layout.
9162  The linker will complain either if memory segments overlap, there is not
9163  enough memory, or there is not enough space for stack.
9164  If you get any linking warnings and/or errors related to stack or segments
9165  allocation, take a look at either the .map or .mem files to find out what
9166  the problem is.
9167  The .mem file may even suggest a solution to the problem.
9168 \layout Subsection
9169
9170 Z80/Z180 Storage Class
9171 \begin_inset LatexCommand \index{Storage class}
9172
9173 \end_inset
9174
9175  Language Extensions
9176 \layout Subsubsection
9177
9178 sfr
9179 \begin_inset LatexCommand \index{sfr}
9180
9181 \end_inset
9182
9183  (in/out to 8-bit addresses)
9184 \layout Standard
9185
9186 The Z80
9187 \begin_inset LatexCommand \index{Z80}
9188
9189 \end_inset
9190
9191  family has separate address spaces for memory and
9192 \emph on
9193 i
9194 \emph default
9195 nput/
9196 \emph on
9197 o
9198 \emph default
9199 utput memory.
9200  I/O memory
9201 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9202
9203 \end_inset
9204
9205  is accessed with special instructions, e.g.:
9206 \layout Verse
9207
9208
9209 \family typewriter
9210 sfr at 0x78 IoPort;\SpecialChar ~
9211 \SpecialChar ~
9212 /* define a var in I/O space at 78h called IoPort */
9213
9214 \layout Standard
9215
9216 Writing 0x01 to this variable generates the assembly code:
9217 \layout Verse
9218
9219
9220 \family typewriter
9221 3E 01\SpecialChar ~
9222 \SpecialChar ~
9223 \SpecialChar ~
9224 \SpecialChar ~
9225 \SpecialChar ~
9226 \SpecialChar ~
9227 ld a,#0x01
9228 \newline
9229 D3 78\SpecialChar ~
9230 \SpecialChar ~
9231 \SpecialChar ~
9232 \SpecialChar ~
9233 \SpecialChar ~
9234 \SpecialChar ~
9235 out (_IoPort),a
9236 \layout Subsubsection
9237
9238 banked sfr
9239 \begin_inset LatexCommand \index{sfr}
9240
9241 \end_inset
9242
9243  (in/out to 16-bit addresses)
9244 \layout Standard
9245
9246 The keyword
9247 \emph on
9248 banked
9249 \emph default
9250  is used to support 16 bit addresses in I/O memory e.g.:
9251 \layout Verse
9252
9253
9254 \family typewriter
9255 sfr banked at
9256 \begin_inset LatexCommand \index{at}
9257
9258 \end_inset
9259
9260  0x123 IoPort;
9261 \layout Standard
9262
9263 Writing 0x01 to this variable generates the assembly code:
9264 \layout Verse
9265
9266
9267 \family typewriter
9268 01 23 01\SpecialChar ~
9269 \SpecialChar ~
9270 \SpecialChar ~
9271 ld bc,#_IoPort
9272 \newline
9273 3E 01\SpecialChar ~
9274 \SpecialChar ~
9275 \SpecialChar ~
9276 \SpecialChar ~
9277 \SpecialChar ~
9278 \SpecialChar ~
9279 ld a,#0x01
9280 \newline
9281 ED 79\SpecialChar ~
9282 \SpecialChar ~
9283 \SpecialChar ~
9284 \SpecialChar ~
9285 \SpecialChar ~
9286 \SpecialChar ~
9287 out (c),a
9288 \layout Subsubsection
9289
9290 sfr
9291 \begin_inset LatexCommand \index{sfr}
9292
9293 \end_inset
9294
9295  (in0/out0 to 8 bit addresses on Z180
9296 \begin_inset LatexCommand \index{Z180}
9297
9298 \end_inset
9299
9300 /HD64180
9301 \begin_inset LatexCommand \index{HD64180}
9302
9303 \end_inset
9304
9305 )
9306 \layout Standard
9307
9308 The compiler option -
9309 \begin_inset ERT
9310 status Collapsed
9311
9312 \layout Standard
9313
9314 \backslash
9315 /
9316 \end_inset
9317
9318 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9319 portmode
9320 \begin_inset LatexCommand \index{\#pragma portmode}
9321
9322 \end_inset
9323
9324 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9325 ns
9326 \family typewriter
9327 in0/out0
9328 \family default
9329  instead of
9330 \family typewriter
9331 in/out
9332 \family default
9333 .
9334  If you include the file z180.h this will be set automatically.
9335 \layout Subsection
9336
9337 HC08 Storage Class
9338 \begin_inset LatexCommand \index{Storage class}
9339
9340 \end_inset
9341
9342  Language Extensions
9343 \layout Subsubsection
9344
9345 data
9346 \begin_inset LatexCommand \index{data (hc08 storage class)}
9347
9348 \end_inset
9349
9350
9351 \layout Standard
9352
9353 The data storage class declares a variable that resides in the first 256
9354  bytes of memory (the direct page).
9355  The HC08 is most efficient at accessing variables (especially pointers)
9356  stored here.
9357 \layout Subsubsection
9358
9359 xdata
9360 \begin_inset LatexCommand \index{xdata (hc08 storage class)}
9361
9362 \end_inset
9363
9364
9365 \layout Standard
9366
9367 The xdata storage class declares a variable that can reside anywhere in
9368  memory.
9369  This is the default if no storage class is specified.
9370
9371 \layout Section
9372
9373 Absolute Addressing
9374 \begin_inset LatexCommand \index{Absolute addressing}
9375
9376 \end_inset
9377
9378
9379 \layout Standard
9380
9381 Data items can be assigned an absolute address with the
9382 \emph on
9383 at
9384 \begin_inset LatexCommand \index{at}
9385
9386 \end_inset
9387
9388  <address>
9389 \emph default
9390  keyword, in addition to a storage class, e.g.:
9391 \layout Verse
9392
9393
9394 \family typewriter
9395 xdata
9396 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9397
9398 \end_inset
9399
9400  at
9401 \begin_inset LatexCommand \index{at}
9402
9403 \end_inset
9404
9405  0x7ffe unsigned int chksum;
9406 \layout Standard
9407
9408 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9409  of the external ram.
9410  The compiler does
9411 \emph on
9412 not
9413 \emph default
9414  reserve any space for variables declared in this way (they are implemented
9415  with an equate in the assembler).
9416  Thus it is left to the programmer to make sure there are no overlaps with
9417  other variables that are declared without the absolute address.
9418  The assembler listing file (.lst
9419 \begin_inset LatexCommand \index{<file>.lst}
9420
9421 \end_inset
9422
9423 ) and the linker output files (.rst
9424 \begin_inset LatexCommand \index{<file>.rst}
9425
9426 \end_inset
9427
9428 ) and (.map
9429 \begin_inset LatexCommand \index{<file>.map}
9430
9431 \end_inset
9432
9433 ) are good places to look for such overlaps.
9434  Variables with an absolute address are
9435 \emph on
9436 not
9437 \emph default
9438  initialized
9439 \begin_inset LatexCommand \index{Variable initialization}
9440
9441 \end_inset
9442
9443 .
9444 \layout Standard
9445
9446 In case of memory mapped I/O devices the keyword
9447 \emph on
9448 volatile
9449 \emph default
9450  has to be used to tell the compiler that accesses might not be removed:
9451 \layout Verse
9452
9453
9454 \family typewriter
9455 volatile
9456 \begin_inset LatexCommand \index{volatile}
9457
9458 \end_inset
9459
9460  xdata
9461 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9462
9463 \end_inset
9464
9465  at
9466 \begin_inset LatexCommand \index{at}
9467
9468 \end_inset
9469
9470  0x8000 unsigned char PORTA_8255;
9471 \layout Standard
9472
9473 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9474 r) array
9475 \family typewriter
9476 \size footnotesize
9477
9478 \begin_inset LatexCommand \index{Aligned array}
9479
9480 \end_inset
9481
9482
9483 \family default
9484 \size default
9485  starts at a block (256 byte) boundary
9486 \begin_inset LatexCommand \index{block boundary}
9487
9488 \end_inset
9489
9490  (section
9491 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9492
9493 \end_inset
9494
9495  has an example).
9496 \newline
9497 Absolute addresses can be specified for variables in all storage classes,
9498  e.g.:
9499 \layout Verse
9500
9501
9502 \family typewriter
9503 bit
9504 \begin_inset LatexCommand \index{bit}
9505
9506 \end_inset
9507
9508  at
9509 \begin_inset LatexCommand \index{at}
9510
9511 \end_inset
9512
9513  0x02 bvar;
9514 \layout Standard
9515
9516 The above example will allocate the variable at offset 0x02 in the bit-addressab
9517 le space.
9518  There is no real advantage to assigning absolute addresses to variables
9519  in this manner, unless you want strict control over all the variables allocated.
9520  One possible use would be to write hardware portable code.
9521  For example, if you have a routine that uses one or more of the microcontroller
9522  I/O pins, and such pins are different for two different hardwares, you
9523  can declare the I/O pins in your routine using:
9524 \layout Verse
9525
9526
9527 \family typewriter
9528 extern volatile bit MOSI;\SpecialChar ~
9529 \SpecialChar ~
9530 \SpecialChar ~
9531 \SpecialChar ~
9532 /* master out, slave in */
9533 \newline
9534 extern volatile bit MISO;\SpecialChar ~
9535 \SpecialChar ~
9536 \SpecialChar ~
9537 \SpecialChar ~
9538 /* master in, slave out */
9539 \newline
9540 extern volatile bit MCLK;\SpecialChar ~
9541 \SpecialChar ~
9542 \SpecialChar ~
9543 \SpecialChar ~
9544 /* master clock */
9545 \newline
9546
9547 \newline
9548 /* Input and Output of a byte on a 3-wire serial bus.
9549 \newline
9550 \SpecialChar ~
9551 \SpecialChar ~
9552 \SpecialChar ~
9553 If needed adapt polarity of clock, polarity of data and bit order
9554 \newline
9555 \SpecialChar ~
9556 */
9557 \newline
9558 unsigned char spi_io(unsigned char out_byte)
9559 \newline
9560 {
9561 \newline
9562 \SpecialChar ~
9563 \SpecialChar ~
9564 \SpecialChar ~
9565 \SpecialChar ~
9566 unsigned char i=8;
9567 \newline
9568 \SpecialChar ~
9569 \SpecialChar ~
9570 \SpecialChar ~
9571 \SpecialChar ~
9572 do {
9573 \newline
9574 \SpecialChar ~
9575 \SpecialChar ~
9576 \SpecialChar ~
9577 \SpecialChar ~
9578 \SpecialChar ~
9579 \SpecialChar ~
9580 \SpecialChar ~
9581 \SpecialChar ~
9582 MOSI = out_byte & 0x80;
9583 \newline
9584 \SpecialChar ~
9585 \SpecialChar ~
9586 \SpecialChar ~
9587 \SpecialChar ~
9588 \SpecialChar ~
9589 \SpecialChar ~
9590 \SpecialChar ~
9591 \SpecialChar ~
9592 out_byte <<= 1;
9593 \newline
9594 \SpecialChar ~
9595 \SpecialChar ~
9596 \SpecialChar ~
9597 \SpecialChar ~
9598 \SpecialChar ~
9599 \SpecialChar ~
9600 \SpecialChar ~
9601 \SpecialChar ~
9602 MCLK = 1;
9603 \newline
9604 \SpecialChar ~
9605 \SpecialChar ~
9606 \SpecialChar ~
9607 \SpecialChar ~
9608 \SpecialChar ~
9609 \SpecialChar ~
9610 \SpecialChar ~
9611 \SpecialChar ~
9612 /* _asm nop _endasm; */\SpecialChar ~
9613 \SpecialChar ~
9614 \SpecialChar ~
9615 \SpecialChar ~
9616 \SpecialChar ~
9617 \SpecialChar ~
9618 \SpecialChar ~
9619 \SpecialChar ~
9620 /* for slow peripherals */
9621 \newline
9622 \SpecialChar ~
9623 \SpecialChar ~
9624 \SpecialChar ~
9625 \SpecialChar ~
9626 \SpecialChar ~
9627 \SpecialChar ~
9628 \SpecialChar ~
9629 \SpecialChar ~
9630 if(MISO)
9631 \newline
9632 \SpecialChar ~
9633 \SpecialChar ~
9634 \SpecialChar ~
9635 \SpecialChar ~
9636 \SpecialChar ~
9637 \SpecialChar ~
9638 \SpecialChar ~
9639 \SpecialChar ~
9640 \SpecialChar ~
9641 \SpecialChar ~
9642 \SpecialChar ~
9643 \SpecialChar ~
9644 out_byte += 1;
9645 \newline
9646 \SpecialChar ~
9647 \SpecialChar ~
9648 \SpecialChar ~
9649 \SpecialChar ~
9650 \SpecialChar ~
9651 \SpecialChar ~
9652 \SpecialChar ~
9653 \SpecialChar ~
9654 MCLK = 0;
9655 \newline
9656 \SpecialChar ~
9657 \SpecialChar ~
9658 \SpecialChar ~
9659 \SpecialChar ~
9660 } while(--i);
9661 \newline
9662 \SpecialChar ~
9663 \SpecialChar ~
9664 \SpecialChar ~
9665 \SpecialChar ~
9666 return out_byte;
9667 \newline
9668 }
9669 \layout Standard
9670
9671 Then, someplace in the code for the first hardware you would use
9672 \layout Verse
9673
9674
9675 \family typewriter
9676 bit at 0x80 MOSI;\SpecialChar ~
9677 \SpecialChar ~
9678 \SpecialChar ~
9679 \SpecialChar ~
9680 /* I/O port 0, bit 0 */
9681 \newline
9682 bit at 0x81 MISO;\SpecialChar ~
9683 \SpecialChar ~
9684 \SpecialChar ~
9685 \SpecialChar ~
9686 /* I/O port 0, bit 1 */
9687 \newline
9688 bit at 0x82 MCLK;\SpecialChar ~
9689 \SpecialChar ~
9690 \SpecialChar ~
9691 \SpecialChar ~
9692 /* I/O port 0, bit 2 */
9693 \layout Standard
9694
9695 Similarly, for the second hardware you would use
9696 \layout Verse
9697
9698
9699 \family typewriter
9700 bit at 0x83 MOSI;\SpecialChar ~
9701 \SpecialChar ~
9702 \SpecialChar ~
9703 \SpecialChar ~
9704 /* I/O port 0, bit 3 */
9705 \newline
9706 bit at 0x91 MISO;\SpecialChar ~
9707 \SpecialChar ~
9708 \SpecialChar ~
9709 \SpecialChar ~
9710 /* I/O port 1, bit 1 */
9711 \newline
9712 bit
9713 \begin_inset LatexCommand \index{bit}
9714
9715 \end_inset
9716
9717  at 0x92 MCLK;\SpecialChar ~
9718 \SpecialChar ~
9719 \SpecialChar ~
9720 \SpecialChar ~
9721 /* I/O port 1, bit 2 */
9722 \layout Standard
9723
9724 and you can use the same hardware dependent routine without changes, as
9725  for example in a library.
9726  This is somehow similar to sbit, but only one absolute address has to be
9727  specified in the whole project.
9728 \layout Section
9729
9730 Parameters
9731 \begin_inset LatexCommand \index{Parameters}
9732
9733 \end_inset
9734
9735
9736 \begin_inset LatexCommand \index{function parameter}
9737
9738 \end_inset
9739
9740  & Local Variables
9741 \begin_inset LatexCommand \index{local variables}
9742
9743 \end_inset
9744
9745
9746 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
9747
9748 \end_inset
9749
9750
9751 \layout Standard
9752
9753 Automatic (local) variables and parameters to functions can either be placed
9754  on the stack or in data-space.
9755  The default action of the compiler is to place these variables in the internal
9756  RAM (for small model) or external RAM (for large model).
9757  This in fact makes them similar to
9758 \emph on
9759 static
9760 \begin_inset LatexCommand \index{static}
9761
9762 \end_inset
9763
9764
9765 \emph default
9766  so by default functions are non-reentrant
9767 \begin_inset LatexCommand \index{reentrant}
9768
9769 \end_inset
9770
9771 .
9772
9773 \newline
9774
9775 \newline
9776 They can be placed on the stack
9777 \begin_inset LatexCommand \index{stack}
9778
9779 \end_inset
9780
9781  by 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 -stack-auto
9794 \begin_inset LatexCommand \index{-\/-stack-auto}
9795
9796 \end_inset
9797
9798
9799 \emph default
9800  option, by using
9801 \emph on
9802 #pragma\SpecialChar ~
9803 stackauto
9804 \emph default
9805
9806 \begin_inset LatexCommand \index{\#pragma stackauto}
9807
9808 \end_inset
9809
9810  or by using the
9811 \emph on
9812 reentrant
9813 \begin_inset LatexCommand \index{reentrant}
9814
9815 \end_inset
9816
9817
9818 \emph default
9819  keyword in the function declaration, e.g.:
9820 \layout Verse
9821
9822
9823 \family typewriter
9824 unsigned char foo(char i) reentrant
9825 \newline
9826 {
9827 \newline
9828 \SpecialChar ~
9829 \SpecialChar ~
9830 \SpecialChar ~
9831 \SpecialChar ~
9832 ...
9833
9834 \newline
9835 }
9836 \layout Standard
9837
9838 Since stack space on 8051 is limited, the
9839 \emph on
9840 reentrant
9841 \emph default
9842 keyword or the
9843 \emph on
9844  -
9845 \begin_inset ERT
9846 status Collapsed
9847
9848 \layout Standard
9849
9850 \backslash
9851 /
9852 \end_inset
9853
9854 -stack-auto
9855 \emph default
9856  option should be used sparingly.
9857  Note that the reentrant keyword just means that the parameters & local
9858  variables will be allocated to the stack, it
9859 \emph on
9860 does not
9861 \emph default
9862  mean that the function is register bank
9863 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9864
9865 \end_inset
9866
9867  independent.
9868 \newline
9869
9870 \newline
9871 Local variables
9872 \begin_inset LatexCommand \index{local variables}
9873
9874 \end_inset
9875
9876  can be assigned storage classes and absolute
9877 \begin_inset LatexCommand \index{Absolute addressing}
9878
9879 \end_inset
9880
9881  addresses, e.g.:
9882 \layout Verse
9883
9884
9885 \family typewriter
9886 unsigned char foo()
9887 \newline
9888 {
9889 \newline
9890 \SpecialChar ~
9891 \SpecialChar ~
9892 \SpecialChar ~
9893 \SpecialChar ~
9894 xdata unsigned char i;
9895 \newline
9896 \SpecialChar ~
9897 \SpecialChar ~
9898 \SpecialChar ~
9899 \SpecialChar ~
9900 bit bvar;
9901 \newline
9902 \SpecialChar ~
9903 \SpecialChar ~
9904 \SpecialChar ~
9905 \SpecialChar ~
9906 data at
9907 \begin_inset LatexCommand \index{at}
9908
9909 \end_inset
9910
9911  0x31 unsigned char j;
9912 \newline
9913 \SpecialChar ~
9914 \SpecialChar ~
9915 \SpecialChar ~
9916 \SpecialChar ~
9917 ...
9918
9919 \newline
9920 }
9921 \layout Standard
9922
9923 In the above example the variable
9924 \emph on
9925 i
9926 \emph default
9927  will be allocated in the external ram,
9928 \emph on
9929 bvar
9930 \emph default
9931  in bit addressable space and
9932 \emph on
9933  j
9934 \emph default
9935  in internal ram.
9936  When compiled with
9937 \emph on
9938 -
9939 \begin_inset ERT
9940 status Collapsed
9941
9942 \layout Standard
9943
9944 \backslash
9945 /
9946 \end_inset
9947
9948 -stack-auto
9949 \emph default
9950  or when a function is declared as
9951 \emph on
9952 reentrant
9953 \emph default
9954  this should only be done for static variables.
9955 \layout Standard
9956
9957 Parameters
9958 \begin_inset LatexCommand \index{function parameter}
9959
9960 \end_inset
9961
9962  however are not allowed any storage class
9963 \begin_inset LatexCommand \index{Storage class}
9964
9965 \end_inset
9966
9967 , (storage classes for parameters will be ignored), their allocation is
9968  governed by the memory model in use, and the reentrancy options.
9969 \layout Section
9970
9971 Overlaying
9972 \begin_inset LatexCommand \label{sub:Overlaying}
9973
9974 \end_inset
9975
9976
9977 \begin_inset LatexCommand \index{Overlaying}
9978
9979 \end_inset
9980
9981
9982 \layout Standard
9983
9984 For non-reentrant
9985 \begin_inset LatexCommand \index{reentrant}
9986
9987 \end_inset
9988
9989  functions SDCC will try to reduce internal ram space usage by overlaying
9990  parameters and local variables of a function (if possible).
9991  Parameters and local variables
9992 \begin_inset LatexCommand \index{local variables}
9993
9994 \end_inset
9995
9996  of a function will be allocated to an overlayable segment if the function
9997  has
9998 \emph on
9999 no other function calls and the function is non-reentrant and the memory
10000  model
10001 \begin_inset LatexCommand \index{Memory model}
10002
10003 \end_inset
10004
10005  is small.
10006
10007 \emph default
10008  If an explicit storage class
10009 \begin_inset LatexCommand \index{Storage class}
10010
10011 \end_inset
10012
10013  is specified for a local variable, it will NOT be overlayed.
10014 \layout Standard
10015
10016 Note that the compiler (not the linkage editor) makes the decision for overlayin
10017 g the data items.
10018  Functions that are called from an interrupt service routine should be preceded
10019  by a #pragma\SpecialChar ~
10020 nooverlay
10021 \begin_inset LatexCommand \index{\#pragma nooverlay}
10022
10023 \end_inset
10024
10025  if they are not reentrant.
10026 \layout Standard
10027
10028 Also note that the compiler does not do any processing of inline assembler
10029  code, so the compiler might incorrectly assign local variables and parameters
10030  of a function into the overlay segment if the inline assembler code calls
10031  other c-functions that might use the overlay.
10032  In that case the #pragma\SpecialChar ~
10033 nooverlay should be used.
10034 \layout Standard
10035
10036 Parameters and local variables of functions that contain 16 or 32 bit multiplica
10037 tion
10038 \begin_inset LatexCommand \index{Multiplication}
10039
10040 \end_inset
10041
10042  or division
10043 \begin_inset LatexCommand \index{Division}
10044
10045 \end_inset
10046
10047  will NOT be overlayed since these are implemented using external functions,
10048  e.g.:
10049 \layout Verse
10050
10051
10052 \family typewriter
10053 #pragma save
10054 \newline
10055 #pragma nooverlay
10056 \begin_inset LatexCommand \index{\#pragma nooverlay}
10057
10058 \end_inset
10059
10060
10061 \newline
10062 void set_error(unsigned char errcd)
10063 \newline
10064 {
10065 \newline
10066 \SpecialChar ~
10067 \SpecialChar ~
10068 \SpecialChar ~
10069 \SpecialChar ~
10070 P3 = errcd;
10071 \newline
10072 }
10073 \newline
10074 #pragma restore
10075 \newline
10076
10077 \newline
10078 void some_isr () interrupt
10079 \begin_inset LatexCommand \index{interrupt}
10080
10081 \end_inset
10082
10083  2
10084 \newline
10085 {
10086 \newline
10087 \SpecialChar ~
10088 \SpecialChar ~
10089 \SpecialChar ~
10090 \SpecialChar ~
10091 ...
10092 \newline
10093 \SpecialChar ~
10094 \SpecialChar ~
10095 \SpecialChar ~
10096 \SpecialChar ~
10097 set_error(10);
10098 \newline
10099 \SpecialChar ~
10100 \SpecialChar ~
10101 \SpecialChar ~
10102 \SpecialChar ~
10103 ...
10104
10105 \newline
10106 }
10107 \layout Standard
10108
10109 In the above example the parameter
10110 \emph on
10111 errcd
10112 \emph default
10113  for the function
10114 \emph on
10115 set_error
10116 \emph default
10117  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
10118 nooverlay was
10119  not present, this could cause unpredictable runtime behavior when called
10120  from an interrupt service routine.
10121  The #pragma\SpecialChar ~
10122 nooverlay ensures that the parameters and local variables for
10123  the function are NOT overlayed.
10124 \layout Section
10125
10126 Interrupt Service Routines
10127 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
10128
10129 \end_inset
10130
10131
10132 \layout Subsection
10133
10134 General Information
10135 \layout Standard
10136
10137 SDCC allows
10138 \emph on
10139 i
10140 \emph default
10141 nterrupt
10142 \emph on
10143 s
10144 \emph default
10145 ervice
10146 \emph on
10147 r
10148 \emph default
10149 outines to be coded in C, with some extended keywords.
10150 \layout Verse
10151
10152
10153 \family typewriter
10154 void timer_isr (void) interrupt 1 using 1
10155 \newline
10156 {
10157 \newline
10158 \SpecialChar ~
10159 \SpecialChar ~
10160 \SpecialChar ~
10161 \SpecialChar ~
10162 ...
10163
10164 \newline
10165 }
10166 \layout Standard
10167
10168 The optional number following the
10169 \emph on
10170 interrupt
10171 \begin_inset LatexCommand \index{interrupt}
10172
10173 \end_inset
10174
10175
10176 \emph default
10177  keyword is the interrupt number this routine will service.
10178  When present, the compiler will insert a call to this routine in the interrupt
10179  vector table for the interrupt number specified.
10180  If you have multiple source files in your project, interrupt service routines
10181  can be present in any of them, but a prototype of the isr MUST be present
10182  or included in the file that contains the function
10183 \emph on
10184 main
10185 \emph default
10186 .
10187  The
10188 \emph on
10189 using
10190 \emph default
10191  keyword can be used to tell the compiler to use the specified register
10192  bank (8051 specific) when generating code for this function.
10193
10194 \newline
10195
10196 \layout Standard
10197
10198 Interrupt service routines open the door for some very interesting bugs:
10199 \newline
10200 If an interrupt service routine changes variables which are accessed by
10201  other functions these variables have to be declared
10202 \emph on
10203 volatile
10204 \emph default
10205
10206 \begin_inset LatexCommand \index{volatile}
10207
10208 \end_inset
10209
10210 .
10211
10212 \layout Standard
10213
10214 If the access to these variables is not
10215 \emph on
10216 atomic
10217 \begin_inset LatexCommand \index{atomic}
10218
10219 \end_inset
10220
10221
10222 \emph default
10223  (i.e.
10224  the processor needs more than one instruction for the access and could
10225  be interrupted while accessing the variable) the interrupt must be disabled
10226  during the access to avoid inconsistent data.
10227  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10228  and should be protected by disabling interrupts.
10229  You're not automatically on the safe side if you use 8 bit variables though.
10230  We need an example here: f.e.
10231  on the 8051 the harmless looking
10232 \begin_inset Quotes srd
10233 \end_inset
10234
10235
10236 \family typewriter
10237 flags\SpecialChar ~
10238 |=\SpecialChar ~
10239 0x80;
10240 \family default
10241
10242 \begin_inset Quotes sld
10243 \end_inset
10244
10245  is not atomic if
10246 \family typewriter
10247 flags
10248 \family default
10249  resides in xdata.
10250  Setting
10251 \begin_inset Quotes srd
10252 \end_inset
10253
10254
10255 \family typewriter
10256 flags\SpecialChar ~
10257 |=\SpecialChar ~
10258 0x40;
10259 \family default
10260
10261 \begin_inset Quotes sld
10262 \end_inset
10263
10264  from within an interrupt routine might get lost if the interrupt occurs
10265  at the wrong time.
10266
10267 \begin_inset Quotes sld
10268 \end_inset
10269
10270
10271 \family typewriter
10272 counter\SpecialChar ~
10273 +=\SpecialChar ~
10274 8;
10275 \family default
10276
10277 \begin_inset Quotes srd
10278 \end_inset
10279
10280  is not atomic on the 8051 even if
10281 \family typewriter
10282 counter
10283 \family default
10284  is located in data memory.
10285  Bugs like these are hard to reproduce and can cause a lot of trouble.
10286
10287 \layout Standard
10288
10289 The return address and the registers used in the interrupt service routine
10290  are saved on the stack
10291 \begin_inset LatexCommand \index{stack}
10292
10293 \end_inset
10294
10295  so there must be sufficient stack space.
10296  If there isn't variables or registers (or even the return address itself)
10297  will be corrupted.
10298  This
10299 \emph on
10300 stack overflow
10301 \emph default
10302
10303 \begin_inset LatexCommand \index{stack overflow}
10304
10305 \end_inset
10306
10307  is most likely to happen if the interrupt occurs during the
10308 \begin_inset Quotes sld
10309 \end_inset
10310
10311 deepest
10312 \begin_inset Quotes srd
10313 \end_inset
10314
10315  subroutine when the stack is already in use for f.e.
10316  many return addresses.
10317 \layout Standard
10318
10319 A special note here, int (16 bit) and long (32 bit) integer division
10320 \begin_inset LatexCommand \index{Division}
10321
10322 \end_inset
10323
10324 , multiplication
10325 \begin_inset LatexCommand \index{Multiplication}
10326
10327 \end_inset
10328
10329  & modulus
10330 \begin_inset LatexCommand \index{Modulus}
10331
10332 \end_inset
10333
10334  and floating-point
10335 \begin_inset LatexCommand \index{Floating point support}
10336
10337 \end_inset
10338
10339  operations are implemented using external support routines developed in
10340  ANSI-C.
10341  If an interrupt service routine needs to do any of these operations then
10342  the support routines (as mentioned in a following section) will have to
10343  be recompiled using the
10344 \emph on
10345  -
10346 \begin_inset ERT
10347 status Collapsed
10348
10349 \layout Standard
10350
10351 \backslash
10352 /
10353 \end_inset
10354
10355 -stack-auto
10356 \begin_inset LatexCommand \index{-\/-stack-auto}
10357
10358 \end_inset
10359
10360
10361 \emph default
10362  option and the source file will need to be compiled using the
10363 \emph on
10364 -
10365 \begin_inset ERT
10366 status Collapsed
10367
10368 \layout Standard
10369
10370 \backslash
10371 /
10372 \end_inset
10373
10374 -int-long-reent
10375 \emph default
10376
10377 \begin_inset LatexCommand \index{-\/-int-long-reent}
10378
10379 \end_inset
10380
10381  compiler option.
10382 \layout Standard
10383
10384 Calling other functions from an interrupt service routine is not recommended,
10385  avoid it if possible.
10386  Note that when some function is called from an interrupt service routine
10387  it should be preceded by a #pragma\SpecialChar ~
10388 nooverlay
10389 \begin_inset LatexCommand \index{\#pragma nooverlay}
10390
10391 \end_inset
10392
10393  if it is not reentrant.
10394  Furthermore nonreentrant functions should not be called from the main program
10395  while the interrupt service routine might be active.
10396
10397 \newline
10398
10399 \newline
10400 Also see section
10401 \begin_inset LatexCommand \ref{sub:Overlaying}
10402
10403 \end_inset
10404
10405 \SpecialChar ~
10406 about Overlaying and section
10407 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10408
10409 \end_inset
10410
10411 \SpecialChar ~
10412 about Functions using private register banks.
10413 \layout Subsection
10414
10415 MCS51/DS390 Interrupt Service Routines
10416 \layout Standard
10417
10418 Interrupt numbers and the corresponding address & descriptions for the Standard
10419  8051/8052 are listed below.
10420  SDCC will automatically adjust the interrupt vector table to the maximum
10421  interrupt number specified.
10422 \newline
10423
10424 \layout Standard
10425 \align center
10426
10427 \begin_inset  Tabular
10428 <lyxtabular version="3" rows="7" columns="3">
10429 <features>
10430 <column alignment="center" valignment="top" leftline="true" width="0in">
10431 <column alignment="center" valignment="top" leftline="true" width="0in">
10432 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10433 <row topline="true" bottomline="true">
10434 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10435 \begin_inset Text
10436
10437 \layout Standard
10438
10439 Interrupt #
10440 \end_inset
10441 </cell>
10442 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10443 \begin_inset Text
10444
10445 \layout Standard
10446
10447 Description
10448 \end_inset
10449 </cell>
10450 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10451 \begin_inset Text
10452
10453 \layout Standard
10454
10455 Vector Address
10456 \end_inset
10457 </cell>
10458 </row>
10459 <row topline="true">
10460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10461 \begin_inset Text
10462
10463 \layout Standard
10464
10465 0
10466 \end_inset
10467 </cell>
10468 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10469 \begin_inset Text
10470
10471 \layout Standard
10472
10473 External 0
10474 \end_inset
10475 </cell>
10476 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10477 \begin_inset Text
10478
10479 \layout Standard
10480
10481 0x0003
10482 \end_inset
10483 </cell>
10484 </row>
10485 <row topline="true">
10486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10487 \begin_inset Text
10488
10489 \layout Standard
10490
10491 1
10492 \end_inset
10493 </cell>
10494 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10495 \begin_inset Text
10496
10497 \layout Standard
10498
10499 Timer 0
10500 \end_inset
10501 </cell>
10502 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10503 \begin_inset Text
10504
10505 \layout Standard
10506
10507 0x000B
10508 \end_inset
10509 </cell>
10510 </row>
10511 <row topline="true">
10512 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10513 \begin_inset Text
10514
10515 \layout Standard
10516
10517 2
10518 \end_inset
10519 </cell>
10520 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10521 \begin_inset Text
10522
10523 \layout Standard
10524
10525 External 1
10526 \end_inset
10527 </cell>
10528 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10529 \begin_inset Text
10530
10531 \layout Standard
10532
10533 0x0013
10534 \end_inset
10535 </cell>
10536 </row>
10537 <row topline="true">
10538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10539 \begin_inset Text
10540
10541 \layout Standard
10542
10543 3
10544 \end_inset
10545 </cell>
10546 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10547 \begin_inset Text
10548
10549 \layout Standard
10550
10551 Timer 1
10552 \end_inset
10553 </cell>
10554 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10555 \begin_inset Text
10556
10557 \layout Standard
10558
10559 0x001B
10560 \end_inset
10561 </cell>
10562 </row>
10563 <row topline="true">
10564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10565 \begin_inset Text
10566
10567 \layout Standard
10568
10569 4
10570 \end_inset
10571 </cell>
10572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10573 \begin_inset Text
10574
10575 \layout Standard
10576
10577 Serial
10578 \end_inset
10579 </cell>
10580 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10581 \begin_inset Text
10582
10583 \layout Standard
10584
10585 0x0023
10586 \end_inset
10587 </cell>
10588 </row>
10589 <row topline="true" bottomline="true">
10590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10591 \begin_inset Text
10592
10593 \layout Standard
10594
10595 5
10596 \end_inset
10597 </cell>
10598 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10599 \begin_inset Text
10600
10601 \layout Standard
10602
10603 Timer 2 (8052)
10604 \end_inset
10605 </cell>
10606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10607 \begin_inset Text
10608
10609 \layout Standard
10610
10611 0x002B
10612 \end_inset
10613 </cell>
10614 </row>
10615 </lyxtabular>
10616
10617 \end_inset
10618
10619
10620 \newline
10621
10622 \layout Standard
10623
10624 If the interrupt service routine is defined without
10625 \emph on
10626 using
10627 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10628
10629 \end_inset
10630
10631
10632 \emph default
10633  a register bank or with register bank 0 (
10634 \emph on
10635 using
10636 \emph default
10637  0), the compiler will save the registers used by itself on the stack upon
10638  entry and restore them at exit, however if such an interrupt service routine
10639  calls another function then the entire register bank will be saved on the
10640  stack.
10641  This scheme may be advantageous for small interrupt service routines which
10642  have low register usage.
10643 \layout Standard
10644
10645 If the interrupt service routine is defined to be using a specific register
10646  bank then only
10647 \emph on
10648 a, b, dptr
10649 \emph default
10650  & psw are saved and restored, if such an interrupt service routine calls
10651  another function (using another register bank) then the entire register
10652  bank of the called function will be saved on the stack.
10653  This scheme is recommended for larger interrupt service routines.
10654 \layout Subsection
10655
10656 HC08 Interrupt Service Routines
10657 \layout Standard
10658
10659 Since the number of interrupts available is chip specific and the interrupt
10660  vector table always ends at the last byte of memory, the interrupt numbers
10661  corresponds to the interrupt vectors in reverse order of address.
10662  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
10663  2 will use the interrupt vector at 0xfffa, and so on.
10664  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
10665  this way; instead see section
10666 \begin_inset LatexCommand \ref{sub:Startup-Code}
10667
10668 \end_inset
10669
10670  for details on customizing startup.
10671 \layout Subsection
10672
10673 Z80 Interrupt Service Routines
10674 \layout Standard
10675
10676 The Z80 uses several different methods for determining the correct interrupt
10677  vector depending on the hardware implementation.
10678  Therefore, SDCC ignores the optional interrupt number and does not attempt
10679  to generate an interrupt vector table.
10680 \layout Standard
10681
10682 By default, SDCC generates code for a maskable interrupt, which uses an
10683  RETI instruction to return from the interrupt.
10684  To write an interrupt handler for the non-maskable interrupt, which needs
10685  an RETN instruction instead, add the
10686 \emph on
10687 critical
10688 \emph default
10689  keyword:
10690 \layout Verse
10691
10692
10693 \family typewriter
10694 void nmi_isr (void) critical interrupt
10695 \newline
10696 {
10697 \newline
10698 \SpecialChar ~
10699 \SpecialChar ~
10700 \SpecialChar ~
10701 \SpecialChar ~
10702 ...
10703
10704 \newline
10705 }
10706 \layout Section
10707
10708 Enabling and Disabling Interrupts
10709 \layout Subsection
10710
10711 Critical Functions and Critical Statements
10712 \layout Standard
10713
10714 A special keyword may be associated with a block or a function declaring
10715  it as
10716 \emph on
10717 critical
10718 \emph default
10719 .
10720  SDCC will generate code to disable all interrupts
10721 \begin_inset LatexCommand \index{interrupt}
10722
10723 \end_inset
10724
10725  upon entry to a critical function and restore the interrupt enable to the
10726  previous state before returning.
10727  Nesting critical functions will need one additional byte on the stack
10728 \begin_inset LatexCommand \index{stack}
10729
10730 \end_inset
10731
10732  for each call.
10733 \layout Verse
10734
10735
10736 \family typewriter
10737 int foo () critical
10738 \begin_inset LatexCommand \index{critical}
10739
10740 \end_inset
10741
10742
10743 \newline
10744 {
10745 \newline
10746 \SpecialChar ~
10747 \SpecialChar ~
10748 \SpecialChar ~
10749 \SpecialChar ~
10750 ...
10751
10752 \newline
10753 \SpecialChar ~
10754 \SpecialChar ~
10755 \SpecialChar ~
10756 \SpecialChar ~
10757 ...
10758
10759 \newline
10760 }
10761 \layout Standard
10762
10763 The critical attribute maybe used with other attributes like
10764 \emph on
10765 reentrant.
10766 \emph default
10767
10768 \newline
10769 The keyword
10770 \emph on
10771 critical
10772 \emph default
10773  may also be used to disable interrupts more locally:
10774 \layout Verse
10775
10776
10777 \family typewriter
10778 critical{ i++; }
10779 \layout Standard
10780
10781 More than one statement could have been included in the block.
10782 \layout Subsection
10783
10784 Enabling and Disabling Interrupts directly
10785 \layout Standard
10786
10787 Interrupts
10788 \begin_inset LatexCommand \index{interrupt}
10789
10790 \end_inset
10791
10792  can also be disabled and enabled directly (8051):
10793 \layout Verse
10794
10795
10796 \family typewriter
10797 EA = 0;\SpecialChar ~
10798 \SpecialChar ~
10799 \SpecialChar ~
10800 \SpecialChar ~
10801 \SpecialChar ~
10802 \SpecialChar ~
10803 \SpecialChar ~
10804 \SpecialChar ~
10805 \SpecialChar ~
10806 \SpecialChar ~
10807 \SpecialChar ~
10808 \SpecialChar ~
10809 or:\SpecialChar ~
10810 \SpecialChar ~
10811 \SpecialChar ~
10812 \SpecialChar ~
10813 \SpecialChar ~
10814 \SpecialChar ~
10815 \SpecialChar ~
10816 \SpecialChar ~
10817 \SpecialChar ~
10818 \SpecialChar ~
10819 \SpecialChar ~
10820 EA_SAVE = EA;
10821 \layout Verse
10822
10823
10824 \family typewriter
10825 ...\SpecialChar ~
10826 \SpecialChar ~
10827 \SpecialChar ~
10828 \SpecialChar ~
10829 \SpecialChar ~
10830 \SpecialChar ~
10831 \SpecialChar ~
10832 \SpecialChar ~
10833 \SpecialChar ~
10834 \SpecialChar ~
10835 \SpecialChar ~
10836 \SpecialChar ~
10837 \SpecialChar ~
10838 \SpecialChar ~
10839 \SpecialChar ~
10840 \SpecialChar ~
10841 \SpecialChar ~
10842 \SpecialChar ~
10843 \SpecialChar ~
10844 \SpecialChar ~
10845 \SpecialChar ~
10846 \SpecialChar ~
10847 \SpecialChar ~
10848 \SpecialChar ~
10849 \SpecialChar ~
10850 \SpecialChar ~
10851 \SpecialChar ~
10852 \SpecialChar ~
10853 \SpecialChar ~
10854 \SpecialChar ~
10855 EA = 0;
10856 \layout Verse
10857
10858
10859 \family typewriter
10860 EA = 1;\SpecialChar ~
10861 \SpecialChar ~
10862 \SpecialChar ~
10863 \SpecialChar ~
10864 \SpecialChar ~
10865 \SpecialChar ~
10866 \SpecialChar ~
10867 \SpecialChar ~
10868 \SpecialChar ~
10869 \SpecialChar ~
10870 \SpecialChar ~
10871 \SpecialChar ~
10872 \SpecialChar ~
10873 \SpecialChar ~
10874 \SpecialChar ~
10875 \SpecialChar ~
10876 \SpecialChar ~
10877 \SpecialChar ~
10878 \SpecialChar ~
10879 \SpecialChar ~
10880 \SpecialChar ~
10881 \SpecialChar ~
10882 \SpecialChar ~
10883 \SpecialChar ~
10884 \SpecialChar ~
10885 \SpecialChar ~
10886 ...
10887 \layout Verse
10888
10889
10890 \family typewriter
10891 \SpecialChar ~
10892 \SpecialChar ~
10893 \SpecialChar ~
10894 \SpecialChar ~
10895 \SpecialChar ~
10896 \SpecialChar ~
10897 \SpecialChar ~
10898 \SpecialChar ~
10899 \SpecialChar ~
10900 \SpecialChar ~
10901 \SpecialChar ~
10902 \SpecialChar ~
10903 \SpecialChar ~
10904 \SpecialChar ~
10905 \SpecialChar ~
10906 \SpecialChar ~
10907 \SpecialChar ~
10908 \SpecialChar ~
10909 \SpecialChar ~
10910 \SpecialChar ~
10911 \SpecialChar ~
10912 \SpecialChar ~
10913 \SpecialChar ~
10914 \SpecialChar ~
10915 \SpecialChar ~
10916 \SpecialChar ~
10917 \SpecialChar ~
10918 \SpecialChar ~
10919 \SpecialChar ~
10920 \SpecialChar ~
10921 \SpecialChar ~
10922 \SpecialChar ~
10923 \SpecialChar ~
10924 EA = EA_SAVE;
10925 \layout Standard
10926
10927 On other architectures which have seperate opcodes for enabling and disabling
10928  interrupts you might want to make use of defines with inline assembly
10929 \begin_inset LatexCommand \index{Assembler routines}
10930
10931 \end_inset
10932
10933  (HC08):
10934 \layout Verse
10935
10936
10937 \family typewriter
10938 #define CLI _asm
10939 \begin_inset LatexCommand \index{\_asm}
10940
10941 \end_inset
10942
10943 \SpecialChar ~
10944 \SpecialChar ~
10945 cli\SpecialChar ~
10946 \SpecialChar ~
10947 _endasm
10948 \begin_inset LatexCommand \index{\_endasm}
10949
10950 \end_inset
10951
10952 ;
10953 \layout Verse
10954
10955
10956 \family typewriter
10957 #define SEI _asm\SpecialChar ~
10958 \SpecialChar ~
10959 sei\SpecialChar ~
10960 \SpecialChar ~
10961 _endasm;
10962 \layout Verse
10963
10964
10965 \family typewriter
10966 ...
10967 \layout Standard
10968
10969 Note: it is sometimes sufficient to disable only a specific interrupt source
10970  like f.e.
10971  a timer or serial interrupt by manipulating an
10972 \emph on
10973 interrupt mask
10974 \begin_inset LatexCommand \index{interrupt mask}
10975
10976 \end_inset
10977
10978
10979 \emph default
10980  register.
10981
10982 \layout Standard
10983
10984 Usually the time during which interrupts are disabled should be kept as
10985  short as possible.
10986  This minimizes both
10987 \emph on
10988 interrupt latency
10989 \emph default
10990
10991 \begin_inset LatexCommand \index{interrupt latency}
10992
10993 \end_inset
10994
10995  (the time between the occurrence of the interrupt and the execution of
10996  the first code in the interrupt routine) and
10997 \emph on
10998 interrupt jitter
10999 \emph default
11000
11001 \begin_inset LatexCommand \index{interrupt jitter}
11002
11003 \end_inset
11004
11005  (the difference between the shortest and the longest interrupt latency).
11006  These really are something different, f.e.
11007  a serial interrupt has to be served before its buffer overruns so it cares
11008  for the maximum interrupt latency, whereas it does not care about jitter.
11009  On a loudspeaker driven via a digital to analog converter which is fed
11010  by an interrupt a latency of a few milliseconds might be tolerable, whereas
11011  a much smaller jitter will be very audible.
11012 \layout Standard
11013
11014 You can reenable interrupts within an interrupt routine and on some architecture
11015 s you can make use of two (or more) levels of
11016 \emph on
11017 interrupt priorities
11018 \emph default
11019
11020 \begin_inset LatexCommand \index{interrupt priority}
11021
11022 \end_inset
11023
11024 .
11025  On some architectures which don't support interrupt priorities these can
11026  be implemented by manipulating the interrupt mask and reenabling interrupts
11027  within the interrupt routine.
11028  Check there is sufficient space on the stack
11029 \begin_inset LatexCommand \index{stack}
11030
11031 \end_inset
11032
11033  and don't add complexity unless you have to.
11034
11035 \layout Subsection
11036
11037 Semaphore
11038 \begin_inset LatexCommand \index{semaphore}
11039
11040 \end_inset
11041
11042  locking (mcs51/ds390)
11043 \layout Standard
11044
11045 Some architectures (mcs51/ds390) have an atomic
11046 \begin_inset LatexCommand \index{atomic}
11047
11048 \end_inset
11049
11050  bit test and
11051 \emph on
11052
11053 \emph default
11054 clear
11055 \emph on
11056
11057 \emph default
11058 instruction.
11059  These type of instructions are typically used in preemptive multitasking
11060  systems, where a routine f.e.
11061  claims the use of a data structure ('acquires a lock
11062 \begin_inset LatexCommand \index{lock}
11063
11064 \end_inset
11065
11066  on it'), makes some modifications and then releases the lock when the data
11067  structure is consistent again.
11068  The instruction may also be used if interrupt and non-interrupt code have
11069  to compete for a resource.
11070  With the atomic bit test and clear instruction interrupts
11071 \begin_inset LatexCommand \index{interrupt}
11072
11073 \end_inset
11074
11075  don't have to be disabled for the locking operation.
11076
11077 \layout Standard
11078
11079 SDCC generates this instruction if the source follows this pattern:
11080 \layout Verse
11081
11082
11083 \family typewriter
11084 volatile bit resource_is_free;
11085 \newline
11086
11087 \newline
11088 if (resource_is_free)
11089 \newline
11090 \SpecialChar ~
11091 \SpecialChar ~
11092 {
11093 \newline
11094 \SpecialChar ~
11095 \SpecialChar ~
11096 \SpecialChar ~
11097 \SpecialChar ~
11098 resource_is_free=0;
11099 \newline
11100 \SpecialChar ~
11101 \SpecialChar ~
11102 \SpecialChar ~
11103 \SpecialChar ~
11104 ...
11105
11106 \newline
11107 \SpecialChar ~
11108 \SpecialChar ~
11109 \SpecialChar ~
11110 \SpecialChar ~
11111 resource_is_free=1;
11112 \newline
11113 \SpecialChar ~
11114 \SpecialChar ~
11115 }
11116 \layout Standard
11117
11118 Note, mcs51 and ds390 support only an atomic
11119 \begin_inset LatexCommand \index{atomic}
11120
11121 \end_inset
11122
11123  bit test and
11124 \emph on
11125 clear
11126 \emph default
11127  instruction (as opposed to atomic bit test and
11128 \emph on
11129 set).
11130 \layout Section
11131
11132 Functions using private register banks
11133 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
11134
11135 \end_inset
11136
11137  (mcs51/ds390)
11138 \layout Standard
11139
11140 Some architectures have support for quickly changing register sets.
11141  SDCC supports this feature with the
11142 \emph on
11143 using
11144 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
11145
11146 \end_inset
11147
11148
11149 \emph default
11150  attribute (which tells the compiler to use a register bank
11151 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
11152
11153 \end_inset
11154
11155  other than the default bank zero).
11156  It should only be applied to
11157 \emph on
11158 interrupt
11159 \begin_inset LatexCommand \index{interrupt}
11160
11161 \end_inset
11162
11163
11164 \emph default
11165  functions (see footnote below).
11166  This will in most circumstances make the generated ISR code more efficient
11167  since it will not have to save registers on the stack.
11168 \layout Standard
11169
11170 The
11171 \emph on
11172 using
11173 \emph default
11174  attribute will have no effect on the generated code for a
11175 \emph on
11176 non-interrupt
11177 \emph default
11178  function (but may occasionally be useful anyway
11179 \begin_inset Foot
11180 collapsed false
11181
11182 \layout Standard
11183
11184 possible exception: if a function is called ONLY from 'interrupt' functions
11185  using a particular bank, it can be declared with the same 'using' attribute
11186  as the calling 'interrupt' functions.
11187  For instance, if you have several ISRs using bank one, and all of them
11188  call memcpy(), it might make sense to create a specialized version of memcpy()
11189  'using 1', since this would prevent the ISR from having to save bank zero
11190  to the stack on entry and switch to bank zero before calling the function
11191 \end_inset
11192
11193 ).
11194 \newline
11195
11196 \emph on
11197 (pending: I don't think this has been done yet)
11198 \layout Standard
11199
11200 An
11201 \emph on
11202 interrupt
11203 \emph default
11204  function using a non-zero bank will assume that it can trash that register
11205  bank, and will not save it.
11206  Since high-priority interrupts
11207 \begin_inset LatexCommand \index{interrupt priority}
11208
11209 \end_inset
11210
11211  can interrupt low-priority ones on the 8051 and friends, this means that
11212  if a high-priority ISR
11213 \emph on
11214 using
11215 \emph default
11216  a particular bank occurs while processing a low-priority ISR
11217 \emph on
11218 using
11219 \emph default
11220  the same bank, terrible and bad things can happen.
11221  To prevent this, no single register bank should be
11222 \emph on
11223 used
11224 \emph default
11225  by both a high priority and a low priority ISR.
11226  This is probably most easily done by having all high priority ISRs use
11227  one bank and all low priority ISRs use another.
11228  If you have an ISR which can change priority at runtime, you're on your
11229  own: I suggest using the default bank zero and taking the small performance
11230  hit.
11231 \layout Standard
11232
11233 It is most efficient if your ISR calls no other functions.
11234  If your ISR must call other functions, it is most efficient if those functions
11235  use the same bank as the ISR (see note 1 below); the next best is if the
11236  called functions use bank zero.
11237  It is very inefficient to call a function using a different, non-zero bank
11238  from an ISR.
11239
11240 \layout Section
11241
11242 Startup Code
11243 \begin_inset LatexCommand \label{sub:Startup-Code}
11244
11245 \end_inset
11246
11247
11248 \begin_inset LatexCommand \index{Startup code}
11249
11250 \end_inset
11251
11252
11253 \layout Subsection
11254
11255 MCS51/DS390 Startup Code
11256 \layout Standard
11257
11258 The compiler inserts a call to the C routine
11259 \emph on
11260 _sdcc_external_startup()
11261 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11262
11263 \end_inset
11264
11265
11266 \series bold
11267 \emph default
11268
11269 \series default
11270 at the start of the CODE area.
11271  This routine is in the runtime library
11272 \begin_inset LatexCommand \index{Runtime library}
11273
11274 \end_inset
11275
11276 .
11277  By default this routine returns 0, if this routine returns a non-zero value,
11278  the static & global variable initialization will be skipped and the function
11279  main will be invoked.
11280  Otherwise static & global variables will be initialized before the function
11281  main is invoked.
11282  You could add a
11283 \emph on
11284 _sdcc_external_startup()
11285 \emph default
11286  routine to your program to override the default if you need to setup hardware
11287  or perform some other critical operation prior to static & global variable
11288  initialization.
11289  On some mcs51 variants xdata has to be explicitly enabled before it can
11290  be accessed or if the watchdog needs to be disabled, this is the place
11291  to do it.
11292  The startup code clears all internal data memory, 256 bytes by default,
11293  but from 0 to n-1 if
11294 \emph on
11295 -
11296 \begin_inset ERT
11297 status Collapsed
11298
11299 \layout Standard
11300
11301 \backslash
11302 /
11303 \end_inset
11304
11305 -iram-size
11306 \begin_inset LatexCommand \index{-\/-iram-size}
11307
11308 \end_inset
11309
11310 n
11311 \emph default
11312  is used.
11313  (recommended for Chipcon CC1010).
11314 \layout Standard
11315
11316 See also the compiler option
11317 \emph on
11318 -
11319 \begin_inset ERT
11320 status Collapsed
11321
11322 \layout Standard
11323
11324 \backslash
11325 /
11326 \end_inset
11327
11328 -no-xinit
11329 \emph default
11330 -
11331 \emph on
11332 opt
11333 \emph default
11334
11335 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11336
11337 \end_inset
11338
11339  and section
11340 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11341
11342 \end_inset
11343
11344 \SpecialChar ~
11345 about MCS51-variants.
11346 \layout Subsection
11347
11348 HC08 Startup Code
11349 \layout Standard
11350
11351 The HC08 startup code follows the same scheme as the MCS51 startup code.
11352 \layout Subsection
11353
11354 Z80 Startup Code
11355 \layout Standard
11356
11357 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11358  from sdcc/device/lib/z80/crt0.s.
11359  If you need a different startup code you can use the compiler option
11360 \emph on
11361 -
11362 \series bold
11363 \emph default
11364
11365 \begin_inset ERT
11366 status Collapsed
11367
11368 \layout Standard
11369
11370 \backslash
11371 /
11372 \end_inset
11373
11374
11375 \series default
11376 \emph on
11377 -no-std-crt0
11378 \emph default
11379
11380 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11381
11382 \end_inset
11383
11384  and provide your own crt0.o.
11385
11386 \layout Section
11387
11388 Inline Assembler Code
11389 \begin_inset LatexCommand \index{Assembler routines}
11390
11391 \end_inset
11392
11393
11394 \layout Subsection
11395
11396 A Step by Step Introduction
11397 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11398
11399 \end_inset
11400
11401
11402 \layout Standard
11403
11404 Starting from a small snippet of c-code this example shows for the MCS51
11405  how to use inline assembly, access variables, a function parameter and
11406  an array in xdata memory.
11407  The example uses an MCS51 here but is easily adapted for other architectures.
11408  This is a buffer routine which should be optimized:
11409 \layout Verse
11410
11411
11412 \family typewriter
11413 \size footnotesize
11414 unsigned char far
11415 \begin_inset LatexCommand \index{far (storage class)}
11416
11417 \end_inset
11418
11419  at
11420 \begin_inset LatexCommand \index{at}
11421
11422 \end_inset
11423
11424  0x7f00 buf[0x100];
11425 \begin_inset LatexCommand \index{Aligned array}
11426
11427 \end_inset
11428
11429
11430 \newline
11431 unsigned char head,tail;
11432 \newline
11433
11434 \newline
11435 void to_buffer( unsigned char c )
11436 \newline
11437 {
11438 \newline
11439 \SpecialChar ~
11440 \SpecialChar ~
11441 \SpecialChar ~
11442 \SpecialChar ~
11443 if( head != tail-1 )
11444 \newline
11445 \SpecialChar ~
11446 \SpecialChar ~
11447 \SpecialChar ~
11448 \SpecialChar ~
11449 \SpecialChar ~
11450 \SpecialChar ~
11451 \SpecialChar ~
11452 \SpecialChar ~
11453 buf[ head++ ] = c;\SpecialChar ~
11454 \SpecialChar ~
11455 \SpecialChar ~
11456 \SpecialChar ~
11457 /* access to a 256 byte aligned array */
11458 \newline
11459 }
11460 \layout Standard
11461
11462 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11463  then a corresponding buffer.asm file is generated.
11464  We define a new function
11465 \family typewriter
11466 to_buffer_asm()
11467 \family default
11468  in file buffer.c in which we cut and paste the generated code, removing
11469  unwanted comments and some ':'.
11470  Then add
11471 \begin_inset Quotes sld
11472 \end_inset
11473
11474 _asm
11475 \begin_inset Quotes srd
11476 \end_inset
11477
11478  and
11479 \begin_inset Quotes sld
11480 \end_inset
11481
11482 _endasm;
11483 \begin_inset Quotes srd
11484 \end_inset
11485
11486  to the beginning and the end of the function body:
11487 \layout Verse
11488
11489
11490 \family typewriter
11491 \size footnotesize
11492 /* With a cut and paste from the .asm file, we have something to start with.
11493 \newline
11494 \SpecialChar ~
11495 \SpecialChar ~
11496 \SpecialChar ~
11497 The function is not yet OK! (registers aren't saved) */
11498 \newline
11499 void to_buffer_asm( unsigned char c )
11500 \newline
11501 {
11502 \newline
11503 \SpecialChar ~
11504 \SpecialChar ~
11505 \SpecialChar ~
11506 \SpecialChar ~
11507 _asm
11508 \begin_inset LatexCommand \index{\_asm}
11509
11510 \end_inset
11511
11512
11513 \newline
11514 \SpecialChar ~
11515 \SpecialChar ~
11516 \SpecialChar ~
11517 \SpecialChar ~
11518 mov\SpecialChar ~
11519 \SpecialChar ~
11520 r2,dpl
11521 \newline
11522 ;buffer.c if( head != tail-1 )
11523 \newline
11524 \SpecialChar ~
11525 \SpecialChar ~
11526 \SpecialChar ~
11527 \SpecialChar ~
11528 mov\SpecialChar ~
11529 \SpecialChar ~
11530 a,_tail
11531 \newline
11532 \SpecialChar ~
11533 \SpecialChar ~
11534 \SpecialChar ~
11535 \SpecialChar ~
11536 dec\SpecialChar ~
11537 \SpecialChar ~
11538 a
11539 \newline
11540 \SpecialChar ~
11541 \SpecialChar ~
11542 \SpecialChar ~
11543 \SpecialChar ~
11544 mov\SpecialChar ~
11545 \SpecialChar ~
11546 r3,a
11547 \newline
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 mov\SpecialChar ~
11553 \SpecialChar ~
11554 a,_head
11555 \newline
11556 \SpecialChar ~
11557 \SpecialChar ~
11558 \SpecialChar ~
11559 \SpecialChar ~
11560 cjne a,ar3,00106$
11561 \newline
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 \SpecialChar ~
11566 ret
11567 \newline
11568 00106$:
11569 \newline
11570 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
11571 \begin_inset LatexCommand \index{Aligned array}
11572
11573 \end_inset
11574
11575
11576 \newline
11577 \SpecialChar ~
11578 \SpecialChar ~
11579 \SpecialChar ~
11580 \SpecialChar ~
11581 mov\SpecialChar ~
11582 \SpecialChar ~
11583 r3,_head
11584 \newline
11585 \SpecialChar ~
11586 \SpecialChar ~
11587 \SpecialChar ~
11588 \SpecialChar ~
11589 inc\SpecialChar ~
11590 \SpecialChar ~
11591 _head
11592 \newline
11593 \SpecialChar ~
11594 \SpecialChar ~
11595 \SpecialChar ~
11596 \SpecialChar ~
11597 mov\SpecialChar ~
11598 \SpecialChar ~
11599 dpl,r3
11600 \newline
11601 \SpecialChar ~
11602 \SpecialChar ~
11603 \SpecialChar ~
11604 \SpecialChar ~
11605 mov\SpecialChar ~
11606 \SpecialChar ~
11607 dph,#(_buf >> 8)
11608 \newline
11609 \SpecialChar ~
11610 \SpecialChar ~
11611 \SpecialChar ~
11612 \SpecialChar ~
11613 mov\SpecialChar ~
11614 \SpecialChar ~
11615 a,r2
11616 \newline
11617 \SpecialChar ~
11618 \SpecialChar ~
11619 \SpecialChar ~
11620 \SpecialChar ~
11621 movx @dptr,a
11622 \newline
11623 00103$:
11624 \newline
11625 \SpecialChar ~
11626 \SpecialChar ~
11627 \SpecialChar ~
11628 \SpecialChar ~
11629 ret
11630 \newline
11631 \SpecialChar ~
11632 \SpecialChar ~
11633 \SpecialChar ~
11634 \SpecialChar ~
11635 _endasm;
11636 \newline
11637 }
11638 \layout Standard
11639
11640 The new file buffer.c should compile with only one warning about the unreferenced
11641  function argument 'c'.
11642  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
11643  (1) and finally have:
11644 \layout Verse
11645
11646
11647 \family typewriter
11648 \size footnotesize
11649 unsigned char far at 0x7f00 buf[0x100];
11650 \newline
11651 unsigned char head,tail;
11652 \newline
11653 #define USE_ASSEMBLY (1)
11654 \newline
11655
11656 \newline
11657 #if !USE_ASSEMBLY
11658 \newline
11659
11660 \newline
11661 void to_buffer( unsigned char c )
11662 \newline
11663 {
11664 \newline
11665 \SpecialChar ~
11666 \SpecialChar ~
11667 \SpecialChar ~
11668 \SpecialChar ~
11669 if( head != tail-1 )
11670 \newline
11671 \SpecialChar ~
11672 \SpecialChar ~
11673 \SpecialChar ~
11674 \SpecialChar ~
11675 \SpecialChar ~
11676 \SpecialChar ~
11677 \SpecialChar ~
11678 \SpecialChar ~
11679 buf[ head++ ] = c;
11680 \newline
11681 }
11682 \newline
11683
11684 \newline
11685 #else
11686 \newline
11687
11688 \newline
11689 void to_buffer( unsigned char c )
11690 \newline
11691 {
11692 \newline
11693 \SpecialChar ~
11694 \SpecialChar ~
11695 \SpecialChar ~
11696 \SpecialChar ~
11697 c; // to avoid warning: unreferenced function argument
11698 \newline
11699 \SpecialChar ~
11700 \SpecialChar ~
11701 \SpecialChar ~
11702 \SpecialChar ~
11703 _asm
11704 \begin_inset LatexCommand \index{\_asm}
11705
11706 \end_inset
11707
11708
11709 \newline
11710 \SpecialChar ~
11711 \SpecialChar ~
11712 \SpecialChar ~
11713 \SpecialChar ~
11714 \SpecialChar ~
11715 \SpecialChar ~
11716 \SpecialChar ~
11717 \SpecialChar ~
11718 ; save used registers here.
11719
11720 \newline
11721 \SpecialChar ~
11722 \SpecialChar ~
11723 \SpecialChar ~
11724 \SpecialChar ~
11725 \SpecialChar ~
11726 \SpecialChar ~
11727 \SpecialChar ~
11728 \SpecialChar ~
11729 ; If we were still using r2,r3 we would have to push them here.
11730
11731 \newline
11732 ; if( head != tail-1 )
11733 \newline
11734 \SpecialChar ~
11735 \SpecialChar ~
11736 \SpecialChar ~
11737 \SpecialChar ~
11738 \SpecialChar ~
11739 \SpecialChar ~
11740 \SpecialChar ~
11741 \SpecialChar ~
11742 mov\SpecialChar ~
11743  a,_tail
11744 \newline
11745 \SpecialChar ~
11746 \SpecialChar ~
11747 \SpecialChar ~
11748 \SpecialChar ~
11749 \SpecialChar ~
11750 \SpecialChar ~
11751 \SpecialChar ~
11752 \SpecialChar ~
11753 dec\SpecialChar ~
11754  a
11755 \newline
11756 \SpecialChar ~
11757 \SpecialChar ~
11758 \SpecialChar ~
11759 \SpecialChar ~
11760 \SpecialChar ~
11761 \SpecialChar ~
11762 \SpecialChar ~
11763 \SpecialChar ~
11764 xrl\SpecialChar ~
11765  a,_head
11766 \newline
11767 \SpecialChar ~
11768 \SpecialChar ~
11769 \SpecialChar ~
11770 \SpecialChar ~
11771 \SpecialChar ~
11772 \SpecialChar ~
11773 \SpecialChar ~
11774 \SpecialChar ~
11775 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
11776 \newline
11777 \SpecialChar ~
11778 \SpecialChar ~
11779 \SpecialChar ~
11780 \SpecialChar ~
11781 \SpecialChar ~
11782 \SpecialChar ~
11783 \SpecialChar ~
11784 \SpecialChar ~
11785 jz\SpecialChar ~
11786 \SpecialChar ~
11787  t_b_end$
11788 \newline
11789 \SpecialChar ~
11790 \SpecialChar ~
11791 \SpecialChar ~
11792 \SpecialChar ~
11793 \SpecialChar ~
11794 \SpecialChar ~
11795 \SpecialChar ~
11796 \SpecialChar ~
11797 ;
11798 \newline
11799 ; buf[ head++ ] = c;
11800 \newline
11801 \SpecialChar ~
11802 \SpecialChar ~
11803 \SpecialChar ~
11804 \SpecialChar ~
11805 \SpecialChar ~
11806 \SpecialChar ~
11807 \SpecialChar ~
11808 \SpecialChar ~
11809 mov\SpecialChar ~
11810  a,dpl \SpecialChar ~
11811 \SpecialChar ~
11812 \SpecialChar ~
11813 \SpecialChar ~
11814 \SpecialChar ~
11815 \SpecialChar ~
11816 \SpecialChar ~
11817 ; dpl holds lower byte of function argument
11818 \newline
11819 \SpecialChar ~
11820 \SpecialChar ~
11821 \SpecialChar ~
11822 \SpecialChar ~
11823 \SpecialChar ~
11824 \SpecialChar ~
11825 \SpecialChar ~
11826 \SpecialChar ~
11827 mov\SpecialChar ~
11828  dpl,_head \SpecialChar ~
11829 \SpecialChar ~
11830 \SpecialChar ~
11831 ; buf is 0x100 byte aligned so head can be used directly
11832 \newline
11833 \SpecialChar ~
11834 \SpecialChar ~
11835 \SpecialChar ~
11836 \SpecialChar ~
11837 \SpecialChar ~
11838 \SpecialChar ~
11839 \SpecialChar ~
11840 \SpecialChar ~
11841 mov\SpecialChar ~
11842  dph,#(_buf>>8)
11843 \newline
11844 \SpecialChar ~
11845 \SpecialChar ~
11846 \SpecialChar ~
11847 \SpecialChar ~
11848 \SpecialChar ~
11849 \SpecialChar ~
11850 \SpecialChar ~
11851 \SpecialChar ~
11852 movx @dptr,a
11853 \newline
11854 \SpecialChar ~
11855 \SpecialChar ~
11856 \SpecialChar ~
11857 \SpecialChar ~
11858 \SpecialChar ~
11859 \SpecialChar ~
11860 \SpecialChar ~
11861 \SpecialChar ~
11862 inc \SpecialChar ~
11863 _head
11864 \newline
11865 \SpecialChar ~
11866 \SpecialChar ~
11867 \SpecialChar ~
11868 \SpecialChar ~
11869 \SpecialChar ~
11870 \SpecialChar ~
11871 \SpecialChar ~
11872 \SpecialChar ~
11873 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
11874 \newline
11875 t_b_end$:
11876 \newline
11877 \SpecialChar ~
11878 \SpecialChar ~
11879 \SpecialChar ~
11880 \SpecialChar ~
11881 \SpecialChar ~
11882 \SpecialChar ~
11883 \SpecialChar ~
11884 \SpecialChar ~
11885 ; restore used registers here
11886 \newline
11887 \SpecialChar ~
11888 \SpecialChar ~
11889 \SpecialChar ~
11890 \SpecialChar ~
11891 _endasm;
11892 \newline
11893 }
11894 \newline
11895 #endif
11896 \layout Standard
11897
11898 The inline assembler code can contain any valid code understood by the assembler
11899 , this includes any assembler directives and comment lines
11900 \begin_inset Foot
11901 collapsed false
11902
11903 \layout Standard
11904
11905 The assembler does not like some characters like ':' or ''' in comments.
11906  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
11907 \end_inset
11908
11909 .
11910  The compiler does not do any validation of the code within the
11911 \family typewriter
11912 _asm
11913 \begin_inset LatexCommand \index{\_asm}
11914
11915 \end_inset
11916
11917  ...
11918  _endasm;
11919 \family default
11920  keyword pair.
11921  Specifically it will not know which registers are used and thus register
11922  pushing/popping
11923 \begin_inset LatexCommand \index{push/pop}
11924
11925 \end_inset
11926
11927  has to be done manually.
11928
11929 \layout Standard
11930
11931 It is recommended that each assembly instruction (including labels) be placed
11932  in a separate line (as the example shows).
11933  When the -
11934 \begin_inset ERT
11935 status Collapsed
11936
11937 \layout Standard
11938
11939 \backslash
11940 /
11941 \end_inset
11942
11943 -
11944 \emph on
11945 peep-asm
11946 \begin_inset LatexCommand \index{-\/-peep-asm}
11947
11948 \end_inset
11949
11950
11951 \emph default
11952  command line option is used, the inline assembler code will be passed through
11953  the peephole optimizer
11954 \begin_inset LatexCommand \index{Peephole optimizer}
11955
11956 \end_inset
11957
11958 .
11959  There are only a few (if any) cases where this option makes sense, it might
11960  cause some unexpected changes in the inline assembler code.
11961  Please go through the peephole optimizer rules defined in file
11962 \emph on
11963 SDCCpeeph.def
11964 \emph default
11965  before using this option.
11966 \layout Subsection
11967
11968 Naked Functions
11969 \begin_inset LatexCommand \label{sub:Naked-Functions}
11970
11971 \end_inset
11972
11973
11974 \begin_inset LatexCommand \index{Naked functions}
11975
11976 \end_inset
11977
11978
11979 \layout Standard
11980
11981 A special keyword may be associated with a function declaring it as
11982 \emph on
11983 _naked
11984 \begin_inset LatexCommand \index{\_naked}
11985
11986 \end_inset
11987
11988 .
11989
11990 \emph default
11991 The
11992 \emph on
11993 _naked
11994 \emph default
11995  function modifier attribute prevents the compiler from generating prologue
11996 \begin_inset LatexCommand \index{function prologue}
11997
11998 \end_inset
11999
12000  and epilogue
12001 \begin_inset LatexCommand \index{function epilogue}
12002
12003 \end_inset
12004
12005  code for that function.
12006  This means that the user is entirely responsible for such things as saving
12007  any registers that may need to be preserved, selecting the proper register
12008  bank, generating the
12009 \emph on
12010 return
12011 \emph default
12012  instruction at the end, etc.
12013  Practically, this means that the contents of the function must be written
12014  in inline assembler.
12015  This is particularly useful for interrupt functions, which can have a large
12016  (and often unnecessary) prologue/epilogue.
12017  For example, compare the code generated by these two functions:
12018 \layout Verse
12019
12020
12021 \family typewriter
12022 volatile
12023 \begin_inset LatexCommand \index{volatile}
12024
12025 \end_inset
12026
12027  data unsigned char counter;
12028 \newline
12029
12030 \newline
12031 void simpleInterrupt(void) interrupt
12032 \begin_inset LatexCommand \index{interrupt}
12033
12034 \end_inset
12035
12036  1
12037 \newline
12038 {
12039 \newline
12040 \SpecialChar ~
12041 \SpecialChar ~
12042 \SpecialChar ~
12043 \SpecialChar ~
12044 counter++;
12045 \newline
12046 }
12047 \newline
12048
12049 \newline
12050 void nakedInterrupt(void) interrupt 2 _naked
12051 \newline
12052 {
12053 \newline
12054 \SpecialChar ~
12055 \SpecialChar ~
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 _asm
12059 \begin_inset LatexCommand \index{\_asm}
12060
12061 \end_inset
12062
12063
12064 \newline
12065 \SpecialChar ~
12066 \SpecialChar ~
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 inc\SpecialChar ~
12072 \SpecialChar ~
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 \SpecialChar ~
12076 _counter ; does not change flags, no need to save psw
12077 \newline
12078 \SpecialChar ~
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 \SpecialChar ~
12083 \SpecialChar ~
12084 reti\SpecialChar ~
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 \SpecialChar ~
12088 ; MUST explicitly include ret or reti in _naked function.
12089 \newline
12090 \SpecialChar ~
12091 \SpecialChar ~
12092 \SpecialChar ~
12093 \SpecialChar ~
12094 _endasm
12095 \begin_inset LatexCommand \index{\_endasm}
12096
12097 \end_inset
12098
12099 ;
12100 \newline
12101 }
12102 \layout Standard
12103
12104 For an 8051 target, the generated simpleInterrupt looks like:
12105 \layout Verse
12106
12107
12108 \family typewriter
12109 _simpleInterrupt:
12110 \newline
12111 \SpecialChar ~
12112 \SpecialChar ~
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 push\SpecialChar ~
12116 \SpecialChar ~
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 acc
12120 \newline
12121 \SpecialChar ~
12122 \SpecialChar ~
12123 \SpecialChar ~
12124 \SpecialChar ~
12125 push\SpecialChar ~
12126 \SpecialChar ~
12127 \SpecialChar ~
12128 \SpecialChar ~
12129 b
12130 \newline
12131 \SpecialChar ~
12132 \SpecialChar ~
12133 \SpecialChar ~
12134 \SpecialChar ~
12135 push\SpecialChar ~
12136 \SpecialChar ~
12137 \SpecialChar ~
12138 \SpecialChar ~
12139 dpl
12140 \newline
12141 \SpecialChar ~
12142 \SpecialChar ~
12143 \SpecialChar ~
12144 \SpecialChar ~
12145 push\SpecialChar ~
12146 \SpecialChar ~
12147 \SpecialChar ~
12148 \SpecialChar ~
12149 dph
12150 \newline
12151 \SpecialChar ~
12152 \SpecialChar ~
12153 \SpecialChar ~
12154 \SpecialChar ~
12155 push\SpecialChar ~
12156 \SpecialChar ~
12157 \SpecialChar ~
12158 \SpecialChar ~
12159 psw
12160 \newline
12161 \SpecialChar ~
12162 \SpecialChar ~
12163 \SpecialChar ~
12164 \SpecialChar ~
12165 mov\SpecialChar ~
12166 \SpecialChar ~
12167 \SpecialChar ~
12168 \SpecialChar ~
12169 \SpecialChar ~
12170 psw,#0x00
12171 \newline
12172 \SpecialChar ~
12173 \SpecialChar ~
12174 \SpecialChar ~
12175 \SpecialChar ~
12176 inc\SpecialChar ~
12177 \SpecialChar ~
12178 \SpecialChar ~
12179 \SpecialChar ~
12180 \SpecialChar ~
12181 _counter
12182 \newline
12183 \SpecialChar ~
12184 \SpecialChar ~
12185 \SpecialChar ~
12186 \SpecialChar ~
12187 pop\SpecialChar ~
12188 \SpecialChar ~
12189 \SpecialChar ~
12190 \SpecialChar ~
12191 \SpecialChar ~
12192 psw
12193 \newline
12194 \SpecialChar ~
12195 \SpecialChar ~
12196 \SpecialChar ~
12197 \SpecialChar ~
12198 pop\SpecialChar ~
12199 \SpecialChar ~
12200 \SpecialChar ~
12201 \SpecialChar ~
12202 \SpecialChar ~
12203 dph
12204 \newline
12205 \SpecialChar ~
12206 \SpecialChar ~
12207 \SpecialChar ~
12208 \SpecialChar ~
12209 pop\SpecialChar ~
12210 \SpecialChar ~
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 \SpecialChar ~
12214 dpl
12215 \newline
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 \SpecialChar ~
12220 pop\SpecialChar ~
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 \SpecialChar ~
12224 \SpecialChar ~
12225 b
12226 \newline
12227 \SpecialChar ~
12228 \SpecialChar ~
12229 \SpecialChar ~
12230 \SpecialChar ~
12231 pop\SpecialChar ~
12232 \SpecialChar ~
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 acc
12237 \newline
12238 \SpecialChar ~
12239 \SpecialChar ~
12240 \SpecialChar ~
12241 \SpecialChar ~
12242 reti
12243 \layout Standard
12244
12245 whereas nakedInterrupt looks like:
12246 \layout Verse
12247
12248
12249 \family typewriter
12250 _nakedInterrupt:
12251 \newline
12252 \SpecialChar ~
12253 \SpecialChar ~
12254 \SpecialChar ~
12255 \SpecialChar ~
12256 inc\SpecialChar ~
12257 \SpecialChar ~
12258 \SpecialChar ~
12259 \SpecialChar ~
12260 _counter ; does not change flags, no need to save psw
12261 \newline
12262 \SpecialChar ~
12263 \SpecialChar ~
12264 \SpecialChar ~
12265 \SpecialChar ~
12266 reti\SpecialChar ~
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 \SpecialChar ~
12273 \SpecialChar ~
12274 \SpecialChar ~
12275 \SpecialChar ~
12276 \SpecialChar ~
12277 \SpecialChar ~
12278 ; MUST explicitly include ret or reti in _naked function
12279 \layout Standard
12280
12281 The related directive #pragma exclude
12282 \begin_inset LatexCommand \index{\#pragma exclude}
12283
12284 \end_inset
12285
12286  allows a more fine grained control over pushing & popping
12287 \begin_inset LatexCommand \index{push/pop}
12288
12289 \end_inset
12290
12291  the registers.
12292 \layout Standard
12293
12294 While there is nothing preventing you from writing C code inside a
12295 \family typewriter
12296 _naked
12297 \family default
12298  function, there are many ways to shoot yourself in the foot doing this,
12299  and it is recommended that you stick to inline assembler.
12300 \layout Subsection
12301
12302 Use of Labels within Inline Assembler
12303 \layout Standard
12304
12305 SDCC allows the use of in-line assembler with a few restrictions regarding
12306  labels.
12307  In older versions of the compiler all labels defined within inline assembler
12308  code
12309 \emph on
12310 had to be
12311 \emph default
12312  of the form
12313 \emph on
12314 nnnnn$
12315 \emph default
12316  where nnnn is a number less than 100 (which implies a limit of utmost 100
12317  inline assembler labels
12318 \emph on
12319 per function
12320 \emph default
12321 \noun on
12322 )
12323 \noun default
12324 .
12325
12326 \layout Verse
12327
12328
12329 \family typewriter
12330 _asm
12331 \begin_inset LatexCommand \index{\_asm}
12332
12333 \end_inset
12334
12335
12336 \newline
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 \SpecialChar ~
12340 \SpecialChar ~
12341 mov\SpecialChar ~
12342 \SpecialChar ~
12343 \SpecialChar ~
12344 \SpecialChar ~
12345 \SpecialChar ~
12346 b,#10
12347 \newline
12348 00001$:
12349 \newline
12350 \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 \SpecialChar ~
12354 djnz\SpecialChar ~
12355 \SpecialChar ~
12356 \SpecialChar ~
12357 \SpecialChar ~
12358 b,00001$
12359 \newline
12360 _endasm
12361 \begin_inset LatexCommand \index{\_endasm}
12362
12363 \end_inset
12364
12365  ;
12366 \layout Standard
12367
12368 Inline assembler code cannot reference any C-Labels, however it can reference
12369  labels
12370 \begin_inset LatexCommand \index{Labels}
12371
12372 \end_inset
12373
12374  defined by the inline assembler, e.g.:
12375 \layout Verse
12376
12377
12378 \family typewriter
12379 foo() {
12380 \newline
12381 \SpecialChar ~
12382 \SpecialChar ~
12383 \SpecialChar ~
12384 \SpecialChar ~
12385 /* some c code */
12386 \newline
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 _asm
12392 \newline
12393 \SpecialChar ~
12394 \SpecialChar ~
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 ; some assembler code
12400 \newline
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 \SpecialChar ~
12404 \SpecialChar ~
12405 \SpecialChar ~
12406 \SpecialChar ~
12407 ljmp $0003
12408 \newline
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 _endasm;
12414 \newline
12415 \SpecialChar ~
12416 \SpecialChar ~
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 /* some more c code */
12420 \newline
12421 clabel:\SpecialChar ~
12422 \SpecialChar ~
12423 /* inline assembler cannot reference this label */
12424 \newline
12425 \SpecialChar ~
12426 \SpecialChar ~
12427 \SpecialChar ~
12428 \SpecialChar ~
12429 _asm
12430 \newline
12431 \SpecialChar ~
12432 \SpecialChar ~
12433 \SpecialChar ~
12434 \SpecialChar ~
12435 $0003: ;label (can be referenced by inline assembler only)
12436 \newline
12437 \SpecialChar ~
12438 \SpecialChar ~
12439 \SpecialChar ~
12440 \SpecialChar ~
12441 _endasm ;
12442 \newline
12443 \SpecialChar ~
12444 \SpecialChar ~
12445 \SpecialChar ~
12446 \SpecialChar ~
12447 /* some more c code */
12448 \newline
12449 }
12450 \layout Standard
12451
12452 In other words inline assembly code can access labels defined in inline
12453  assembly within the scope of the function.
12454  The same goes the other way, i.e.
12455  labels defines in inline assembly can not be accessed by C statements.
12456 \layout Section
12457
12458 Interfacing with Assembler Code
12459 \begin_inset LatexCommand \index{Assembler routines}
12460
12461 \end_inset
12462
12463
12464 \layout Subsection
12465
12466 Global Registers used for Parameter Passing
12467 \begin_inset LatexCommand \index{Parameter passing}
12468
12469 \end_inset
12470
12471
12472 \layout Standard
12473
12474 The compiler always uses the global registers
12475 \emph on
12476 DPL, DPH
12477 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12478
12479 \end_inset
12480
12481
12482 \begin_inset LatexCommand \index{DPTR}
12483
12484 \end_inset
12485
12486 , B
12487 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
12488
12489 \end_inset
12490
12491
12492 \emph default
12493 and
12494 \emph on
12495  ACC
12496 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
12497
12498 \end_inset
12499
12500
12501 \emph default
12502  to pass the first parameter to a routine.
12503  The second parameter onwards is either allocated on the stack (for reentrant
12504  routines or if -
12505 \begin_inset ERT
12506 status Collapsed
12507
12508 \layout Standard
12509
12510 \backslash
12511 /
12512 \end_inset
12513
12514 -stack-auto is used) or in data / xdata memory (depending on the memory
12515  model).
12516
12517 \layout Subsection
12518
12519 Assembler Routine (non-reentrant)
12520 \layout Standard
12521
12522 In the following example
12523 \begin_inset LatexCommand \index{reentrant}
12524
12525 \end_inset
12526
12527
12528 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
12529
12530 \end_inset
12531
12532  the function c_func calls an assembler routine asm_func, which takes two
12533  parameters
12534 \begin_inset LatexCommand \index{function parameter}
12535
12536 \end_inset
12537
12538 .
12539 \layout Verse
12540
12541
12542 \family typewriter
12543 extern int asm_func(unsigned char, unsigned char);
12544 \newline
12545
12546 \newline
12547 int c_func (unsigned char i, unsigned char j)
12548 \newline
12549 {
12550 \newline
12551 \SpecialChar ~
12552 \SpecialChar ~
12553 \SpecialChar ~
12554 \SpecialChar ~
12555 return asm_func(i,j);
12556 \newline
12557 }
12558 \newline
12559
12560 \newline
12561 int main()
12562 \newline
12563 {
12564 \newline
12565 \SpecialChar ~
12566 \SpecialChar ~
12567 \SpecialChar ~
12568 \SpecialChar ~
12569 return c_func(10,9);
12570 \newline
12571 }
12572 \layout Standard
12573
12574 The corresponding assembler function is:
12575 \layout Verse
12576
12577
12578 \family typewriter
12579 .globl _asm_func_PARM_2
12580 \newline
12581 \SpecialChar ~
12582 \SpecialChar ~
12583 \SpecialChar ~
12584 \SpecialChar ~
12585 \SpecialChar ~
12586 \SpecialChar ~
12587 \SpecialChar ~
12588 \SpecialChar ~
12589 .globl _asm_func
12590 \newline
12591 \SpecialChar ~
12592 \SpecialChar ~
12593 \SpecialChar ~
12594 \SpecialChar ~
12595 \SpecialChar ~
12596 \SpecialChar ~
12597 \SpecialChar ~
12598 \SpecialChar ~
12599 .area OSEG
12600 \newline
12601 _asm_func_PARM_2:
12602 \newline
12603 \SpecialChar ~
12604 \SpecialChar ~
12605 \SpecialChar ~
12606 \SpecialChar ~
12607 \SpecialChar ~
12608 \SpecialChar ~
12609 \SpecialChar ~
12610 \SpecialChar ~
12611 .ds    1
12612 \newline
12613 \SpecialChar ~
12614 \SpecialChar ~
12615 \SpecialChar ~
12616 \SpecialChar ~
12617 \SpecialChar ~
12618 \SpecialChar ~
12619 \SpecialChar ~
12620 \SpecialChar ~
12621 .area CSEG
12622 \newline
12623 _asm_func:
12624 \newline
12625 \SpecialChar ~
12626 \SpecialChar ~
12627 \SpecialChar ~
12628 \SpecialChar ~
12629 \SpecialChar ~
12630 \SpecialChar ~
12631 \SpecialChar ~
12632 \SpecialChar ~
12633 mov\SpecialChar ~
12634 \SpecialChar ~
12635 \SpecialChar ~
12636 \SpecialChar ~
12637 a,dpl
12638 \newline
12639 \SpecialChar ~
12640 \SpecialChar ~
12641 \SpecialChar ~
12642 \SpecialChar ~
12643 \SpecialChar ~
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 \SpecialChar ~
12647 add\SpecialChar ~
12648 \SpecialChar ~
12649 \SpecialChar ~
12650 \SpecialChar ~
12651 a,_asm_func_PARM_2
12652 \newline
12653 \SpecialChar ~
12654 \SpecialChar ~
12655 \SpecialChar ~
12656 \SpecialChar ~
12657 \SpecialChar ~
12658 \SpecialChar ~
12659 \SpecialChar ~
12660 \SpecialChar ~
12661 mov\SpecialChar ~
12662 \SpecialChar ~
12663 \SpecialChar ~
12664 \SpecialChar ~
12665 dpl,a
12666 \newline
12667 \SpecialChar ~
12668 \SpecialChar ~
12669 \SpecialChar ~
12670 \SpecialChar ~
12671 \SpecialChar ~
12672 \SpecialChar ~
12673 \SpecialChar ~
12674 \SpecialChar ~
12675 mov\SpecialChar ~
12676 \SpecialChar ~
12677 \SpecialChar ~
12678 \SpecialChar ~
12679 dph
12680 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12681
12682 \end_inset
12683
12684 ,#0x00
12685 \newline
12686 \SpecialChar ~
12687 \SpecialChar ~
12688 \SpecialChar ~
12689 \SpecialChar ~
12690 \SpecialChar ~
12691 \SpecialChar ~
12692 \SpecialChar ~
12693 \SpecialChar ~
12694 ret
12695 \layout Standard
12696
12697 Note here that the return values
12698 \begin_inset LatexCommand \index{return value}
12699
12700 \end_inset
12701
12702  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
12703  two byte values.
12704  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12705 b' & 'acc' for four byte values.
12706 \layout Standard
12707
12708 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12709  the parameter number starting from 1, and counting from the left.
12710  The first parameter is passed in
12711 \begin_inset Quotes eld
12712 \end_inset
12713
12714 dpl
12715 \begin_inset Quotes erd
12716 \end_inset
12717
12718  for a one byte parameter,
12719 \begin_inset Quotes eld
12720 \end_inset
12721
12722 dptr
12723 \begin_inset Quotes erd
12724 \end_inset
12725
12726  for two bytes,
12727 \begin_inset Quotes eld
12728 \end_inset
12729
12730 b,dptr
12731 \begin_inset Quotes erd
12732 \end_inset
12733
12734  for three bytes and
12735 \begin_inset Quotes eld
12736 \end_inset
12737
12738 acc,b,dptr
12739 \begin_inset Quotes erd
12740 \end_inset
12741
12742  for a four bytes parameter.
12743  The variable name for the second parameter will be _<function_name>_PARM_2.
12744 \newline
12745
12746 \newline
12747 Assemble the assembler routine with the following command:
12748 \newline
12749
12750 \newline
12751
12752 \family sans
12753 \series bold
12754 asx8051 -losg asmfunc.asm
12755 \newline
12756
12757 \newline
12758
12759 \family default
12760 \series default
12761 Then compile and link the assembler routine to the C source file with the
12762  following command:
12763 \newline
12764
12765 \newline
12766
12767 \family sans
12768 \series bold
12769 sdcc cfunc.c asmfunc.rel
12770 \layout Subsection
12771
12772 Assembler Routine (reentrant)
12773 \layout Standard
12774
12775 In this case
12776 \begin_inset LatexCommand \index{reentrant}
12777
12778 \end_inset
12779
12780
12781 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12782
12783 \end_inset
12784
12785  the second parameter
12786 \begin_inset LatexCommand \index{function parameter}
12787
12788 \end_inset
12789
12790  onwards will be passed on the stack, the parameters are pushed from right
12791  to left i.e.
12792  after the call the leftmost parameter will be on the top of the stack.
12793  Here is an example:
12794 \layout Verse
12795
12796
12797 \family typewriter
12798 extern int asm_func(unsigned char, unsigned char);
12799 \newline
12800
12801 \newline
12802 int c_func (unsigned char i, unsigned char j) reentrant
12803 \newline
12804 {
12805 \newline
12806 \SpecialChar ~
12807 \SpecialChar ~
12808 \SpecialChar ~
12809 \SpecialChar ~
12810 return asm_func(i,j);
12811 \newline
12812 }
12813 \newline
12814
12815 \newline
12816 int main()
12817 \newline
12818 {
12819 \newline
12820 \SpecialChar ~
12821 \SpecialChar ~
12822 \SpecialChar ~
12823 \SpecialChar ~
12824 return c_func(10,9);
12825 \newline
12826 }
12827 \layout Standard
12828
12829 The corresponding assembler routine is:
12830 \layout Verse
12831
12832
12833 \family typewriter
12834 .globl _asm_func
12835 \newline
12836 _asm_func:
12837 \newline
12838 \SpecialChar ~
12839 \SpecialChar ~
12840 \SpecialChar ~
12841 \SpecialChar ~
12842 push  _bp
12843 \newline
12844 \SpecialChar ~
12845 \SpecialChar ~
12846 \SpecialChar ~
12847 \SpecialChar ~
12848 mov _bp,sp
12849 \newline
12850 \SpecialChar ~
12851 \SpecialChar ~
12852 \SpecialChar ~
12853 \SpecialChar ~
12854 mov r2,dpl
12855 \newline
12856 \SpecialChar ~
12857 \SpecialChar ~
12858 \SpecialChar ~
12859 \SpecialChar ~
12860 mov a,_bp
12861 \newline
12862 \SpecialChar ~
12863 \SpecialChar ~
12864 \SpecialChar ~
12865 \SpecialChar ~
12866 add a,#0xfd
12867 \newline
12868 \SpecialChar ~
12869 \SpecialChar ~
12870 \SpecialChar ~
12871 \SpecialChar ~
12872 mov r0,a
12873 \newline
12874 \SpecialChar ~
12875 \SpecialChar ~
12876 \SpecialChar ~
12877 \SpecialChar ~
12878 add  a,#0xfc ;?
12879 \newline
12880 \SpecialChar ~
12881 \SpecialChar ~
12882 \SpecialChar ~
12883 \SpecialChar ~
12884 mov  r1,a
12885 \newline
12886 \SpecialChar ~
12887 \SpecialChar ~
12888 \SpecialChar ~
12889 \SpecialChar ~
12890 mov  a,@r0
12891 \newline
12892 \SpecialChar ~
12893 \SpecialChar ~
12894 \SpecialChar ~
12895 \SpecialChar ~
12896 add  a,r2 ;?
12897 \newline
12898 \SpecialChar ~
12899 \SpecialChar ~
12900 \SpecialChar ~
12901 \SpecialChar ~
12902 mov  dpl,a
12903 \newline
12904 \SpecialChar ~
12905 \SpecialChar ~
12906 \SpecialChar ~
12907 \SpecialChar ~
12908 mov  dph,#0x00
12909 \newline
12910 \SpecialChar ~
12911 \SpecialChar ~
12912 \SpecialChar ~
12913 \SpecialChar ~
12914 mov  sp,_bp
12915 \newline
12916 \SpecialChar ~
12917 \SpecialChar ~
12918 \SpecialChar ~
12919 \SpecialChar ~
12920 pop  _bp
12921 \newline
12922 \SpecialChar ~
12923 \SpecialChar ~
12924 \SpecialChar ~
12925 \SpecialChar ~
12926 ret
12927 \layout Standard
12928
12929 The compiling and linking procedure remains the same, however note the extra
12930  entry & exit linkage required for the assembler code, _bp is the stack
12931  frame pointer and is used to compute the offset into the stack for parameters
12932  and local variables.
12933 \layout Section
12934
12935 int (16 bit)
12936 \begin_inset LatexCommand \index{int (16 bit)}
12937
12938 \end_inset
12939
12940  and long (32 bit)
12941 \begin_inset LatexCommand \index{long (32 bit)}
12942
12943 \end_inset
12944
12945  Support
12946 \layout Standard
12947
12948 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
12949  multiplication and modulus operations are implemented by support routines.
12950  These support routines are all developed in ANSI-C to facilitate porting
12951  to other MCUs, although some model specific assembler optimizations are
12952  used.
12953  The following files contain the described routines, all of them can be
12954  found in <installdir>/share/sdcc/lib.
12955 \newline
12956
12957 \layout Standard
12958 \align center
12959
12960 \begin_inset  Tabular
12961 <lyxtabular version="3" rows="11" columns="2">
12962 <features>
12963 <column alignment="center" valignment="top" leftline="true" width="0">
12964 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12965 <row topline="true" bottomline="true">
12966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12967 \begin_inset Text
12968
12969 \layout Standard
12970
12971
12972 \series bold
12973 Function
12974 \end_inset
12975 </cell>
12976 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12977 \begin_inset Text
12978
12979 \layout Standard
12980
12981
12982 \series bold
12983 Description
12984 \end_inset
12985 </cell>
12986 </row>
12987 <row topline="true">
12988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12989 \begin_inset Text
12990
12991 \layout Standard
12992
12993 _mulint.c
12994 \end_inset
12995 </cell>
12996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12997 \begin_inset Text
12998
12999 \layout Standard
13000
13001 16 bit multiplication
13002 \end_inset
13003 </cell>
13004 </row>
13005 <row topline="true">
13006 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13007 \begin_inset Text
13008
13009 \layout Standard
13010
13011 _divsint.c
13012 \end_inset
13013 </cell>
13014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13015 \begin_inset Text
13016
13017 \layout Standard
13018
13019  signed 16 bit division (calls _divuint)
13020 \end_inset
13021 </cell>
13022 </row>
13023 <row topline="true">
13024 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13025 \begin_inset Text
13026
13027 \layout Standard
13028
13029 _divuint.c
13030 \end_inset
13031 </cell>
13032 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13033 \begin_inset Text
13034
13035 \layout Standard
13036
13037  unsigned 16 bit division
13038 \end_inset
13039 </cell>
13040 </row>
13041 <row topline="true">
13042 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13043 \begin_inset Text
13044
13045 \layout Standard
13046
13047 _modsint.c
13048 \end_inset
13049 </cell>
13050 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13051 \begin_inset Text
13052
13053 \layout Standard
13054
13055 signed 16 bit modulus (calls _moduint)
13056 \end_inset
13057 </cell>
13058 </row>
13059 <row topline="true">
13060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13061 \begin_inset Text
13062
13063 \layout Standard
13064
13065 _moduint.c
13066 \end_inset
13067 </cell>
13068 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13069 \begin_inset Text
13070
13071 \layout Standard
13072
13073 unsigned 16 bit modulus
13074 \end_inset
13075 </cell>
13076 </row>
13077 <row topline="true">
13078 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13079 \begin_inset Text
13080
13081 \layout Standard
13082
13083 _mullong.c
13084 \end_inset
13085 </cell>
13086 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13087 \begin_inset Text
13088
13089 \layout Standard
13090
13091 32 bit multiplication
13092 \end_inset
13093 </cell>
13094 </row>
13095 <row topline="true">
13096 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13097 \begin_inset Text
13098
13099 \layout Standard
13100
13101 _divslong.c
13102 \end_inset
13103 </cell>
13104 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13105 \begin_inset Text
13106
13107 \layout Standard
13108
13109  signed 32 division (calls _divulong)
13110 \end_inset
13111 </cell>
13112 </row>
13113 <row topline="true">
13114 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13115 \begin_inset Text
13116
13117 \layout Standard
13118
13119 _divulong.c
13120 \end_inset
13121 </cell>
13122 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13123 \begin_inset Text
13124
13125 \layout Standard
13126
13127 unsigned 32 division
13128 \end_inset
13129 </cell>
13130 </row>
13131 <row topline="true">
13132 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13133 \begin_inset Text
13134
13135 \layout Standard
13136
13137 _modslong.c
13138 \end_inset
13139 </cell>
13140 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13141 \begin_inset Text
13142
13143 \layout Standard
13144
13145  signed 32 bit modulus (calls _modulong)
13146 \end_inset
13147 </cell>
13148 </row>
13149 <row topline="true" bottomline="true">
13150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13151 \begin_inset Text
13152
13153 \layout Standard
13154
13155 _modulong.c
13156 \end_inset
13157 </cell>
13158 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13159 \begin_inset Text
13160
13161 \layout Standard
13162
13163 unsigned 32 bit modulus
13164 \end_inset
13165 </cell>
13166 </row>
13167 </lyxtabular>
13168
13169 \end_inset
13170
13171
13172 \newline
13173
13174 \layout Standard
13175
13176 Since they are compiled as
13177 \emph on
13178 non-reentrant
13179 \emph default
13180
13181 \begin_inset LatexCommand \index{reentrant}
13182
13183 \end_inset
13184
13185 , interrupt
13186 \begin_inset LatexCommand \index{interrupt}
13187
13188 \end_inset
13189
13190  service routines should not do any of the above operations.
13191  If this is unavoidable then the above routines will need to be compiled
13192  with the
13193 \emph on
13194 -
13195 \begin_inset ERT
13196 status Collapsed
13197
13198 \layout Standard
13199
13200 \backslash
13201 /
13202 \end_inset
13203
13204 -stack-auto
13205 \begin_inset LatexCommand \index{-\/-stack-auto}
13206
13207 \end_inset
13208
13209
13210 \emph default
13211  option, after which the source program will have to be compiled with
13212 \emph on
13213 -
13214 \begin_inset ERT
13215 status Collapsed
13216
13217 \layout Standard
13218
13219 \backslash
13220 /
13221 \end_inset
13222
13223 -int-long-reent
13224 \begin_inset LatexCommand \index{-\/-int-long-reent}
13225
13226 \end_inset
13227
13228
13229 \emph default
13230  option.
13231  Notice that you don't have to call these routines directly.
13232  The compiler will use them automatically every time an integer operation
13233  is required.
13234 \layout Section
13235
13236 Floating Point Support
13237 \begin_inset LatexCommand \index{Floating point support}
13238
13239 \end_inset
13240
13241
13242 \layout Standard
13243
13244 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13245  floating point support routines are derived from gcc's floatlib.c and consist
13246  of the following routines:
13247 \newline
13248
13249 \layout Standard
13250 \align center
13251
13252 \size footnotesize
13253
13254 \begin_inset  Tabular
13255 <lyxtabular version="3" rows="17" columns="2">
13256 <features>
13257 <column alignment="center" valignment="top" leftline="true" width="0">
13258 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13259 <row topline="true" bottomline="true">
13260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13261 \begin_inset Text
13262
13263 \layout Standard
13264
13265
13266 \family roman
13267 \series medium
13268 \shape up
13269 \size normal
13270 \emph off
13271 \bar no
13272 \noun off
13273 \color none
13274 Function
13275 \end_inset
13276 </cell>
13277 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13278 \begin_inset Text
13279
13280 \layout Standard
13281
13282 Description
13283 \end_inset
13284 </cell>
13285 </row>
13286 <row topline="true">
13287 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13288 \begin_inset Text
13289
13290 \layout Standard
13291
13292
13293 \family roman
13294 \series medium
13295 \shape up
13296 \size normal
13297 \emph off
13298 \bar no
13299 \noun off
13300 \color none
13301 _fsadd.c
13302 \end_inset
13303 </cell>
13304 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13305 \begin_inset Text
13306
13307 \layout Standard
13308
13309
13310 \family roman
13311 \series medium
13312 \shape up
13313 \size normal
13314 \emph off
13315 \bar no
13316 \noun off
13317 \color none
13318 add floating point numbers
13319 \end_inset
13320 </cell>
13321 </row>
13322 <row topline="true">
13323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13324 \begin_inset Text
13325
13326 \layout Standard
13327
13328
13329 \family roman
13330 \series medium
13331 \shape up
13332 \size normal
13333 \emph off
13334 \bar no
13335 \noun off
13336 \color none
13337 _fssub.c
13338 \end_inset
13339 </cell>
13340 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13341 \begin_inset Text
13342
13343 \layout Standard
13344
13345
13346 \family roman
13347 \series medium
13348 \shape up
13349 \size normal
13350 \emph off
13351 \bar no
13352 \noun off
13353 \color none
13354 subtract floating point numbers
13355 \end_inset
13356 </cell>
13357 </row>
13358 <row topline="true">
13359 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13360 \begin_inset Text
13361
13362 \layout Standard
13363
13364
13365 \family roman
13366 \series medium
13367 \shape up
13368 \size normal
13369 \emph off
13370 \bar no
13371 \noun off
13372 \color none
13373 _fsdiv.c
13374 \end_inset
13375 </cell>
13376 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13377 \begin_inset Text
13378
13379 \layout Standard
13380
13381
13382 \family roman
13383 \series medium
13384 \shape up
13385 \size normal
13386 \emph off
13387 \bar no
13388 \noun off
13389 \color none
13390 divide floating point numbers
13391 \end_inset
13392 </cell>
13393 </row>
13394 <row topline="true">
13395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13396 \begin_inset Text
13397
13398 \layout Standard
13399
13400
13401 \family roman
13402 \series medium
13403 \shape up
13404 \size normal
13405 \emph off
13406 \bar no
13407 \noun off
13408 \color none
13409 _fsmul.c
13410 \end_inset
13411 </cell>
13412 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13413 \begin_inset Text
13414
13415 \layout Standard
13416
13417
13418 \family roman
13419 \series medium
13420 \shape up
13421 \size normal
13422 \emph off
13423 \bar no
13424 \noun off
13425 \color none
13426 multiply floating point numbers
13427 \end_inset
13428 </cell>
13429 </row>
13430 <row topline="true">
13431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13432 \begin_inset Text
13433
13434 \layout Standard
13435
13436
13437 \family roman
13438 \series medium
13439 \shape up
13440 \size normal
13441 \emph off
13442 \bar no
13443 \noun off
13444 \color none
13445 _fs2uchar.c
13446 \end_inset
13447 </cell>
13448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13449 \begin_inset Text
13450
13451 \layout Standard
13452
13453
13454 \family roman
13455 \series medium
13456 \shape up
13457 \size normal
13458 \emph off
13459 \bar no
13460 \noun off
13461 \color none
13462 convert floating point to unsigned char
13463 \end_inset
13464 </cell>
13465 </row>
13466 <row topline="true">
13467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13468 \begin_inset Text
13469
13470 \layout Standard
13471
13472
13473 \family roman
13474 \series medium
13475 \shape up
13476 \size normal
13477 \emph off
13478 \bar no
13479 \noun off
13480 \color none
13481 _fs2char.c
13482 \end_inset
13483 </cell>
13484 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13485 \begin_inset Text
13486
13487 \layout Standard
13488
13489
13490 \family roman
13491 \series medium
13492 \shape up
13493 \size normal
13494 \emph off
13495 \bar no
13496 \noun off
13497 \color none
13498 convert floating point to signed char
13499 \end_inset
13500 </cell>
13501 </row>
13502 <row topline="true">
13503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13504 \begin_inset Text
13505
13506 \layout Standard
13507
13508
13509 \family roman
13510 \series medium
13511 \shape up
13512 \size normal
13513 \emph off
13514 \bar no
13515 \noun off
13516 \color none
13517 _fs2uint.c
13518 \end_inset
13519 </cell>
13520 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13521 \begin_inset Text
13522
13523 \layout Standard
13524
13525
13526 \family roman
13527 \series medium
13528 \shape up
13529 \size normal
13530 \emph off
13531 \bar no
13532 \noun off
13533 \color none
13534 convert floating point to unsigned int
13535 \end_inset
13536 </cell>
13537 </row>
13538 <row topline="true">
13539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13540 \begin_inset Text
13541
13542 \layout Standard
13543
13544
13545 \family roman
13546 \series medium
13547 \shape up
13548 \size normal
13549 \emph off
13550 \bar no
13551 \noun off
13552 \color none
13553 _fs2int.c
13554 \end_inset
13555 </cell>
13556 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13557 \begin_inset Text
13558
13559 \layout Standard
13560
13561
13562 \family roman
13563 \series medium
13564 \shape up
13565 \size normal
13566 \emph off
13567 \bar no
13568 \noun off
13569 \color none
13570 convert floating point to signed int
13571 \end_inset
13572 </cell>
13573 </row>
13574 <row topline="true">
13575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13576 \begin_inset Text
13577
13578 \layout Standard
13579
13580
13581 \family roman
13582 \series medium
13583 \shape up
13584 \size normal
13585 \emph off
13586 \bar no
13587 \noun off
13588 \color none
13589 _fs2ulong.
13590 \family default
13591 \series default
13592 \shape default
13593 \size default
13594 \emph default
13595 \bar default
13596 \noun default
13597 \color default
13598 c
13599 \end_inset
13600 </cell>
13601 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13602 \begin_inset Text
13603
13604 \layout Standard
13605
13606
13607 \family roman
13608 \series medium
13609 \shape up
13610 \size normal
13611 \emph off
13612 \bar no
13613 \noun off
13614 \color none
13615 convert floating point to unsigned long
13616 \end_inset
13617 </cell>
13618 </row>
13619 <row topline="true">
13620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13621 \begin_inset Text
13622
13623 \layout Standard
13624
13625
13626 \family roman
13627 \series medium
13628 \shape up
13629 \size normal
13630 \emph off
13631 \bar no
13632 \noun off
13633 \color none
13634 _fs2long.c
13635 \end_inset
13636 </cell>
13637 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13638 \begin_inset Text
13639
13640 \layout Standard
13641
13642
13643 \family roman
13644 \series medium
13645 \shape up
13646 \size normal
13647 \emph off
13648 \bar no
13649 \noun off
13650 \color none
13651 convert floating point to signed long
13652 \end_inset
13653 </cell>
13654 </row>
13655 <row topline="true">
13656 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13657 \begin_inset Text
13658
13659 \layout Standard
13660
13661
13662 \family roman
13663 \series medium
13664 \shape up
13665 \size normal
13666 \emph off
13667 \bar no
13668 \noun off
13669 \color none
13670 _uchar2fs.c
13671 \end_inset
13672 </cell>
13673 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13674 \begin_inset Text
13675
13676 \layout Standard
13677
13678
13679 \family roman
13680 \series medium
13681 \shape up
13682 \size normal
13683 \emph off
13684 \bar no
13685 \noun off
13686 \color none
13687 convert unsigned char to floating point
13688 \end_inset
13689 </cell>
13690 </row>
13691 <row topline="true">
13692 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13693 \begin_inset Text
13694
13695 \layout Standard
13696
13697
13698 \family roman
13699 \series medium
13700 \shape up
13701 \size normal
13702 \emph off
13703 \bar no
13704 \noun off
13705 \color none
13706 _char2fs.c
13707 \end_inset
13708 </cell>
13709 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13710 \begin_inset Text
13711
13712 \layout Standard
13713
13714
13715 \family roman
13716 \series medium
13717 \shape up
13718 \size normal
13719 \emph off
13720 \bar no
13721 \noun off
13722 \color none
13723 convert char to floating point number
13724 \end_inset
13725 </cell>
13726 </row>
13727 <row topline="true">
13728 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13729 \begin_inset Text
13730
13731 \layout Standard
13732
13733
13734 \family roman
13735 \series medium
13736 \shape up
13737 \size normal
13738 \emph off
13739 \bar no
13740 \noun off
13741 \color none
13742 _uint2fs.c
13743 \end_inset
13744 </cell>
13745 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13746 \begin_inset Text
13747
13748 \layout Standard
13749
13750
13751 \family roman
13752 \series medium
13753 \shape up
13754 \size normal
13755 \emph off
13756 \bar no
13757 \noun off
13758 \color none
13759 convert unsigned int to floating point
13760 \end_inset
13761 </cell>
13762 </row>
13763 <row topline="true">
13764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13765 \begin_inset Text
13766
13767 \layout Standard
13768
13769
13770 \family roman
13771 \series medium
13772 \shape up
13773 \size normal
13774 \emph off
13775 \bar no
13776 \noun off
13777 \color none
13778 _int2fs.c
13779 \end_inset
13780 </cell>
13781 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13782 \begin_inset Text
13783
13784 \layout Standard
13785
13786
13787 \family roman
13788 \series medium
13789 \shape up
13790 \size normal
13791 \emph off
13792 \bar no
13793 \noun off
13794 \color none
13795 convert int to floating point numbers
13796 \end_inset
13797 </cell>
13798 </row>
13799 <row topline="true">
13800 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13801 \begin_inset Text
13802
13803 \layout Standard
13804
13805
13806 \family roman
13807 \series medium
13808 \shape up
13809 \size normal
13810 \emph off
13811 \bar no
13812 \noun off
13813 \color none
13814 _ulong2fs.c
13815 \end_inset
13816 </cell>
13817 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13818 \begin_inset Text
13819
13820 \layout Standard
13821
13822
13823 \family roman
13824 \series medium
13825 \shape up
13826 \size normal
13827 \emph off
13828 \bar no
13829 \noun off
13830 \color none
13831 convert unsigned long to floating point number
13832 \end_inset
13833 </cell>
13834 </row>
13835 <row topline="true" bottomline="true">
13836 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13837 \begin_inset Text
13838
13839 \layout Standard
13840
13841
13842 \family roman
13843 \series medium
13844 \shape up
13845 \size normal
13846 \emph off
13847 \bar no
13848 \noun off
13849 \color none
13850 _long2fs.c
13851 \end_inset
13852 </cell>
13853 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13854 \begin_inset Text
13855
13856 \layout Standard
13857
13858
13859 \family roman
13860 \series medium
13861 \shape up
13862 \size normal
13863 \emph off
13864 \bar no
13865 \noun off
13866 \color none
13867 convert long to floating point number
13868 \end_inset
13869 </cell>
13870 </row>
13871 </lyxtabular>
13872
13873 \end_inset
13874
13875
13876 \newline
13877
13878 \layout Standard
13879
13880 These support routines are developed in ANSI-C so there is room for space
13881  and speed improvement.
13882  Note if all these routines are used simultaneously the data space might
13883  overflow.
13884  For serious floating point usage it is recommended that the large model
13885  be used.
13886  Also notice that you don't have to call this routines directly.
13887  The compiler will use them automatically every time a floating point operation
13888  is required.
13889 \layout Section
13890
13891 Library Routines
13892 \begin_inset LatexCommand \index{Libraries}
13893
13894 \end_inset
13895
13896
13897 \layout Standard
13898
13899
13900 \emph on
13901 <pending: this is messy and incomplete - a little more information is in
13902  sdcc/doc/libdoc.txt
13903 \emph default
13904  >
13905 \layout Subsection
13906
13907 Compiler support routines (_gptrget, _mulint etc.)
13908 \layout Subsection
13909
13910 Stdclib functions (puts, printf, strcat etc.)
13911 \layout Subsubsection
13912
13913 <stdio.h>
13914 \layout Standard
13915
13916
13917 \begin_inset LatexCommand \index{<stdio.h>}
13918
13919 \end_inset
13920
13921 As usual on embedded systems you have to provide your own
13922 \family typewriter
13923 getchar()
13924 \begin_inset LatexCommand \index{getchar()}
13925
13926 \end_inset
13927
13928
13929 \family default
13930 and
13931 \family typewriter
13932 putchar()
13933 \begin_inset LatexCommand \index{putchar()}
13934
13935 \end_inset
13936
13937
13938 \family default
13939  routines.
13940  SDCC does not know whether the system connects to a serial line with or
13941  without handshake, LCD, keyboard or other device.
13942  You'll find examples for serial routines f.e.
13943  in sdcc/device/lib.
13944 \layout Standard
13945
13946 The default
13947 \family typewriter
13948  printf()
13949 \begin_inset LatexCommand \index{printf()}
13950
13951 \end_inset
13952
13953
13954 \family default
13955 implementation in
13956 \family typewriter
13957  printf_large.c
13958 \family default
13959  does not support float (except on ds390).
13960  To enable this recompile it with the option
13961 \emph on
13962 -
13963 \begin_inset ERT
13964 status Collapsed
13965
13966 \layout Standard
13967
13968 \backslash
13969 /
13970 \end_inset
13971
13972 DUSE_FLOATS=1
13973 \begin_inset LatexCommand \index{USE\_FLOATS}
13974
13975 \end_inset
13976
13977
13978 \emph default
13979  on the command line.
13980  Use
13981 \emph on
13982 -
13983 \begin_inset ERT
13984 status Collapsed
13985
13986 \layout Standard
13987
13988 \backslash
13989 /
13990 \end_inset
13991
13992 -model-large
13993 \begin_inset LatexCommand \index{-\/-model-large}
13994
13995 \end_inset
13996
13997
13998 \emph default
13999  for the mcs51 port, since this uses a lot of memory.
14000 \layout Standard
14001
14002 If you're short on memory you might want to use
14003 \family typewriter
14004 printf_small()
14005 \family default
14006
14007 \emph on
14008 instead
14009 \emph default
14010  of
14011 \family typewriter
14012  printf().
14013
14014 \family default
14015  For the mcs51 there is an assembly version
14016 \family typewriter
14017 printf_fast()
14018 \family default
14019  which should fit the requirements of many embedded systems (by unsetting
14020  #defines it can be customized to
14021 \emph on
14022 not
14023 \emph default
14024  support long variables and field widths).
14025 \layout Subsection
14026
14027 Math functions (sin, pow, sqrt etc.)
14028 \layout Subsection
14029
14030 Other libraries
14031 \layout Standard
14032
14033 Libraries
14034 \begin_inset LatexCommand \index{Libraries}
14035
14036 \end_inset
14037
14038  included in SDCC should have a license at least as liberal as the GNU Lesser
14039  General Public License
14040 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
14041
14042 \end_inset
14043
14044
14045 \emph on
14046 LGPL
14047 \emph default
14048 .
14049 \layout Comment
14050
14051 license statements for the libraries are missing.
14052  sdcc/device/lib/ser_ir.c
14053 \layout Comment
14054
14055 or _decdptr f.e.
14056  come with a GPL (as opposed to LGPL) License - this will not be liberal
14057  enough for many embedded programmers.
14058 \layout Standard
14059
14060 If you have ported some library or want to share experience about some code
14061  which f.e.
14062  falls into any of these categories Busses (I
14063 \begin_inset Formula $^{\textrm{2}}$
14064 \end_inset
14065
14066 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
14067  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
14068  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
14069 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
14070
14071 \end_inset
14072
14073 \SpecialChar ~
14074 would certainly like to hear about it.
14075  Programmers coding for embedded systems are not especially famous for being
14076  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
14077 e these references are very valuable.
14078  Let's help to create a climate where information is shared.
14079 \layout Section
14080
14081 Memory Models
14082 \layout Subsection
14083
14084 MCS51 Memory Models
14085 \begin_inset LatexCommand \index{Memory model}
14086
14087 \end_inset
14088
14089
14090 \begin_inset LatexCommand \index{MCS51 memory model}
14091
14092 \end_inset
14093
14094
14095 \layout Subsubsection
14096
14097 Small and Large
14098 \layout Standard
14099
14100 SDCC allows two memory models for MCS51 code,
14101 \shape slanted
14102 small
14103 \shape default
14104  and
14105 \shape slanted
14106 large
14107 \shape default
14108 .
14109  Modules compiled with different memory models should
14110 \emph on
14111 never
14112 \emph default
14113  be combined together or the results would be unpredictable.
14114  The library routines supplied with the compiler are compiled as both small
14115  and large.
14116  The compiled library modules are contained in separate directories as small
14117  and large so that you can link to either set.
14118
14119 \layout Standard
14120
14121 When the large model is used all variables declared without a storage class
14122  will be allocated into the external ram, this includes all parameters and
14123  local variables (for non-reentrant
14124 \begin_inset LatexCommand \index{reentrant}
14125
14126 \end_inset
14127
14128  functions).
14129  When the small model is used variables without storage class are allocated
14130  in the internal ram.
14131 \layout Standard
14132
14133 Judicious usage of the processor specific storage classes
14134 \begin_inset LatexCommand \index{Storage class}
14135
14136 \end_inset
14137
14138  and the 'reentrant' function type will yield much more efficient code,
14139  than using the large model.
14140  Several optimizations are disabled when the program is compiled using the
14141  large model, it is therefore recommended that the small model be used unless
14142  absolutely required.
14143 \layout Subsubsection
14144
14145 External Stack
14146 \begin_inset LatexCommand \label{sub:External-Stack}
14147
14148 \end_inset
14149
14150
14151 \begin_inset LatexCommand \index{stack}
14152
14153 \end_inset
14154
14155
14156 \begin_inset LatexCommand \index{External stack (mcs51)}
14157
14158 \end_inset
14159
14160
14161 \layout Standard
14162
14163 The external stack (-
14164 \begin_inset ERT
14165 status Collapsed
14166
14167 \layout Standard
14168
14169 \backslash
14170 /
14171 \end_inset
14172
14173 -xstack option
14174 \begin_inset LatexCommand \index{-\/-xstack}
14175
14176 \end_inset
14177
14178 ) is located in pdata
14179 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14180
14181 \end_inset
14182
14183  memory (usually at the start of the external ram segment) and uses all
14184  unused space in pdata (max.
14185  256 bytes).
14186  When -
14187 \begin_inset ERT
14188 status Collapsed
14189
14190 \layout Standard
14191
14192 \backslash
14193 /
14194 \end_inset
14195
14196 -xstack option is used to compile the program, the parameters and local
14197  variables
14198 \begin_inset LatexCommand \index{local variables}
14199
14200 \end_inset
14201
14202  of all reentrant functions are allocated in this area.
14203  This option is provided for programs with large stack space requirements.
14204  When used with the -
14205 \begin_inset ERT
14206 status Collapsed
14207
14208 \layout Standard
14209
14210 \backslash
14211 /
14212 \end_inset
14213
14214 -stack-auto
14215 \begin_inset LatexCommand \index{-\/-stack-auto}
14216
14217 \end_inset
14218
14219  option, all parameters and local variables are allocated on the external
14220  stack (note: support libraries will need to be recompiled with the same
14221  options.
14222  There is a predefined target in the library makefile).
14223 \layout Standard
14224
14225 The compiler outputs the higher order address byte of the external ram segment
14226  into port P2
14227 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14228
14229 \end_inset
14230
14231  (see also section
14232 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14233
14234 \end_inset
14235
14236 ), therefore when using the External Stack option, this port
14237 \emph on
14238 may not
14239 \emph default
14240  be used by the application program.
14241 \layout Subsection
14242
14243 DS390 Memory Model
14244 \begin_inset LatexCommand \index{Memory model}
14245
14246 \end_inset
14247
14248
14249 \begin_inset LatexCommand \index{DS390 memory model}
14250
14251 \end_inset
14252
14253
14254 \layout Standard
14255
14256 The only model supported is Flat 24
14257 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14258
14259 \end_inset
14260
14261 .
14262  This generates code for the 24 bit contiguous addressing mode of the Dallas
14263  DS80C390 part.
14264  In this mode, up to four meg of external RAM or code space can be directly
14265  addressed.
14266  See the data sheets at www.dalsemi.com for further information on this part.
14267 \newline
14268
14269 \newline
14270 Note that the compiler does not generate any code to place the processor
14271  into 24 bitmode (although
14272 \emph on
14273 tinibios
14274 \emph default
14275  in the ds390 libraries will do that for you).
14276  If you don't use
14277 \emph on
14278 tinibios
14279 \emph default
14280
14281 \begin_inset LatexCommand \index{Tinibios (DS390)}
14282
14283 \end_inset
14284
14285 , the boot loader or similar code must ensure that the processor is in 24
14286  bit contiguous addressing mode before calling the SDCC startup code.
14287 \newline
14288
14289 \newline
14290 Like the
14291 \emph on
14292 -
14293 \begin_inset ERT
14294 status Collapsed
14295
14296 \layout Standard
14297
14298 \backslash
14299 /
14300 \end_inset
14301
14302 -model-large
14303 \emph default
14304  option, variables will by default be placed into the XDATA segment.
14305
14306 \newline
14307
14308 \newline
14309 Segments may be placed anywhere in the 4 meg address space using the usual
14310  -
14311 \begin_inset ERT
14312 status Collapsed
14313
14314 \layout Standard
14315
14316 \backslash
14317 /
14318 \end_inset
14319
14320 -*-loc options.
14321  Note that if any segments are located above 64K, the -r flag must be passed
14322  to the linker to generate the proper segment relocations, and the Intel
14323  HEX output format must be used.
14324  The -r flag can be passed to the linker by using the option
14325 \emph on
14326 -Wl-r
14327 \emph default
14328  on the SDCC command line.
14329  However, currently the linker can not handle code segments > 64k.
14330 \layout Section
14331
14332 Pragmas
14333 \begin_inset LatexCommand \index{Pragmas}
14334
14335 \end_inset
14336
14337
14338 \layout Standard
14339
14340 SDCC supports the following #pragma directives:
14341 \layout Itemize
14342
14343 save
14344 \begin_inset LatexCommand \index{\#pragma save}
14345
14346 \end_inset
14347
14348  - this will save all current options to the save/restore stack.
14349  See #pragma\SpecialChar ~
14350 restore.
14351 \layout Itemize
14352
14353 restore
14354 \begin_inset LatexCommand \index{\#pragma restore}
14355
14356 \end_inset
14357
14358  - will restore saved options from the last save.
14359  saves & restores can be nested.
14360  SDCC uses a save/restore stack: save pushes current options to the stack,
14361  restore pulls current options from the stack.
14362  See #pragma\SpecialChar ~
14363 save.
14364 \newline
14365
14366 \layout Itemize
14367
14368 callee_saves
14369 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14370
14371 \end_inset
14372
14373
14374 \begin_inset LatexCommand \index{function prologue}
14375
14376 \end_inset
14377
14378  function1[,function2[,function3...]] - The compiler by default uses a caller
14379  saves convention for register saving across function calls, however this
14380  can cause unnecessary register pushing & popping
14381 \begin_inset LatexCommand \index{push/pop}
14382
14383 \end_inset
14384
14385  when calling small functions from larger functions.
14386  This option can be used to switch off the register saving convention for
14387  the function names specified.
14388  The compiler will not save registers when calling these functions, extra
14389  code need to be manually inserted at the entry & exit for these functions
14390  to save & restore the registers used by these functions, this can SUBSTANTIALLY
14391  reduce code & improve run time performance of the generated code.
14392  In the future the compiler (with inter procedural analysis) may be able
14393  to determine the appropriate scheme to use for each function call.
14394  If -
14395 \begin_inset ERT
14396 status Collapsed
14397
14398 \layout Standard
14399
14400 \backslash
14401 /
14402 \end_inset
14403
14404 -callee-saves command line option is used, the function names specified
14405  in #pragma\SpecialChar ~
14406 callee_saves
14407 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14408
14409 \end_inset
14410
14411  is appended to the list of functions specified in the command line.
14412 \layout Itemize
14413
14414 exclude
14415 \begin_inset LatexCommand \index{\#pragma exclude}
14416
14417 \end_inset
14418
14419  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
14420  of pairs of push/pop
14421 \begin_inset LatexCommand \index{push/pop}
14422
14423 \end_inset
14424
14425  instructions in
14426 \emph on
14427 I
14428 \emph default
14429 nterrupt
14430 \begin_inset LatexCommand \index{interrupt}
14431
14432 \end_inset
14433
14434
14435 \emph on
14436 S
14437 \emph default
14438 ervice
14439 \emph on
14440 R
14441 \emph default
14442 outines.
14443  The directive should be placed immediately before the ISR function definition
14444  and it affects ALL ISR functions following it.
14445  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
14446 exclude\SpecialChar ~
14447 none
14448 \begin_inset LatexCommand \index{\#pragma exclude}
14449
14450 \end_inset
14451
14452 .
14453  See also the related keyword _naked
14454 \begin_inset LatexCommand \index{\_naked}
14455
14456 \end_inset
14457
14458 .
14459 \layout Itemize
14460
14461 less_pedantic
14462 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
14463
14464 \end_inset
14465
14466  - the compiler will not warn you anymore for obvious mistakes, you'r on
14467  your own now ;-(
14468 \layout Itemize
14469
14470 disable_warning <nnnn>
14471 \begin_inset LatexCommand \index{\#pragma disable\_warning}
14472
14473 \end_inset
14474
14475  - the compiler will not warn you anymore about warning number <nnnn>.
14476 \layout Itemize
14477
14478 nogcse
14479 \begin_inset LatexCommand \index{\#pragma nogcse}
14480
14481 \end_inset
14482
14483  - will stop global common subexpression elimination.
14484 \layout Itemize
14485
14486 noinduction
14487 \begin_inset LatexCommand \index{\#pragma noinduction}
14488
14489 \end_inset
14490
14491  - will stop loop induction optimizations.
14492 \layout Itemize
14493
14494 noinvariant
14495 \begin_inset LatexCommand \index{\#pragma noinvariant}
14496
14497 \end_inset
14498
14499  - will not do loop invariant optimizations.
14500  For more details see Loop Invariants in section
14501 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
14502
14503 \end_inset
14504
14505 .
14506 \layout Itemize
14507
14508 noiv
14509 \begin_inset LatexCommand \index{\#pragma noiv}
14510
14511 \end_inset
14512
14513  - Do not generate interrupt
14514 \begin_inset LatexCommand \index{interrupt}
14515
14516 \end_inset
14517
14518  vector table entries for all ISR functions defined after the pragma.
14519  This is useful in cases where the interrupt vector table must be defined
14520  manually, or when there is a secondary, manually defined interrupt vector
14521  table (e.g.
14522  for the autovector feature of the Cypress EZ-USB FX2).
14523  More elegantly this can be achieved by obmitting the optional interrupt
14524  number after the interrupt keyword, see section
14525 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
14526
14527 \end_inset
14528
14529 \SpecialChar ~
14530 about interrupts.
14531 \layout Itemize
14532
14533 nojtbound
14534 \begin_inset LatexCommand \index{\#pragma nojtbound}
14535
14536 \end_inset
14537
14538  - will not generate code for boundary value checking, when switch statements
14539  are turned into jump-tables (dangerous).
14540  For more details see section
14541 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
14542
14543 \end_inset
14544
14545 .
14546 \layout Itemize
14547
14548 noloopreverse
14549 \begin_inset LatexCommand \index{\#pragma noloopreverse}
14550
14551 \end_inset
14552
14553  - Will not do loop reversal optimization
14554 \layout Itemize
14555
14556 nooverlay
14557 \begin_inset LatexCommand \index{\#pragma nooverlay}
14558
14559 \end_inset
14560
14561  - the compiler will not overlay the parameters and local variables of a
14562  function.
14563 \layout Itemize
14564
14565 stackauto
14566 \begin_inset LatexCommand \index{\#pragma stackauto}
14567
14568 \end_inset
14569
14570 - See option -
14571 \begin_inset ERT
14572 status Collapsed
14573
14574 \layout Standard
14575
14576 \backslash
14577 /
14578 \end_inset
14579
14580 -stack-auto
14581 \begin_inset LatexCommand \index{-\/-stack-auto}
14582
14583 \end_inset
14584
14585  and section
14586 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
14587
14588 \end_inset
14589
14590  Parameters and Local Variables.
14591 \layout Itemize
14592
14593 opt_code_speed
14594 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
14595
14596 \end_inset
14597
14598 - The compiler will optimize code generation towards fast code, possibly
14599  at the expense of code size.
14600 \layout Itemize
14601
14602 opt_code_size
14603 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
14604
14605 \end_inset
14606
14607 - The compiler will optimize code generation towards compact code, possibly
14608  at the expense of code speed.
14609 \layout Itemize
14610
14611 opt_code_balanced
14612 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
14613
14614 \end_inset
14615
14616 - The compiler will attempt to generate code that is both compact and fast,
14617  as long as meeting one goal is not a detriment to the other (this is the
14618  default).
14619
14620 \layout Itemize
14621
14622 std_sdcc89
14623 \begin_inset LatexCommand \index{\#pragma std\_sdcc89}
14624
14625 \end_inset
14626
14627 - Generally follow the C89 standard, but allow SDCC features that conflict
14628  with the standard (default).
14629 \layout Itemize
14630
14631 std_c89
14632 \begin_inset LatexCommand \index{\#pragma std\_c89}
14633
14634 \end_inset
14635
14636 - Follow the C89 standard and disable SDCC features that conflict with the
14637  standard.
14638 \layout Itemize
14639
14640 std_sdcc99
14641 \begin_inset LatexCommand \index{\#pragma std\_sdcc99}
14642
14643 \end_inset
14644
14645 - Generally follow the C99 standard, but allow SDCC features that conflict
14646  with the standard (incomplete support).
14647 \layout Itemize
14648
14649 std_c99
14650 \begin_inset LatexCommand \index{\#pragma std\_c99}
14651
14652 \end_inset
14653
14654 - Follow the C99 standard and disable SDCC features that conflict with the
14655  standard (incomplete support).
14656 \layout Standard
14657
14658 SDCPP supports the following #pragma directives:
14659 \layout Itemize
14660
14661 preproc_asm
14662 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
14663
14664 \end_inset
14665
14666  (+ | -) - switch _asm _endasm block preprocessing on / off.
14667  Default is on.
14668 \layout Standard
14669
14670 The pragma's are intended to be used to turn-on or off certain optimizations
14671  which might cause the compiler to generate extra stack / data space to
14672  store compiler generated temporary variables.
14673  This usually happens in large functions.
14674  Pragma directives should be used as shown in the following example, they
14675  are used to control options & optimizations for a given function; pragmas
14676  should be placed before and/or after a function, placing pragma's inside
14677  a function body could have unpredictable results.
14678 \layout Verse
14679
14680
14681 \family typewriter
14682 #pragma save
14683 \begin_inset LatexCommand \index{\#pragma save}
14684
14685 \end_inset
14686
14687  \SpecialChar ~
14688 \SpecialChar ~
14689 \SpecialChar ~
14690 \SpecialChar ~
14691 \SpecialChar ~
14692 \SpecialChar ~
14693 \SpecialChar ~
14694 /* save the current settings */
14695 \newline
14696 #pragma nogcse
14697 \begin_inset LatexCommand \index{\#pragma nogcse}
14698
14699 \end_inset
14700
14701  \SpecialChar ~
14702 \SpecialChar ~
14703 \SpecialChar ~
14704 \SpecialChar ~
14705 \SpecialChar ~
14706 /* turnoff global subexpression elimination */
14707 \newline
14708 #pragma noinduction
14709 \begin_inset LatexCommand \index{\#pragma noinduction}
14710
14711 \end_inset
14712
14713  /* turn off induction optimizations */
14714 \newline
14715 int foo ()
14716 \newline
14717 {
14718 \newline
14719 \SpecialChar ~
14720  \SpecialChar ~
14721  ...
14722
14723 \newline
14724 \SpecialChar ~
14725  \SpecialChar ~
14726  /* large code */
14727 \newline
14728 \SpecialChar ~
14729  \SpecialChar ~
14730  ...
14731
14732 \newline
14733 }
14734 \newline
14735 #pragma restore
14736 \begin_inset LatexCommand \index{\#pragma restore}
14737
14738 \end_inset
14739
14740  /* turn the optimizations back on */
14741 \layout Standard
14742
14743 The compiler will generate a warning message when extra space is allocated.
14744  It is strongly recommended that the save and restore pragma's be used when
14745  changing options for a function.
14746 \layout Section
14747
14748 Defines Created by the Compiler
14749 \layout Standard
14750
14751 The compiler creates the following #defines
14752 \begin_inset LatexCommand \index{\#defines}
14753
14754 \end_inset
14755
14756
14757 \begin_inset LatexCommand \index{Defines created by the compiler}
14758
14759 \end_inset
14760
14761 :
14762 \newline
14763
14764 \layout Standard
14765
14766
14767 \begin_inset  Tabular
14768 <lyxtabular version="3" rows="10" columns="2">
14769 <features>
14770 <column alignment="center" valignment="top" leftline="true" width="0">
14771 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
14772 <row topline="true" bottomline="true">
14773 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14774 \begin_inset Text
14775
14776 \layout Standard
14777
14778
14779 \series bold
14780 #define
14781 \end_inset
14782 </cell>
14783 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14784 \begin_inset Text
14785
14786 \layout Standard
14787
14788
14789 \series bold
14790 Description
14791 \end_inset
14792 </cell>
14793 </row>
14794 <row topline="true">
14795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14796 \begin_inset Text
14797
14798 \layout Standard
14799
14800 SDCC
14801 \begin_inset LatexCommand \index{SDCC}
14802
14803 \end_inset
14804
14805
14806 \end_inset
14807 </cell>
14808 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14809 \begin_inset Text
14810
14811 \layout Standard
14812
14813 this Symbol is always defined
14814 \end_inset
14815 </cell>
14816 </row>
14817 <row topline="true">
14818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14819 \begin_inset Text
14820
14821 \layout Standard
14822
14823 SDCC_mcs51
14824 \begin_inset LatexCommand \index{SDCC\_mcs51}
14825
14826 \end_inset
14827
14828  or SDCC_ds390
14829 \begin_inset LatexCommand \index{SDCC\_ds390}
14830
14831 \end_inset
14832
14833  or SDCC_z80
14834 \begin_inset LatexCommand \index{SDCC\_z80}
14835
14836 \end_inset
14837
14838 , etc
14839 \end_inset
14840 </cell>
14841 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14842 \begin_inset Text
14843
14844 \layout Standard
14845
14846 depending on the model used (e.g.: -mds390
14847 \end_inset
14848 </cell>
14849 </row>
14850 <row topline="true">
14851 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14852 \begin_inset Text
14853
14854 \layout Standard
14855
14856 __mcs51
14857 \begin_inset LatexCommand \index{\_\_mcs51}
14858
14859 \end_inset
14860
14861 , __ds390
14862 \begin_inset LatexCommand \index{\_\_ds390}
14863
14864 \end_inset
14865
14866 , __hc08
14867 \begin_inset LatexCommand \index{\_\_hc08}
14868
14869 \end_inset
14870
14871 , __z80
14872 \begin_inset LatexCommand \index{\_\_z80}
14873
14874 \end_inset
14875
14876 , etc
14877 \end_inset
14878 </cell>
14879 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14880 \begin_inset Text
14881
14882 \layout Standard
14883
14884 depending on the model used (e.g.
14885  -mz80)
14886 \end_inset
14887 </cell>
14888 </row>
14889 <row topline="true">
14890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14891 \begin_inset Text
14892
14893 \layout Standard
14894
14895 SDCC_STACK_AUTO
14896 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
14897
14898 \end_inset
14899
14900
14901 \end_inset
14902 </cell>
14903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14904 \begin_inset Text
14905
14906 \layout Standard
14907
14908 when
14909 \emph on
14910 -
14911 \begin_inset ERT
14912 status Collapsed
14913
14914 \layout Standard
14915
14916 \backslash
14917 /
14918 \end_inset
14919
14920 -stack-auto
14921 \emph default
14922  option is used
14923 \end_inset
14924 </cell>
14925 </row>
14926 <row topline="true">
14927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14928 \begin_inset Text
14929
14930 \layout Standard
14931
14932 SDCC_MODEL_SMALL
14933 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
14934
14935 \end_inset
14936
14937
14938 \end_inset
14939 </cell>
14940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14941 \begin_inset Text
14942
14943 \layout Standard
14944
14945 when
14946 \emph on
14947 -
14948 \begin_inset ERT
14949 status Collapsed
14950
14951 \layout Standard
14952
14953 \backslash
14954 /
14955 \end_inset
14956
14957 -model-small
14958 \emph default
14959  is used
14960 \end_inset
14961 </cell>
14962 </row>
14963 <row topline="true">
14964 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14965 \begin_inset Text
14966
14967 \layout Standard
14968
14969 SDCC_MODEL_LARGE
14970 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
14971
14972 \end_inset
14973
14974
14975 \end_inset
14976 </cell>
14977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14978 \begin_inset Text
14979
14980 \layout Standard
14981
14982 when
14983 \emph on
14984 -
14985 \begin_inset ERT
14986 status Collapsed
14987
14988 \layout Standard
14989
14990 \backslash
14991 /
14992 \end_inset
14993
14994 -model-large
14995 \emph default
14996  is used
14997 \end_inset
14998 </cell>
14999 </row>
15000 <row topline="true">
15001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15002 \begin_inset Text
15003
15004 \layout Standard
15005
15006 SDCC_USE_XSTACK
15007 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
15008
15009 \end_inset
15010
15011
15012 \end_inset
15013 </cell>
15014 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15015 \begin_inset Text
15016
15017 \layout Standard
15018
15019 when
15020 \emph on
15021 -
15022 \begin_inset ERT
15023 status Collapsed
15024
15025 \layout Standard
15026
15027 \backslash
15028 /
15029 \end_inset
15030
15031 -xstack
15032 \emph default
15033  option is used
15034 \end_inset
15035 </cell>
15036 </row>
15037 <row topline="true">
15038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15039 \begin_inset Text
15040
15041 \layout Standard
15042
15043 SDCC_STACK_TENBIT
15044 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
15045
15046 \end_inset
15047
15048
15049 \end_inset
15050 </cell>
15051 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15052 \begin_inset Text
15053
15054 \layout Standard
15055
15056 when
15057 \emph on
15058 -mds390
15059 \emph default
15060  is used
15061 \end_inset
15062 </cell>
15063 </row>
15064 <row topline="true" bottomline="true">
15065 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15066 \begin_inset Text
15067
15068 \layout Standard
15069
15070 SDCC_MODEL_FLAT24
15071 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
15072
15073 \end_inset
15074
15075
15076 \end_inset
15077 </cell>
15078 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15079 \begin_inset Text
15080
15081 \layout Standard
15082
15083 when
15084 \emph on
15085 -mds390
15086 \emph default
15087  is used
15088 \end_inset
15089 </cell>
15090 </row>
15091 </lyxtabular>
15092
15093 \end_inset
15094
15095
15096 \layout Chapter
15097
15098 Notes on supported Processors
15099 \layout Section
15100
15101 MCS51 variants
15102 \begin_inset LatexCommand \label{sub:MCS51-variants}
15103
15104 \end_inset
15105
15106
15107 \begin_inset LatexCommand \index{MCS51 variants}
15108
15109 \end_inset
15110
15111
15112 \layout Standard
15113
15114 MCS51 processors are available from many vendors and come in many different
15115  flavours.
15116  While they might differ considerably in respect to Special Function Registers
15117  the core MCS51 is usually not modified or is kept compatible.
15118
15119 \layout Subsection
15120
15121 pdata access by SFR
15122 \layout Standard
15123
15124 With the upcome of devices with internal xdata and flash memory devices
15125  using port P2
15126 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
15127
15128 \end_inset
15129
15130  as dedicated I/O port is becoming more popular.
15131  Switching the high byte for pdata
15132 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
15133
15134 \end_inset
15135
15136  access which was formerly done by port P2 is then achieved by a Special
15137  Function Register
15138 \begin_inset LatexCommand \index{sfr}
15139
15140 \end_inset
15141
15142 .
15143  In well-established MCS51 tradition the address of this
15144 \emph on
15145 sfr
15146 \emph default
15147  is where the chip designers decided to put it.
15148  Needless to say that they didn't agree on a common name either.
15149  So that the startup code can correctly initialize xdata variables, you
15150  should define an sfr with the name _XPAGE
15151 \family typewriter
15152
15153 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
15154
15155 \end_inset
15156
15157
15158 \family default
15159  at the appropriate location if the default, port P2, is not used for this.
15160  Some examples are:
15161 \layout Verse
15162
15163
15164 \family typewriter
15165 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
15166 \layout Verse
15167
15168
15169 \family typewriter
15170 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
15171 \layout Verse
15172
15173
15174 \family typewriter
15175 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
15176 \layout Standard
15177
15178 For more exotic implementations further customizations may be needed.
15179  See section
15180 \begin_inset LatexCommand \ref{sub:Startup-Code}
15181
15182 \end_inset
15183
15184  for other possibilities.
15185 \layout Subsection
15186
15187 Other Features available by SFR
15188 \layout Standard
15189
15190 Some MCS51 variants offer features like Double DPTR
15191 \begin_inset LatexCommand \index{DPTR}
15192
15193 \end_inset
15194
15195 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
15196  These are currently not used for the MCS51 port.
15197  If you absolutely need them you can fall back to inline assembly or submit
15198  a patch to SDCC.
15199 \layout Section
15200
15201 DS400 port
15202 \layout Standard
15203
15204 The DS80C400 microcontroller has a rich set of peripherals.
15205  In its built-in ROM library it includes functions to access some of the
15206  features, among them is a TCP stack with IP4 and IP6 support.
15207  Library headers (currently in beta status) and other files are provided
15208  at
15209 \size footnotesize
15210
15211 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
15212
15213 \end_inset
15214
15215 .
15216
15217 \layout Section
15218
15219 The Z80 and gbz80 port
15220 \layout Standard
15221
15222 SDCC can target both the Zilog
15223 \begin_inset LatexCommand \index{Z80}
15224
15225 \end_inset
15226
15227  and the Nintendo Gameboy's Z80-like gbz80
15228 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
15229
15230 \end_inset
15231
15232 .
15233  The Z80 port is passed through the same
15234 \emph on
15235 regressions tests
15236 \begin_inset LatexCommand \index{Regression test}
15237
15238 \end_inset
15239
15240
15241 \emph default
15242  as the MCS51 and DS390 ports, so floating point support, support for long
15243  variables and bitfield support is fine.
15244  See mailing lists and forums about interrupt routines.
15245 \layout Standard
15246
15247 As always, the code is the authoritative reference - see z80/ralloc.c and
15248  z80/gen.c.
15249  The stack
15250 \begin_inset LatexCommand \index{stack}
15251
15252 \end_inset
15253
15254  frame is similar to that generated by the IAR Z80 compiler.
15255  IX is used as the base pointer, HL and IY are used as a temporary registers,
15256  and BC and DE are available for holding variables.
15257  Return values
15258 \begin_inset LatexCommand \index{return value}
15259
15260 \end_inset
15261
15262  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
15263  bytes).
15264  The gbz80 port use the same set of registers for the return values, but
15265  in a different order of significance: E (one byte), DE (two bytes), or
15266  HLDE (four bytes).
15267 \layout Section
15268
15269 The HC08 port
15270 \layout Standard
15271
15272 The port to the Motorola HC08
15273 \begin_inset LatexCommand \index{HC08}
15274
15275 \end_inset
15276
15277  family has been added in October 2003, and is still undergoing some basic
15278  development.
15279  The code generator is complete, but the register allocation is still quite
15280  unoptimized.
15281  Some of the SDCC's standard C library functions have embedded non-HC08
15282  inline assembly and so are not yet usable.
15283 \newline
15284
15285 \newline
15286
15287 \layout Section
15288
15289 The PIC14 port
15290 \layout Standard
15291
15292 The 14bit PIC
15293 \begin_inset LatexCommand \index{PIC14}
15294
15295 \end_inset
15296
15297  port still requires a major effort from the development community.
15298  However it can work for very simple code.
15299 \layout Subsection
15300
15301 C code and 14bit PIC code page
15302 \begin_inset LatexCommand \index{code page (pic14)}
15303
15304 \end_inset
15305
15306  and RAM banks
15307 \begin_inset LatexCommand \index{RAM bank (pic14)}
15308
15309 \end_inset
15310
15311
15312 \layout Standard
15313
15314 The linker organizes allocation for the code page and RAM banks.
15315  It does not have intimate knowledge of the code flow.
15316  It will put all the code section of a single asm file into a single code
15317  page.
15318  In order to make use of multiple code pages, separate asm files must be
15319  used.
15320  The compiler treats all functions of a single C file as being in the same
15321  code page unless it is non static.
15322  The compiler treats all local variables of a single C file as being in
15323  the same RAM bank unless it is an extern.
15324 \newline
15325
15326 \newline
15327 To get the best follow these guide lines:
15328 \layout Enumerate
15329
15330 make local functions static, as non static functions require code page selection
15331  overhead.
15332 \layout Enumerate
15333
15334 Make local variables static as extern variables require RAM bank selection
15335  overhead.
15336 \layout Enumerate
15337
15338 For devices that have multiple code pages it is more efficient to use the
15339  same number of files as pages, i.e.
15340  for the 16F877 use 4 separate files and i.e.
15341  for the 16F874 use 2 separate files.
15342  This way the linker can put the code for each file into different code
15343  pages and the compiler can allocate reusable variables more efficiently
15344  and there's less page selection overhead.
15345  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
15346  instruction set) use 'unsigned char' whereever possible instead of 'int'.
15347 \layout Subsection
15348
15349 Creating a device include file
15350 \layout Standard
15351
15352 For generating a device include file use the support perl script inc2h.pl
15353  kept in directory support/script.
15354 \layout Subsection
15355
15356 Interrupt code
15357 \layout Standard
15358
15359 For the interrupt function, use the keyword 'interrupt'
15360 \begin_inset LatexCommand \index{interrupt}
15361
15362 \end_inset
15363
15364  with level number of 0 (PIC14 only has 1 interrupt so this number is only
15365  there to avoid a syntax error - it ought to be fixed).
15366  E.g.:
15367 \layout Verse
15368
15369
15370 \family typewriter
15371 void Intr(void) interrupt 0
15372 \newline
15373 {
15374 \newline
15375 \SpecialChar ~
15376 \SpecialChar ~
15377 T0IF = 0; /* Clear timer interrupt */
15378 \newline
15379 }
15380 \layout Subsection
15381
15382 Linking and assembling
15383 \layout Standard
15384
15385 For assembling you can use either GPUTILS'
15386 \begin_inset LatexCommand \index{gputils (pic tools)}
15387
15388 \end_inset
15389
15390  gpasm.exe or MPLAB's mpasmwin.exe.
15391  GPUTILS is available from
15392 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
15393
15394 \end_inset
15395
15396 .
15397  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
15398  If you use MPLAB and an interrupt function then the linker script file
15399  vectors section will need to be enlarged to link with mplink.
15400 \newline
15401
15402 \newline
15403 Here is a
15404 \family typewriter
15405 Makefile
15406 \family default
15407  using GPUTILS:
15408 \layout Verse
15409
15410
15411 \family typewriter
15412 .c.o:
15413 \newline
15414 \SpecialChar ~
15415 \SpecialChar ~
15416 \SpecialChar ~
15417 \SpecialChar ~
15418 \SpecialChar ~
15419 \SpecialChar ~
15420 \SpecialChar ~
15421 \SpecialChar ~
15422 sdcc -S -V -mpic14 -p16F877 $<
15423 \newline
15424 \SpecialChar ~
15425 \SpecialChar ~
15426 \SpecialChar ~
15427 \SpecialChar ~
15428 \SpecialChar ~
15429 \SpecialChar ~
15430 \SpecialChar ~
15431 \SpecialChar ~
15432 gpasm -c $*.asm
15433 \newline
15434
15435 \newline
15436 $(PRJ).hex: $(OBJS)
15437 \newline
15438 \SpecialChar ~
15439 \SpecialChar ~
15440 \SpecialChar ~
15441 \SpecialChar ~
15442 \SpecialChar ~
15443 \SpecialChar ~
15444 \SpecialChar ~
15445 \SpecialChar ~
15446 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
15447 \layout Standard
15448
15449 Here is a
15450 \family typewriter
15451 Makefile
15452 \family default
15453  using MPLAB:
15454 \layout Verse
15455
15456
15457 \family typewriter
15458 .c.o:
15459 \newline
15460 \SpecialChar ~
15461 \SpecialChar ~
15462 \SpecialChar ~
15463 \SpecialChar ~
15464 \SpecialChar ~
15465 \SpecialChar ~
15466 \SpecialChar ~
15467 \SpecialChar ~
15468 sdcc -S -V -mpic14 -p16F877 $<
15469 \newline
15470 \SpecialChar ~
15471 \SpecialChar ~
15472 \SpecialChar ~
15473 \SpecialChar ~
15474 \SpecialChar ~
15475 \SpecialChar ~
15476 \SpecialChar ~
15477 \SpecialChar ~
15478 mpasmwin /q /o $*.asm
15479 \newline
15480
15481 \newline
15482 $(PRJ).hex: $(OBJS)
15483 \newline
15484 \SpecialChar ~
15485 \SpecialChar ~
15486 \SpecialChar ~
15487 \SpecialChar ~
15488 \SpecialChar ~
15489 \SpecialChar ~
15490 \SpecialChar ~
15491 \SpecialChar ~
15492 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
15493 \layout Standard
15494
15495 Please note that indentations within a
15496 \family typewriter
15497  Makefile
15498 \family default
15499  have to be done with a tabulator character.
15500 \layout Section
15501
15502 The PIC16
15503 \begin_inset LatexCommand \index{PIC16}
15504
15505 \end_inset
15506
15507  port
15508 \layout Standard
15509
15510 The PIC16
15511 \begin_inset LatexCommand \index{PIC16}
15512
15513 \end_inset
15514
15515  port is the portion of SDCC that is responsible to produce code for the
15516  Microchip
15517 \begin_inset LatexCommand \index{Microchip}
15518
15519 \end_inset
15520
15521 (TM) microcontrollers with 16 bit core.
15522  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
15523  Currently supported devices are:
15524 \layout Standard
15525 \align center
15526
15527 \begin_inset  Tabular
15528 <lyxtabular version="3" rows="4" columns="6">
15529 <features>
15530 <column alignment="center" valignment="top" leftline="true" width="0">
15531 <column alignment="center" valignment="top" leftline="true" width="0">
15532 <column alignment="center" valignment="top" leftline="true" width="0">
15533 <column alignment="center" valignment="top" leftline="true" width="0">
15534 <column alignment="center" valignment="top" leftline="true" width="0">
15535 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15536 <row topline="true">
15537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15538 \begin_inset Text
15539
15540 \layout Standard
15541
15542 18F242
15543 \end_inset
15544 </cell>
15545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15546 \begin_inset Text
15547
15548 \layout Standard
15549
15550 18F248
15551 \end_inset
15552 </cell>
15553 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15554 \begin_inset Text
15555
15556 \layout Standard
15557
15558 18F252
15559 \end_inset
15560 </cell>
15561 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15562 \begin_inset Text
15563
15564 \layout Standard
15565
15566 18F258
15567 \end_inset
15568 </cell>
15569 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15570 \begin_inset Text
15571
15572 \layout Standard
15573
15574 18F442
15575 \end_inset
15576 </cell>
15577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15578 \begin_inset Text
15579
15580 \layout Standard
15581
15582 18F448
15583 \end_inset
15584 </cell>
15585 </row>
15586 <row topline="true">
15587 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15588 \begin_inset Text
15589
15590 \layout Standard
15591
15592 18F452
15593 \end_inset
15594 </cell>
15595 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15596 \begin_inset Text
15597
15598 \layout Standard
15599
15600 18F458
15601 \end_inset
15602 </cell>
15603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15604 \begin_inset Text
15605
15606 \layout Standard
15607
15608 18F1220
15609 \end_inset
15610 </cell>
15611 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15612 \begin_inset Text
15613
15614 \layout Standard
15615
15616 18F2220
15617 \end_inset
15618 </cell>
15619 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15620 \begin_inset Text
15621
15622 \layout Standard
15623
15624 18F2550
15625 \end_inset
15626 </cell>
15627 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15628 \begin_inset Text
15629
15630 \layout Standard
15631
15632 18F4331
15633 \end_inset
15634 </cell>
15635 </row>
15636 <row topline="true">
15637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15638 \begin_inset Text
15639
15640 \layout Standard
15641
15642 18F4455
15643 \end_inset
15644 </cell>
15645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15646 \begin_inset Text
15647
15648 \layout Standard
15649
15650 18F6520
15651 \end_inset
15652 </cell>
15653 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15654 \begin_inset Text
15655
15656 \layout Standard
15657
15658 18F6620
15659 \end_inset
15660 </cell>
15661 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15662 \begin_inset Text
15663
15664 \layout Standard
15665
15666 18F6680
15667 \end_inset
15668 </cell>
15669 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15670 \begin_inset Text
15671
15672 \layout Standard
15673
15674 18F6720
15675 \end_inset
15676 </cell>
15677 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15678 \begin_inset Text
15679
15680 \layout Standard
15681
15682 18F8520
15683 \end_inset
15684 </cell>
15685 </row>
15686 <row topline="true" bottomline="true">
15687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15688 \begin_inset Text
15689
15690 \layout Standard
15691
15692 18F8620
15693 \end_inset
15694 </cell>
15695 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15696 \begin_inset Text
15697
15698 \layout Standard
15699
15700 18F8680
15701 \end_inset
15702 </cell>
15703 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15704 \begin_inset Text
15705
15706 \layout Standard
15707
15708 18F8720
15709 \end_inset
15710 </cell>
15711 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15712 \begin_inset Text
15713
15714 \layout Standard
15715
15716 \end_inset
15717 </cell>
15718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15719 \begin_inset Text
15720
15721 \layout Standard
15722
15723 \end_inset
15724 </cell>
15725 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15726 \begin_inset Text
15727
15728 \layout Standard
15729
15730 \end_inset
15731 </cell>
15732 </row>
15733 </lyxtabular>
15734
15735 \end_inset
15736
15737
15738 \layout Subsection
15739
15740 Global Options
15741 \layout Standard
15742
15743 PIC16 port supports the standard command line arguments as supposed, with
15744  the exception of certain cases that will be mentioned in the following
15745  list:
15746 \layout List
15747 \labelwidthstring 00.00.0000
15748
15749 -
15750 \begin_inset ERT
15751 status Collapsed
15752
15753 \layout Standard
15754
15755 \backslash
15756 /
15757 \end_inset
15758
15759 -callee-saves See -
15760 \begin_inset ERT
15761 status Collapsed
15762
15763 \layout Standard
15764
15765 \backslash
15766 /
15767 \end_inset
15768
15769 -all-callee-saves
15770 \layout List
15771 \labelwidthstring 00.00.0000
15772
15773 -
15774 \begin_inset ERT
15775 status Collapsed
15776
15777 \layout Standard
15778
15779 \backslash
15780 /
15781 \end_inset
15782
15783 -all-callee-saves All function arguments are passed on stack by default.
15784
15785 \emph on
15786 There is no need to specify this in the command line.
15787 \layout List
15788 \labelwidthstring 00.00.0000
15789
15790 -
15791 \begin_inset ERT
15792 status Collapsed
15793
15794 \layout Standard
15795
15796 \backslash
15797 /
15798 \end_inset
15799
15800 -fommit-frame-pointer Frame pointer will be omitted when the function uses
15801  no local variables.
15802 \layout Subsection
15803
15804 Port Specific Options
15805 \begin_inset LatexCommand \index{Options PIC16}
15806
15807 \end_inset
15808
15809
15810 \layout Standard
15811
15812 The port specific options appear after the global options in the sdcc --help
15813  output.
15814 \layout Subsubsection
15815
15816 General Options
15817 \layout Standard
15818
15819 General options enable certain port features and optimizations.
15820 \layout List
15821 \labelwidthstring 00.00.0000
15822
15823 -
15824 \begin_inset ERT
15825 status Collapsed
15826
15827 \layout Standard
15828
15829 \backslash
15830 /
15831 \end_inset
15832
15833 -stack-model=[model] Used in conjuction with the command above.
15834  Defines the stack model to be used, valid stack models are :
15835 \begin_deeper
15836 \layout List
15837 \labelwidthstring 00.00.0000
15838
15839
15840 \emph on
15841 small
15842 \emph default
15843  Selects small stack model.
15844  8 bit stack and frame pointers.
15845  Supports 256 bytes stack size.
15846 \layout List
15847 \labelwidthstring 00.00.0000
15848
15849
15850 \emph on
15851 large
15852 \emph default
15853  Selects large stack model.
15854  16 bit stack and frame pointers.
15855  Supports 65536 bytes stack size.
15856 \end_deeper
15857 \layout List
15858 \labelwidthstring 00.00.0000
15859
15860 -
15861 \begin_inset ERT
15862 status Collapsed
15863
15864 \layout Standard
15865
15866 \backslash
15867 /
15868 \end_inset
15869
15870 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
15871  unitialized data variables with [kword].
15872  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
15873 \layout List
15874 \labelwidthstring 00.00.0000
15875
15876 -
15877 \begin_inset ERT
15878 status Collapsed
15879
15880 \layout Standard
15881
15882 \backslash
15883 /
15884 \end_inset
15885
15886 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
15887  Useful for bootloaders.
15888 \layout List
15889 \labelwidthstring 00.00.0000
15890
15891 -
15892 \begin_inset ERT
15893 status Collapsed
15894
15895 \layout Standard
15896
15897 \backslash
15898 /
15899 \end_inset
15900
15901 -asm= sets the full path and name of an external assembler to call.
15902 \layout List
15903 \labelwidthstring 00.00.0000
15904
15905 -
15906 \begin_inset ERT
15907 status Collapsed
15908
15909 \layout Standard
15910
15911 \backslash
15912 /
15913 \end_inset
15914
15915 -link= sets the full path and name of an external linker to call.
15916 \layout List
15917 \labelwidthstring 00.00.0000
15918
15919 -
15920 \begin_inset ERT
15921 status Collapsed
15922
15923 \layout Standard
15924
15925 \backslash
15926 /
15927 \end_inset
15928
15929 -mplab-comp MPLAB compatibility option.
15930  Currently only suppresses special gpasm directives.
15931 \layout Subsubsection
15932
15933 Optimization Options
15934 \layout List
15935 \labelwidthstring 00.00.0000
15936
15937 -
15938 \begin_inset ERT
15939 status Collapsed
15940
15941 \layout Standard
15942
15943 \backslash
15944 /
15945 \end_inset
15946
15947 -optimize-goto Try to use (conditional) BRA instead of GOTO
15948 \layout List
15949 \labelwidthstring 00.00.0000
15950
15951 -
15952 \begin_inset ERT
15953 status Collapsed
15954
15955 \layout Standard
15956
15957 \backslash
15958 /
15959 \end_inset
15960
15961 -optimize-cmp Try to optimize some compares.
15962 \layout List
15963 \labelwidthstring 00.00.0000
15964
15965 -
15966 \begin_inset ERT
15967 status Collapsed
15968
15969 \layout Standard
15970
15971 \backslash
15972 /
15973 \end_inset
15974
15975 -obanksel=nn Set optimization level for inserting BANKSELs.
15976 \newline
15977
15978 \begin_deeper
15979 \layout List
15980 \labelwidthstring 00.00.0000
15981
15982 0 no optimization
15983 \layout List
15984 \labelwidthstring 00.00.0000
15985
15986 1 checks previous used register and if it is the same then does not emit
15987  BANKSEL, accounts only for labels.
15988 \layout List
15989 \labelwidthstring 00.00.0000
15990
15991 2 tries to check the location of (even different) symbols and removes BANKSELs
15992  if they are in the same bank.
15993
15994 \newline
15995
15996 \emph on
15997 Important: There might be problems if the linker script has data sections
15998  across bank borders!
15999 \end_deeper
16000 \layout Subsubsection
16001
16002 Linking Options
16003 \layout List
16004 \labelwidthstring 00.00.0000
16005
16006 -
16007 \begin_inset ERT
16008 status Collapsed
16009
16010 \layout Standard
16011
16012 \backslash
16013 /
16014 \end_inset
16015
16016 -nodefaultlibs do not link default libraries when linking
16017 \layout List
16018 \labelwidthstring 00.00.0000
16019
16020 -
16021 \begin_inset ERT
16022 status Collapsed
16023
16024 \layout Standard
16025
16026 \backslash
16027 /
16028 \end_inset
16029
16030 -no-crt Don't link the default run-time modules
16031 \layout List
16032 \labelwidthstring 00.00.0000
16033
16034 -
16035 \begin_inset ERT
16036 status Collapsed
16037
16038 \layout Standard
16039
16040 \backslash
16041 /
16042 \end_inset
16043
16044 -use-crt= Use a custom run-time module instead of the defaults.
16045 \layout Subsubsection
16046
16047 Debugging Options
16048 \layout Standard
16049
16050 Debugging options enable extra debugging information in the output files.
16051 \layout List
16052 \labelwidthstring 00.00.0000
16053
16054 -
16055 \begin_inset ERT
16056 status Collapsed
16057
16058 \layout Standard
16059
16060 \backslash
16061 /
16062 \end_inset
16063
16064 -debug-xtra Similar to -
16065 \begin_inset ERT
16066 status Collapsed
16067
16068 \layout Standard
16069
16070 \backslash
16071 /
16072 \end_inset
16073
16074 -debug
16075 \begin_inset LatexCommand \index{-\/-debug}
16076
16077 \end_inset
16078
16079 , but dumps more information.
16080 \layout List
16081 \labelwidthstring 00.00.0000
16082
16083 -
16084 \begin_inset ERT
16085 status Collapsed
16086
16087 \layout Standard
16088
16089 \backslash
16090 /
16091 \end_inset
16092
16093 -debug-ralloc Force register allocator to dump <source>.d file with debugging
16094  information.
16095  <source> is the name of the file compiled.
16096 \layout List
16097 \labelwidthstring 00.00.0000
16098
16099 -
16100 \begin_inset ERT
16101 status Collapsed
16102
16103 \layout Standard
16104
16105 \backslash
16106 /
16107 \end_inset
16108
16109 -pcode-verbose Enable pcode debugging information in translation.
16110 \layout List
16111 \labelwidthstring 00.00.0000
16112
16113 -
16114 \begin_inset ERT
16115 status Collapsed
16116
16117 \layout Standard
16118
16119 \backslash
16120 /
16121 \end_inset
16122
16123 -denable-peeps Force the usage of peepholes.
16124  Use with care.
16125 \layout List
16126 \labelwidthstring 00.00.0000
16127
16128 -
16129 \begin_inset ERT
16130 status Collapsed
16131
16132 \layout Standard
16133
16134 \backslash
16135 /
16136 \end_inset
16137
16138 -gstack Trace push/pops for stack pointer overflow
16139 \layout List
16140 \labelwidthstring 00.00.0000
16141
16142 -
16143 \begin_inset ERT
16144 status Collapsed
16145
16146 \layout Standard
16147
16148 \backslash
16149 /
16150 \end_inset
16151
16152 -call-tree dump call tree in .calltree file
16153 \layout Subsection
16154
16155 Enviromental Variables
16156 \layout Standard
16157
16158 There is a number of enviromental variables that can be used when running
16159  SDCC to enable certain optimizations or force a specific program behaviour.
16160  these variables are primarily for debugging purposes so they can be enabled/dis
16161 abled at will.
16162 \layout Standard
16163
16164 Currently there is only two such variables available:
16165 \layout List
16166 \labelwidthstring 00.00.0000
16167
16168 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
16169  bitfields is optimized by directly loading FSR0 with the address of the
16170  bitfield structure.
16171  Normally SDCC will cast the bitfield structure to a bitfield pointer and
16172  then load FSR0.
16173  This step saves data ram and code space for functions that perform heavy
16174  use of bitfields.
16175  (ie.
16176  80 bytes of code space are saved when compiling malloc.c with this option).
16177
16178 \layout List
16179 \labelwidthstring 00.00.0000
16180
16181 NO_REG_OPT do not perform pCode registers optimization.
16182  This should be used for debugging purposes.
16183  In some where bugs in the pcode optimizer are found, users can benefit
16184  from temporarily disabling the optimizer until the bug is fixed.
16185 \layout Subsection
16186
16187 Preprocessor Macros
16188 \layout Standard
16189
16190 PIC16 port defines the following preprocessor macros while translating a
16191  source.
16192 \layout Standard
16193 \align center
16194
16195 \begin_inset  Tabular
16196 <lyxtabular version="3" rows="6" columns="2">
16197 <features>
16198 <column alignment="center" valignment="top" leftline="true" width="0">
16199 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16200 <row topline="true" bottomline="true">
16201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16202 \begin_inset Text
16203
16204 \layout Standard
16205
16206 Macro
16207 \end_inset
16208 </cell>
16209 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16210 \begin_inset Text
16211
16212 \layout Standard
16213
16214 Description
16215 \end_inset
16216 </cell>
16217 </row>
16218 <row topline="true">
16219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16220 \begin_inset Text
16221
16222 \layout Standard
16223
16224 SDCC_pic16
16225 \end_inset
16226 </cell>
16227 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16228 \begin_inset Text
16229
16230 \layout Standard
16231
16232 Port identification
16233 \end_inset
16234 </cell>
16235 </row>
16236 <row topline="true">
16237 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16238 \begin_inset Text
16239
16240 \layout Standard
16241
16242 _
16243 \begin_inset ERT
16244 status Collapsed
16245
16246 \layout Standard
16247
16248 \backslash
16249 /
16250 \end_inset
16251
16252 _pic16
16253 \end_inset
16254 </cell>
16255 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16256 \begin_inset Text
16257
16258 \layout Standard
16259
16260 Port identification (same as above)
16261 \end_inset
16262 </cell>
16263 </row>
16264 <row topline="true">
16265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16266 \begin_inset Text
16267
16268 \layout Standard
16269
16270 pic18fxxxx
16271 \end_inset
16272 </cell>
16273 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16274 \begin_inset Text
16275
16276 \layout Standard
16277
16278 MCU Identification.
16279
16280 \emph on
16281 xxxx
16282 \emph default
16283  is the microcontrol identification number, i.e.
16284  452, 6620, etc
16285 \end_inset
16286 </cell>
16287 </row>
16288 <row topline="true">
16289 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16290 \begin_inset Text
16291
16292 \layout Standard
16293
16294 _
16295 \begin_inset ERT
16296 status Collapsed
16297
16298 \layout Standard
16299
16300 \backslash
16301 /
16302 \end_inset
16303
16304 _18Fxxxx
16305 \end_inset
16306 </cell>
16307 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16308 \begin_inset Text
16309
16310 \layout Standard
16311
16312 MCU Identification (same as above)
16313 \end_inset
16314 </cell>
16315 </row>
16316 <row topline="true" bottomline="true">
16317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16318 \begin_inset Text
16319
16320 \layout Standard
16321
16322 STACK_MODEL_nnn
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 nnn = SMALL or LARGE respectively according to the stack model used
16331 \end_inset
16332 </cell>
16333 </row>
16334 </lyxtabular>
16335
16336 \end_inset
16337
16338
16339 \layout Standard
16340
16341 In addition the following macros are defined when calling assembler:
16342 \layout Standard
16343 \align center
16344
16345 \begin_inset  Tabular
16346 <lyxtabular version="3" rows="4" columns="2">
16347 <features>
16348 <column alignment="center" valignment="top" leftline="true" width="0">
16349 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16350 <row topline="true" bottomline="true">
16351 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16352 \begin_inset Text
16353
16354 \layout Standard
16355
16356 Macro
16357 \end_inset
16358 </cell>
16359 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16360 \begin_inset Text
16361
16362 \layout Standard
16363
16364 Description
16365 \end_inset
16366 </cell>
16367 </row>
16368 <row topline="true">
16369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16370 \begin_inset Text
16371
16372 \layout Standard
16373
16374 __18Fxxxx
16375 \end_inset
16376 </cell>
16377 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16378 \begin_inset Text
16379
16380 \layout Standard
16381
16382 MCU Identification.
16383
16384 \emph on
16385 xxxx
16386 \emph default
16387  is the microcontrol identification number, i.e.
16388  452, 6620, etc
16389 \end_inset
16390 </cell>
16391 </row>
16392 <row topline="true">
16393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16394 \begin_inset Text
16395
16396 \layout Standard
16397
16398 SDCC_MODEL_nnn
16399 \end_inset
16400 </cell>
16401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16402 \begin_inset Text
16403
16404 \layout Standard
16405
16406 nnn = SMALL or LARGE respectively according to the memory model used for
16407  SDCC
16408 \end_inset
16409 </cell>
16410 </row>
16411 <row topline="true" bottomline="true">
16412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16413 \begin_inset Text
16414
16415 \layout Standard
16416
16417 STACK_MODEL_nnn
16418 \end_inset
16419 </cell>
16420 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16421 \begin_inset Text
16422
16423 \layout Standard
16424
16425 nnn = SMALL or LARGE respectively according to the stack model used
16426 \end_inset
16427 </cell>
16428 </row>
16429 </lyxtabular>
16430
16431 \end_inset
16432
16433
16434 \layout Subsection
16435
16436 Directories
16437 \layout Standard
16438
16439 PIC16
16440 \begin_inset LatexCommand \index{PIC16}
16441
16442 \end_inset
16443
16444  port uses the following directories for searching header files and libraries.
16445 \layout Standard
16446 \align center
16447
16448 \begin_inset  Tabular
16449 <lyxtabular version="3" rows="3" columns="4">
16450 <features>
16451 <column alignment="center" valignment="top" leftline="true" width="0">
16452 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16453 <column alignment="center" valignment="top" width="0">
16454 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16455 <row topline="true" bottomline="true">
16456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16457 \begin_inset Text
16458
16459 \layout Standard
16460
16461 Directory
16462 \end_inset
16463 </cell>
16464 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16465 \begin_inset Text
16466
16467 \layout Standard
16468
16469 Description
16470 \end_inset
16471 </cell>
16472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16473 \begin_inset Text
16474
16475 \layout Standard
16476
16477 Target
16478 \end_inset
16479 </cell>
16480 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16481 \begin_inset Text
16482
16483 \layout Standard
16484
16485 Command prefix
16486 \end_inset
16487 </cell>
16488 </row>
16489 <row topline="true">
16490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16491 \begin_inset Text
16492
16493 \layout Standard
16494
16495 PREFIX/sdcc/include/pic16
16496 \end_inset
16497 </cell>
16498 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16499 \begin_inset Text
16500
16501 \layout Standard
16502
16503 PIC16 specific headers
16504 \end_inset
16505 </cell>
16506 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16507 \begin_inset Text
16508
16509 \layout Standard
16510
16511 Compiler
16512 \end_inset
16513 </cell>
16514 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16515 \begin_inset Text
16516
16517 \layout Standard
16518
16519 -I
16520 \end_inset
16521 </cell>
16522 </row>
16523 <row topline="true" bottomline="true">
16524 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16525 \begin_inset Text
16526
16527 \layout Standard
16528
16529 PREFIX/sdcc/lib/pic16
16530 \end_inset
16531 </cell>
16532 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16533 \begin_inset Text
16534
16535 \layout Standard
16536
16537 PIC16 specific libraries
16538 \end_inset
16539 </cell>
16540 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16541 \begin_inset Text
16542
16543 \layout Standard
16544
16545 Linker
16546 \end_inset
16547 </cell>
16548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16549 \begin_inset Text
16550
16551 \layout Standard
16552
16553 -L
16554 \end_inset
16555 </cell>
16556 </row>
16557 </lyxtabular>
16558
16559 \end_inset
16560
16561
16562 \layout Subsection
16563
16564 Pragmas
16565 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
16566
16567 \end_inset
16568
16569
16570 \layout Standard
16571
16572 PIC16 port currently supports the following pragmas:
16573 \layout List
16574 \labelwidthstring 00.00.0000
16575
16576 stack pragma stack forces the code generator to initialize the stack & frame
16577  pointers at a specific address.
16578  This is an adhoc solution for cases where no STACK directive is available
16579  in the linker script or gplink is not instructed to create a stack section.
16580 \newline
16581 The stack pragma should be used only once in a project.
16582  Multiple pragmas may result in indeterminate behaviour of the program.
16583 \begin_inset Foot
16584 collapsed false
16585
16586 \layout Standard
16587
16588 The old format (ie.
16589  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
16590  cross page boundaries (or even exceed the available data RAM) and crash
16591  the program.
16592  Make sure that stack does not cross page boundaries when using the SMALL
16593  stack model.
16594 \end_inset
16595
16596
16597 \newline
16598 The format is as follows:
16599 \layout LyX-Code
16600
16601 #pragma stack bottom_address [stack_size]
16602 \layout Standard
16603
16604
16605 \emph on
16606 bottom_address
16607 \emph default
16608  is the lower bound of the stack section.
16609  The stack pointer initially will point at address (bottom_address+stack_size-1).
16610 \layout LyX-Code
16611
16612 Example:
16613 \layout LyX-Code
16614
16615 \layout LyX-Code
16616
16617 /* initializes stack of 100 bytes at RAM address 0x200 */
16618 \layout LyX-Code
16619
16620 #pragma stack 0x200 100
16621 \layout Standard
16622
16623 If the stack_size field is omitted then a stack is created with the default
16624  size of 64.
16625  This size might be enough for most programs, but its not enough for operations
16626  with deep function nesting or excessive stack usage.
16627 \layout List
16628 \labelwidthstring 00.00.0000
16629
16630 wparam
16631 \emph on
16632 This pragma is deprecated.
16633  Its use will cause a warning message to be issued.
16634 \emph default
16635
16636 \newline
16637
16638 \layout List
16639 \labelwidthstring 00.00.0000
16640
16641 code place a function symbol at static FLASH address
16642 \layout LyX-Code
16643
16644 Example:
16645 \layout LyX-Code
16646
16647 \layout LyX-Code
16648
16649 /* place function test_func at 0x4000 */
16650 \layout LyX-Code
16651
16652 #pragma code test_func 0x4000
16653 \layout LyX-Code
16654
16655 \layout List
16656 \labelwidthstring 00.00.0000
16657
16658 library instructs the linker to use a library module.
16659 \newline
16660 Usage:
16661 \layout LyX-Code
16662
16663 #pragma library module_name
16664 \layout Standard
16665
16666
16667 \emph on
16668 module_name
16669 \emph default
16670  can be any library or object file (including its path).
16671  Note that there are four reserved keywords which have special meaning.
16672  These are:
16673 \layout Standard
16674 \align center
16675
16676 \begin_inset  Tabular
16677 <lyxtabular version="3" rows="6" columns="3">
16678 <features>
16679 <column alignment="center" valignment="top" leftline="true" width="0">
16680 <column alignment="block" valignment="top" leftline="true" width="20page%">
16681 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
16682 <row topline="true" bottomline="true">
16683 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16684 \begin_inset Text
16685
16686 \layout Standard
16687
16688 Keyword
16689 \end_inset
16690 </cell>
16691 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16692 \begin_inset Text
16693
16694 \layout Standard
16695
16696 Description
16697 \end_inset
16698 </cell>
16699 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16700 \begin_inset Text
16701
16702 \layout Standard
16703
16704 Module to link
16705 \end_inset
16706 </cell>
16707 </row>
16708 <row topline="true">
16709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16710 \begin_inset Text
16711
16712 \layout Standard
16713
16714
16715 \series bold
16716 ignore
16717 \end_inset
16718 </cell>
16719 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16720 \begin_inset Text
16721
16722 \layout Standard
16723
16724 ignore all library pragmas
16725 \end_inset
16726 </cell>
16727 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16728 \begin_inset Text
16729
16730 \layout Standard
16731
16732
16733 \emph on
16734 (none)
16735 \end_inset
16736 </cell>
16737 </row>
16738 <row topline="true">
16739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16740 \begin_inset Text
16741
16742 \layout Standard
16743
16744
16745 \series bold
16746 c
16747 \end_inset
16748 </cell>
16749 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16750 \begin_inset Text
16751
16752 \layout Standard
16753
16754 link the C library
16755 \end_inset
16756 </cell>
16757 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16758 \begin_inset Text
16759
16760 \layout Standard
16761
16762
16763 \emph on
16764 libc18f
16765 \emph default
16766 .lib
16767 \end_inset
16768 </cell>
16769 </row>
16770 <row topline="true">
16771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16772 \begin_inset Text
16773
16774 \layout Standard
16775
16776
16777 \series bold
16778 math
16779 \end_inset
16780 </cell>
16781 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16782 \begin_inset Text
16783
16784 \layout Standard
16785
16786 link the Math libarary
16787 \end_inset
16788 </cell>
16789 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16790 \begin_inset Text
16791
16792 \layout Standard
16793
16794
16795 \emph on
16796 libm18f
16797 \emph default
16798 .lib
16799 \end_inset
16800 </cell>
16801 </row>
16802 <row topline="true">
16803 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16804 \begin_inset Text
16805
16806 \layout Standard
16807
16808
16809 \series bold
16810 io
16811 \end_inset
16812 </cell>
16813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16814 \begin_inset Text
16815
16816 \layout Standard
16817
16818 link the I/O library
16819 \end_inset
16820 </cell>
16821 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16822 \begin_inset Text
16823
16824 \layout Standard
16825
16826
16827 \emph on
16828 libio18f*
16829 \emph default
16830 .lib
16831 \end_inset
16832 </cell>
16833 </row>
16834 <row topline="true" bottomline="true">
16835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16836 \begin_inset Text
16837
16838 \layout Standard
16839
16840
16841 \series bold
16842 debug
16843 \end_inset
16844 </cell>
16845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16846 \begin_inset Text
16847
16848 \layout Standard
16849
16850 link the debug library
16851 \end_inset
16852 </cell>
16853 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16854 \begin_inset Text
16855
16856 \layout Standard
16857
16858
16859 \emph on
16860 libdebug
16861 \emph default
16862 .lib
16863 \end_inset
16864 </cell>
16865 </row>
16866 </lyxtabular>
16867
16868 \end_inset
16869
16870
16871 \newline
16872 * is the device number, i.e.
16873  452 for PIC18F452 MCU.
16874 \layout Standard
16875
16876 This feature allows for linking with specific libraries withoug having to
16877  explicit name them in the command line.
16878  Note that the
16879 \noun on
16880 ignore
16881 \noun default
16882  keyword will reject all modules specified by the library pragma.
16883 \layout List
16884 \labelwidthstring 00.00.0000
16885
16886 udata pragma udata instructs the compiler to emit code so that linker will
16887  place a variable at a specific memory bank
16888 \layout LyX-Code
16889
16890 Example:
16891 \layout LyX-Code
16892
16893 \layout LyX-Code
16894
16895 /* places variable foo at bank2 */
16896 \layout LyX-Code
16897
16898 #pragma udata bank2 foo
16899 \layout LyX-Code
16900
16901 char foo;
16902 \layout Standard
16903
16904 In order for this pragma to work extra SECTION directives should be added
16905  in the .lkr script.
16906  In the following example a sample .lkr file is shown:
16907 \layout LyX-Code
16908
16909 \layout LyX-Code
16910
16911 // Sample linker script for the PIC18F452 processor
16912 \layout LyX-Code
16913
16914 LIBPATH .
16915 \layout LyX-Code
16916
16917 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
16918 \layout LyX-Code
16919
16920 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
16921 \layout LyX-Code
16922
16923 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
16924 \layout LyX-Code
16925
16926 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
16927 \layout LyX-Code
16928
16929 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
16930 \layout LyX-Code
16931
16932 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
16933 \layout LyX-Code
16934
16935 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
16936 \layout LyX-Code
16937
16938 \layout LyX-Code
16939
16940 DATABANK   NAME=gpr0       START=0x80           END=0xFF
16941 \layout LyX-Code
16942
16943 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
16944 \layout LyX-Code
16945
16946 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
16947 \layout LyX-Code
16948
16949 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
16950 \layout LyX-Code
16951
16952 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
16953 \layout LyX-Code
16954
16955 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
16956 \layout LyX-Code
16957
16958 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
16959 \layout LyX-Code
16960
16961 \layout LyX-Code
16962
16963 SECTION    NAME=CONFIG     ROM=config
16964 \layout LyX-Code
16965
16966 \layout LyX-Code
16967
16968 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
16969 \layout LyX-Code
16970
16971 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
16972 \layout LyX-Code
16973
16974 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
16975 \layout LyX-Code
16976
16977 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
16978 \layout LyX-Code
16979
16980 SECTION    NAME=bank4      RAM=gpr4
16981 \layout LyX-Code
16982
16983 SECTION    NAME=bank5      RAM=gpr5
16984 \layout Standard
16985
16986 The linker will recognise the section name set in the pragma statement and
16987  will position the variable at the memory bank set with the RAM field at
16988  the SECTION line in the linker script file.
16989 \layout Subsection
16990
16991 Header Files
16992 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
16993
16994 \end_inset
16995
16996
16997 \layout Standard
16998
16999 There is one main header file that can be included to the source files using
17000  the pic16 port.
17001  That file is the
17002 \series bold
17003 pic18fregs.h
17004 \series default
17005 .
17006  This header file contains the definitions for the processor special registers,
17007  so it is necessary if the source accesses them.
17008  It can be included by adding the following line in the beginning of the
17009  file:
17010 \layout LyX-Code
17011
17012 #include <pic18fregs.h>
17013 \layout Standard
17014
17015 The specific microcontroller is selected within the pic18fregs.h automatically,
17016  so the same source can be used with a variety of devices.
17017 \layout Subsection
17018
17019 Libraries
17020 \layout Standard
17021
17022 The libraries that PIC16
17023 \begin_inset LatexCommand \index{PIC16}
17024
17025 \end_inset
17026
17027  port depends on are the microcontroller device libraries which contain
17028  the symbol definitions for the microcontroller special function registers.
17029  These libraries have the format pic18fxxxx.lib, where
17030 \emph on
17031 xxxx
17032 \emph default
17033  is the microcontroller identification number.
17034  The specific library is selected automatically by the compiler at link
17035  stage according to the selected device.
17036 \layout Standard
17037
17038 Libraries are created with gplib which is part of the gputils package
17039 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
17040
17041 \end_inset
17042
17043 .
17044 \layout Subsubsection*
17045
17046 Building the libraries
17047 \layout Standard
17048
17049 Before using SDCC/pic16 there are some libraries that need to be compiled.
17050  This process is not done automatically by SDCC since not all users use
17051  SDCC for pic16 projects.
17052  So each user should compile the libraries separately.
17053 \layout Standard
17054
17055 The steps to compile the pic16 libraries under Linux are:
17056 \layout LyX-Code
17057
17058 cd device/lib/pic16
17059 \layout LyX-Code
17060
17061 ./configure
17062 \layout LyX-Code
17063
17064 make
17065 \layout LyX-Code
17066
17067 cd ..
17068 \layout LyX-Code
17069
17070 make model-pic16
17071 \layout LyX-Code
17072
17073 su -c 'make install'     # install the libraries, you need the root password
17074 \layout Standard
17075
17076 If you need to install the headers too, do:
17077 \layout LyX-Code
17078
17079 cd device/include
17080 \layout LyX-Code
17081
17082 su -c 'make install'     # install the headers, you need the root password
17083 \layout Standard
17084
17085 There exist a special target to build the I/O libraries.
17086  This target is not automatically build because it will build the I/O library
17087  for
17088 \emph on
17089 every
17090 \emph default
17091  supported device.
17092  This way building will take quite a lot of time.
17093  Users are advised to edit the
17094 \series bold
17095 device/lib/pic16/pics.build
17096 \series default
17097  file and then execute:
17098 \layout LyX-Code
17099
17100 make lib-io
17101 \layout Subsection
17102
17103 Memory Models
17104 \layout Standard
17105
17106 The following memory models are supported by the PIC16 port:
17107 \layout Itemize
17108
17109 small model
17110 \layout Itemize
17111
17112 large model
17113 \layout Standard
17114
17115 Memory model affects the default size of pointers within the source.
17116  The sizes are shown in the next table:
17117 \layout Standard
17118 \align center
17119
17120 \begin_inset  Tabular
17121 <lyxtabular version="3" rows="3" columns="3">
17122 <features>
17123 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17124 <column alignment="center" valignment="top" leftline="true" width="0">
17125 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17126 <row topline="true" bottomline="true">
17127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17128 \begin_inset Text
17129
17130 \layout Standard
17131
17132 Pointer sizes according to memory model
17133 \end_inset
17134 </cell>
17135 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17136 \begin_inset Text
17137
17138 \layout Standard
17139
17140 small model
17141 \end_inset
17142 </cell>
17143 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17144 \begin_inset Text
17145
17146 \layout Standard
17147
17148 large model
17149 \end_inset
17150 </cell>
17151 </row>
17152 <row topline="true" bottomline="true">
17153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17154 \begin_inset Text
17155
17156 \layout Standard
17157
17158 code pointers
17159 \end_inset
17160 </cell>
17161 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17162 \begin_inset Text
17163
17164 \layout Standard
17165
17166 16-bits
17167 \end_inset
17168 </cell>
17169 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17170 \begin_inset Text
17171
17172 \layout Standard
17173
17174 24-bits
17175 \end_inset
17176 </cell>
17177 </row>
17178 <row topline="true" bottomline="true">
17179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17180 \begin_inset Text
17181
17182 \layout Standard
17183
17184 data pointers
17185 \end_inset
17186 </cell>
17187 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
17188 \begin_inset Text
17189
17190 \layout Standard
17191
17192 16-bits
17193 \end_inset
17194 </cell>
17195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17196 \begin_inset Text
17197
17198 \layout Standard
17199
17200 16-bits
17201 \end_inset
17202 </cell>
17203 </row>
17204 </lyxtabular>
17205
17206 \end_inset
17207
17208
17209 \layout Standard
17210
17211 It is advisable that all sources within a project are compiled with the
17212  same memory model.
17213  If one wants to override the default memory model, this can be done by
17214  declaring a pointer as
17215 \series bold
17216 far
17217 \series default
17218  or
17219 \series bold
17220 near
17221 \series default
17222 .
17223  Far selects large memory model's pointers, while near selects small memory
17224  model's pointers.
17225 \layout Standard
17226
17227 The standard device libraries (see
17228 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
17229
17230 \end_inset
17231
17232 ) contain no reference to pointers, so they can be used with both memory
17233  models.
17234 \layout Subsection
17235
17236 Stack
17237 \layout Standard
17238
17239 The stack implementation for the PIC16 port uses two indirect registers,
17240  FSR1 and FSR2.
17241 \layout List
17242 \labelwidthstring 00.00.0000
17243
17244 FSR1 is assigned as stack pointer
17245 \layout List
17246 \labelwidthstring 00.00.0000
17247
17248 FSR2 is assigned as frame pointer
17249 \layout Standard
17250
17251 The following stack models are supported by the PIC16 port
17252 \layout Itemize
17253
17254
17255 \noun on
17256 small
17257 \noun default
17258  model
17259 \layout Itemize
17260
17261
17262 \noun on
17263 large
17264 \noun default
17265  model
17266 \layout Standard
17267
17268
17269 \noun on
17270 Small
17271 \noun default
17272  model means that only the FSRxL byte is used to access stack and frame,
17273  while
17274 \emph on
17275 \noun on
17276 large
17277 \emph default
17278 \noun default
17279  uses both FSRxL and FSRxH registers.
17280  The following table shows the stack/frame pointers sizes according to stack
17281  model and the maximum space they can address:
17282 \layout Standard
17283 \align center
17284
17285 \begin_inset  Tabular
17286 <lyxtabular version="3" rows="3" columns="3">
17287 <features>
17288 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17289 <column alignment="center" valignment="top" leftline="true" width="0">
17290 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17291 <row topline="true" bottomline="true">
17292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17293 \begin_inset Text
17294
17295 \layout Standard
17296
17297 Stack & Frame pointer sizes according to stack model
17298 \end_inset
17299 </cell>
17300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17301 \begin_inset Text
17302
17303 \layout Standard
17304
17305 small
17306 \end_inset
17307 </cell>
17308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17309 \begin_inset Text
17310
17311 \layout Standard
17312
17313 large
17314 \end_inset
17315 </cell>
17316 </row>
17317 <row topline="true">
17318 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17319 \begin_inset Text
17320
17321 \layout Standard
17322
17323 Stack pointer FSR1
17324 \end_inset
17325 </cell>
17326 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17327 \begin_inset Text
17328
17329 \layout Standard
17330
17331 8-bits
17332 \end_inset
17333 </cell>
17334 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17335 \begin_inset Text
17336
17337 \layout Standard
17338
17339 16-bits
17340 \end_inset
17341 </cell>
17342 </row>
17343 <row topline="true" bottomline="true">
17344 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17345 \begin_inset Text
17346
17347 \layout Standard
17348
17349 Frame pointer FSR2
17350 \end_inset
17351 </cell>
17352 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17353 \begin_inset Text
17354
17355 \layout Standard
17356
17357 8-bits
17358 \end_inset
17359 </cell>
17360 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17361 \begin_inset Text
17362
17363 \layout Standard
17364
17365 16-bits
17366 \end_inset
17367 </cell>
17368 </row>
17369 </lyxtabular>
17370
17371 \end_inset
17372
17373
17374 \layout Standard
17375
17376
17377 \noun on
17378 Large
17379 \noun default
17380 stack model is currently not working properly throughout the code generator.
17381  So its use is not advised.
17382  Also there are some other points that need special care:
17383 \newline
17384
17385 \layout Enumerate
17386
17387 Do not create stack sections with size more than one physical bank (that
17388  is 256 bytes)
17389 \layout Enumerate
17390
17391 Stack sections should no cross physical bank limits (i.e.
17392  #pragma stack 0x50 0x100)
17393 \layout Standard
17394
17395 These limitations are caused by the fact that only FSRxL is modified when
17396  using SMALL stack model, so no more than 256 bytes of stack can be used.
17397  This problem will disappear after LARGE model is fully implemented.
17398 \layout Subsection
17399
17400 Functions
17401 \layout Standard
17402
17403 In addition to the standard SDCC function keywords, PIC16 port makes available
17404  two more:
17405 \layout List
17406 \labelwidthstring 00.00.0000
17407
17408 wparam Use the WREG to pass one byte of the first function argument.
17409  This improves speed but you may not use this for functions with arguments
17410  that are called via function pointers, otherwise the first byte of the
17411  first parameter will get lost.
17412  Usage:
17413 \layout LyX-Code
17414
17415 void func_wparam(int a) wparam
17416 \layout LyX-Code
17417
17418 {
17419 \layout LyX-Code
17420
17421     /* WREG hold the lower part of a */
17422 \layout LyX-Code
17423
17424     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
17425  */
17426 \layout LyX-Code
17427
17428 ...
17429 \layout LyX-Code
17430
17431 }
17432 \layout Standard
17433
17434 This keyword replaces the deprecated wparam pragma.
17435 \layout List
17436 \labelwidthstring 00.00.0000
17437
17438 shadowregs When entering/exiting an ISR, it is possible to take advantage
17439  of the PIC18F hardware shadow registers which hold the values of WREG,
17440  STATUS and BSR registers.
17441  This can be done by adding the keyword
17442 \emph on
17443 shadowregs
17444 \emph default
17445  before the
17446 \emph on
17447 interrupt
17448 \emph default
17449  keyword in the function's header.
17450 \layout LyX-Code
17451
17452 void isr_shadow(void) shadowregs interrupt 1
17453 \layout LyX-Code
17454
17455 {
17456 \layout LyX-Code
17457
17458 ...
17459 \layout LyX-Code
17460
17461 }
17462 \layout Standard
17463
17464
17465 \emph on
17466 shadowregs
17467 \emph default
17468  instructs the code generator not to store/restore WREG, STATUS, BSR when
17469  entering/exiting the ISR.
17470 \layout Subsection
17471
17472 Function return values
17473 \layout Standard
17474
17475 Return values from functions are placed to the appropriate registers following
17476  a modified Microchip policy optimized for SDCC.
17477  The following table shows these registers:
17478 \layout Standard
17479 \align center
17480
17481 \begin_inset  Tabular
17482 <lyxtabular version="3" rows="6" columns="2">
17483 <features>
17484 <column alignment="center" valignment="top" leftline="true" width="0">
17485 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17486 <row topline="true" bottomline="true">
17487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17488 \begin_inset Text
17489
17490 \layout Standard
17491
17492 size
17493 \end_inset
17494 </cell>
17495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17496 \begin_inset Text
17497
17498 \layout Standard
17499
17500 destination register
17501 \end_inset
17502 </cell>
17503 </row>
17504 <row topline="true">
17505 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17506 \begin_inset Text
17507
17508 \layout Standard
17509
17510 8 bits
17511 \end_inset
17512 </cell>
17513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17514 \begin_inset Text
17515
17516 \layout Standard
17517
17518 WREG
17519 \end_inset
17520 </cell>
17521 </row>
17522 <row topline="true">
17523 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17524 \begin_inset Text
17525
17526 \layout Standard
17527
17528 16 bits
17529 \end_inset
17530 </cell>
17531 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17532 \begin_inset Text
17533
17534 \layout Standard
17535
17536 PRODL:WREG
17537 \end_inset
17538 </cell>
17539 </row>
17540 <row topline="true">
17541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17542 \begin_inset Text
17543
17544 \layout Standard
17545
17546 24 bits
17547 \end_inset
17548 </cell>
17549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17550 \begin_inset Text
17551
17552 \layout Standard
17553
17554 PRODH:PRODL:WREG
17555 \end_inset
17556 </cell>
17557 </row>
17558 <row topline="true">
17559 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17560 \begin_inset Text
17561
17562 \layout Standard
17563
17564 32 bits
17565 \end_inset
17566 </cell>
17567 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17568 \begin_inset Text
17569
17570 \layout Standard
17571
17572 FSR0L:PRODH:PRODL:WREG
17573 \end_inset
17574 </cell>
17575 </row>
17576 <row topline="true" bottomline="true">
17577 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17578 \begin_inset Text
17579
17580 \layout Standard
17581
17582 >32 bits
17583 \end_inset
17584 </cell>
17585 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17586 \begin_inset Text
17587
17588 \layout Standard
17589
17590 on stack, FSR0 points to the beginning
17591 \end_inset
17592 </cell>
17593 </row>
17594 </lyxtabular>
17595
17596 \end_inset
17597
17598
17599 \layout Subsection
17600
17601 Interrupts
17602 \layout Standard
17603
17604 An interrupt servive routine (ISR) is declared using the
17605 \emph on
17606 interrupt
17607 \emph default
17608  keyword.
17609 \layout LyX-Code
17610
17611 void isr(void) interrupt
17612 \emph on
17613 n
17614 \layout LyX-Code
17615
17616 {
17617 \layout LyX-Code
17618
17619 ...
17620 \layout LyX-Code
17621
17622 }
17623 \layout Standard
17624
17625
17626 \emph on
17627 n
17628 \emph default
17629  is the interrupt number, which for PIC18F devices can be:
17630 \layout Standard
17631 \align center
17632
17633 \begin_inset  Tabular
17634 <lyxtabular version="3" rows="4" columns="3">
17635 <features>
17636 <column alignment="center" valignment="top" leftline="true" width="0">
17637 <column alignment="center" valignment="top" leftline="true" width="0">
17638 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17639 <row topline="true" bottomline="true">
17640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17641 \begin_inset Text
17642
17643 \layout Standard
17644
17645
17646 \emph on
17647 n
17648 \end_inset
17649 </cell>
17650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17651 \begin_inset Text
17652
17653 \layout Standard
17654
17655 Interrupt Vector
17656 \end_inset
17657 </cell>
17658 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17659 \begin_inset Text
17660
17661 \layout Standard
17662
17663 Interrupt Vector Address
17664 \end_inset
17665 </cell>
17666 </row>
17667 <row topline="true">
17668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17669 \begin_inset Text
17670
17671 \layout Standard
17672
17673 0
17674 \end_inset
17675 </cell>
17676 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17677 \begin_inset Text
17678
17679 \layout Standard
17680
17681 RESET vector
17682 \end_inset
17683 </cell>
17684 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17685 \begin_inset Text
17686
17687 \layout Standard
17688
17689 0x000000
17690 \end_inset
17691 </cell>
17692 </row>
17693 <row topline="true">
17694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17695 \begin_inset Text
17696
17697 \layout Standard
17698
17699
17700 \family roman
17701 \series medium
17702 \shape up
17703 \size normal
17704 \emph off
17705 \bar no
17706 \noun off
17707 \color none
17708 1
17709 \end_inset
17710 </cell>
17711 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17712 \begin_inset Text
17713
17714 \layout Standard
17715
17716
17717 \family roman
17718 \series medium
17719 \shape up
17720 \size normal
17721 \emph off
17722 \bar no
17723 \noun off
17724 \color none
17725 HIGH priority interrupts
17726 \end_inset
17727 </cell>
17728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17729 \begin_inset Text
17730
17731 \layout Standard
17732
17733 0x000008
17734 \end_inset
17735 </cell>
17736 </row>
17737 <row topline="true" bottomline="true">
17738 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17739 \begin_inset Text
17740
17741 \layout Standard
17742
17743 2
17744 \end_inset
17745 </cell>
17746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17747 \begin_inset Text
17748
17749 \layout Standard
17750
17751 LOW priority interrupts
17752 \end_inset
17753 </cell>
17754 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17755 \begin_inset Text
17756
17757 \layout Standard
17758
17759 0x000018
17760 \end_inset
17761 </cell>
17762 </row>
17763 </lyxtabular>
17764
17765 \end_inset
17766
17767
17768 \layout Standard
17769
17770 When generating assembly code for ISR the code generator places a
17771 \noun on
17772 goto
17773 \noun default
17774 instruction at the
17775 \emph on
17776 Interrupt Vector Address
17777 \emph default
17778  which points at the genetated ISR.
17779  This single GOTO instruction is part of an automatically generated
17780 \emph on
17781 interrupt entry point
17782 \emph default
17783  function.
17784  The actuall ISR code is placed as normally would in the code space.
17785  Upon interrupt request, the GOTO instruction is executed which jumps to
17786  the ISR code.
17787  When declaring interrupt functions as _naked this GOTO instruction is
17788 \series bold
17789 not
17790 \series default
17791  generated.
17792  The whole interrupt functions is therefore placed at the Interrupt Vector
17793  Address of the specific interrupt.
17794  This is not a problem for the LOW priority interrupts, but it is a problem
17795  for the RESET and the HIGH priority interrupts because code may be written
17796  at the next interrupt´s vector address and cause undeterminate program
17797  behaviour if that interrupt is raised.
17798 \begin_inset Foot
17799 collapsed false
17800
17801 \layout Standard
17802
17803 This is not a problem when
17804 \layout Enumerate
17805
17806 this is a HIGH interrupt ISR and LOW interrupts are
17807 \emph on
17808 disabled
17809 \emph default
17810  or not used.
17811 \layout Enumerate
17812
17813 when the ISR is small enough not to reach the next interrupt´s vector address.
17814 \end_inset
17815
17816
17817 \layout Standard
17818
17819
17820 \emph on
17821 n
17822 \emph default
17823  is possible to be omitted.
17824  This way a function is generated similar to an ISR, but it is not assigned
17825  to any interrupt.
17826 \layout Standard
17827
17828 When entering an interrupt, currently the PIC16
17829 \begin_inset LatexCommand \index{PIC16}
17830
17831 \end_inset
17832
17833  port automatically saves the following registers:
17834 \layout Itemize
17835
17836 WREG
17837 \layout Itemize
17838
17839 STATUS
17840 \layout Itemize
17841
17842 BSR
17843 \layout Itemize
17844
17845 PROD (PRODL and PRODH)
17846 \layout Itemize
17847
17848 FSR0 (FSR0L and FSR0H)
17849 \layout Standard
17850
17851 These registers are restored upon return from the interrupt routine.
17852 \begin_inset Foot
17853 collapsed false
17854
17855 \layout Standard
17856
17857 NOTE that when the _naked attribute is specified for an interrupt routine,
17858  then NO registers are stored or restored.
17859 \end_inset
17860
17861
17862 \layout Subsection
17863
17864 Generic Pointers
17865 \layout Standard
17866
17867 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
17868  There are 3 types of generic pointers currently implemented data, code
17869  and eeprom pointers.
17870  They are differentiated by the value of the 7th and 6th bits of the upper
17871  byte:
17872 \layout Standard
17873 \align center
17874
17875 \begin_inset  Tabular
17876 <lyxtabular version="3" rows="5" columns="5">
17877 <features>
17878 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17879 <column alignment="center" valignment="top" width="0">
17880 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17881 <column alignment="center" valignment="top" width="0">
17882 <column alignment="left" valignment="top" rightline="true" width="0">
17883 <row topline="true" bottomline="true">
17884 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17885 \begin_inset Text
17886
17887 \layout Standard
17888
17889 pointer type
17890 \end_inset
17891 </cell>
17892 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17893 \begin_inset Text
17894
17895 \layout Standard
17896
17897 7th bit
17898 \end_inset
17899 </cell>
17900 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17901 \begin_inset Text
17902
17903 \layout Standard
17904
17905 6th bit
17906 \end_inset
17907 </cell>
17908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17909 \begin_inset Text
17910
17911 \layout Standard
17912
17913 rest of the pointer
17914 \end_inset
17915 </cell>
17916 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17917 \begin_inset Text
17918
17919 \layout Standard
17920
17921 descrption
17922 \end_inset
17923 </cell>
17924 </row>
17925 <row topline="true" bottomline="true">
17926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17927 \begin_inset Text
17928
17929 \layout Standard
17930
17931 data
17932 \end_inset
17933 </cell>
17934 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17935 \begin_inset Text
17936
17937 \layout Standard
17938
17939 1
17940 \end_inset
17941 </cell>
17942 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17943 \begin_inset Text
17944
17945 \layout Standard
17946
17947 0
17948 \end_inset
17949 </cell>
17950 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17951 \begin_inset Text
17952
17953 \layout Standard
17954
17955
17956 \family typewriter
17957 \shape slanted
17958 \emph on
17959 uuuuuu uuuuxxxx xxxxxxxx
17960 \end_inset
17961 </cell>
17962 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17963 \begin_inset Text
17964
17965 \layout Standard
17966
17967 a 12-bit data pointer in data RAM memory
17968 \end_inset
17969 </cell>
17970 </row>
17971 <row bottomline="true">
17972 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17973 \begin_inset Text
17974
17975 \layout Standard
17976
17977 code
17978 \end_inset
17979 </cell>
17980 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17981 \begin_inset Text
17982
17983 \layout Standard
17984
17985 0
17986 \end_inset
17987 </cell>
17988 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17989 \begin_inset Text
17990
17991 \layout Standard
17992
17993 0
17994 \end_inset
17995 </cell>
17996 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17997 \begin_inset Text
17998
17999 \layout Standard
18000
18001
18002 \family typewriter
18003 \shape slanted
18004 \emph on
18005 uxxxxx xxxxxxxx xxxxxxxx
18006 \end_inset
18007 </cell>
18008 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18009 \begin_inset Text
18010
18011 \layout Standard
18012
18013 a 21-bit code pointer in FLASH memory
18014 \end_inset
18015 </cell>
18016 </row>
18017 <row bottomline="true">
18018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18019 \begin_inset Text
18020
18021 \layout Standard
18022
18023 eeprom
18024 \end_inset
18025 </cell>
18026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18027 \begin_inset Text
18028
18029 \layout Standard
18030
18031 0
18032 \end_inset
18033 </cell>
18034 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18035 \begin_inset Text
18036
18037 \layout Standard
18038
18039 1
18040 \end_inset
18041 </cell>
18042 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18043 \begin_inset Text
18044
18045 \layout Standard
18046
18047
18048 \family typewriter
18049 \shape slanted
18050 \emph on
18051 uuuuuu uuuuuuxx xxxxxxxx
18052 \end_inset
18053 </cell>
18054 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18055 \begin_inset Text
18056
18057 \layout Standard
18058
18059 a 10-bit eeprom pointer in EEPROM memory
18060 \end_inset
18061 </cell>
18062 </row>
18063 <row bottomline="true">
18064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18065 \begin_inset Text
18066
18067 \layout Standard
18068
18069 (unimplemented)
18070 \end_inset
18071 </cell>
18072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18073 \begin_inset Text
18074
18075 \layout Standard
18076
18077 1
18078 \end_inset
18079 </cell>
18080 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18081 \begin_inset Text
18082
18083 \layout Standard
18084
18085 1
18086 \end_inset
18087 </cell>
18088 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18089 \begin_inset Text
18090
18091 \layout Standard
18092
18093
18094 \family typewriter
18095 \shape slanted
18096 \emph on
18097 xxxxxx xxxxxxxx xxxxxxxx
18098 \end_inset
18099 </cell>
18100 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18101 \begin_inset Text
18102
18103 \layout Standard
18104
18105 unimplemented pointer type
18106 \end_inset
18107 </cell>
18108 </row>
18109 </lyxtabular>
18110
18111 \end_inset
18112
18113
18114 \layout Standard
18115
18116 Generic pointer are read and written with a set of library functions which
18117  read/write 1, 2, 3, 4 bytes.
18118 \layout Subsection
18119
18120 PIC16 C Libraries
18121 \layout Subsubsection
18122
18123 Standard I/O Streams
18124 \layout Standard
18125
18126 In the
18127 \emph on
18128 stdio.h
18129 \emph default
18130  the type FILE is defined as:
18131 \layout LyX-Code
18132
18133 typedef char * FILE;
18134 \layout Standard
18135
18136 This type is the stream type implemented I/O in the PIC18F devices.
18137  Also the standard input and output streams are declared in stdio.h:
18138 \layout LyX-Code
18139
18140 extern FILE * stdin;
18141 \layout LyX-Code
18142
18143 extern FILE * stdout;
18144 \layout Standard
18145
18146 The FILE type is actually a generic pointer which defines one more type
18147  of generic pointers, the
18148 \emph on
18149 stream
18150 \emph default
18151 pointer.
18152  This new type has the format:
18153 \layout Standard
18154 \align center
18155
18156 \begin_inset  Tabular
18157 <lyxtabular version="3" rows="2" columns="7">
18158 <features>
18159 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18160 <column alignment="center" valignment="top" width="0">
18161 <column alignment="center" valignment="top" leftline="true" width="0">
18162 <column alignment="center" valignment="top" leftline="true" width="0">
18163 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18164 <column alignment="center" valignment="top" width="0">
18165 <column alignment="left" valignment="top" rightline="true" width="0">
18166 <row topline="true" bottomline="true">
18167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18168 \begin_inset Text
18169
18170 \layout Standard
18171
18172 pointer type
18173 \end_inset
18174 </cell>
18175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18176 \begin_inset Text
18177
18178 \layout Standard
18179
18180 <7:6>
18181 \end_inset
18182 </cell>
18183 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18184 \begin_inset Text
18185
18186 \layout Standard
18187
18188 <5>
18189 \end_inset
18190 </cell>
18191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18192 \begin_inset Text
18193
18194 \layout Standard
18195
18196 <4>
18197 \end_inset
18198 </cell>
18199 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18200 \begin_inset Text
18201
18202 \layout Standard
18203
18204 <3:0>
18205 \end_inset
18206 </cell>
18207 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18208 \begin_inset Text
18209
18210 \layout Standard
18211
18212 rest of the pointer
18213 \end_inset
18214 </cell>
18215 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18216 \begin_inset Text
18217
18218 \layout Standard
18219
18220 descrption
18221 \end_inset
18222 </cell>
18223 </row>
18224 <row topline="true" bottomline="true">
18225 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18226 \begin_inset Text
18227
18228 \layout Standard
18229
18230 stream
18231 \end_inset
18232 </cell>
18233 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18234 \begin_inset Text
18235
18236 \layout Standard
18237
18238 00
18239 \end_inset
18240 </cell>
18241 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18242 \begin_inset Text
18243
18244 \layout Standard
18245
18246 1
18247 \end_inset
18248 </cell>
18249 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18250 \begin_inset Text
18251
18252 \layout Standard
18253
18254 0
18255 \end_inset
18256 </cell>
18257 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18258 \begin_inset Text
18259
18260 \layout Standard
18261
18262 nnnn
18263 \end_inset
18264 </cell>
18265 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18266 \begin_inset Text
18267
18268 \layout Standard
18269
18270
18271 \family typewriter
18272 \shape slanted
18273 \emph on
18274 uuuuuuuu uuuuuuuu
18275 \end_inset
18276 </cell>
18277 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18278 \begin_inset Text
18279
18280 \layout Standard
18281
18282 upper byte high nubble is 0x2n, the rest are zeroes
18283 \end_inset
18284 </cell>
18285 </row>
18286 </lyxtabular>
18287
18288 \end_inset
18289
18290
18291 \layout Standard
18292
18293 Currently implemented there are 3 types of streams defined:
18294 \layout Standard
18295 \align center
18296
18297 \begin_inset  Tabular
18298 <lyxtabular version="3" rows="4" columns="4">
18299 <features>
18300 <column alignment="center" valignment="top" leftline="true" width="0">
18301 <column alignment="center" valignment="top" leftline="true" width="0">
18302 <column alignment="center" valignment="top" leftline="true" width="0">
18303 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18304 <row topline="true" bottomline="true">
18305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18306 \begin_inset Text
18307
18308 \layout Standard
18309
18310 stream type
18311 \end_inset
18312 </cell>
18313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18314 \begin_inset Text
18315
18316 \layout Standard
18317
18318 value
18319 \end_inset
18320 </cell>
18321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18322 \begin_inset Text
18323
18324 \layout Standard
18325
18326 module
18327 \end_inset
18328 </cell>
18329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18330 \begin_inset Text
18331
18332 \layout Standard
18333
18334 description
18335 \end_inset
18336 </cell>
18337 </row>
18338 <row topline="true">
18339 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18340 \begin_inset Text
18341
18342 \layout Standard
18343
18344 STREAM_USART
18345 \end_inset
18346 </cell>
18347 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18348 \begin_inset Text
18349
18350 \layout Standard
18351
18352
18353 \family typewriter
18354 0x200000UL
18355 \end_inset
18356 </cell>
18357 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18358 \begin_inset Text
18359
18360 \layout Standard
18361
18362 USART
18363 \end_inset
18364 </cell>
18365 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18366 \begin_inset Text
18367
18368 \layout Standard
18369
18370 Writes/Reads characters via the USART peripheral
18371 \end_inset
18372 </cell>
18373 </row>
18374 <row topline="true">
18375 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18376 \begin_inset Text
18377
18378 \layout Standard
18379
18380 STREAM_MSSP
18381 \end_inset
18382 </cell>
18383 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18384 \begin_inset Text
18385
18386 \layout Standard
18387
18388
18389 \family typewriter
18390 0x210000UL
18391 \end_inset
18392 </cell>
18393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18394 \begin_inset Text
18395
18396 \layout Standard
18397
18398 MSSP
18399 \end_inset
18400 </cell>
18401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18402 \begin_inset Text
18403
18404 \layout Standard
18405
18406 Writes/Reads characters via the MSSP peripheral
18407 \end_inset
18408 </cell>
18409 </row>
18410 <row topline="true" bottomline="true">
18411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18412 \begin_inset Text
18413
18414 \layout Standard
18415
18416 STREAM_USER
18417 \end_inset
18418 </cell>
18419 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18420 \begin_inset Text
18421
18422 \layout Standard
18423
18424
18425 \family typewriter
18426 0x2f0000UL
18427 \end_inset
18428 </cell>
18429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18430 \begin_inset Text
18431
18432 \layout Standard
18433
18434 (none)
18435 \end_inset
18436 </cell>
18437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18438 \begin_inset Text
18439
18440 \layout Standard
18441
18442 Writes/Reads characters via used defined functions
18443 \end_inset
18444 </cell>
18445 </row>
18446 </lyxtabular>
18447
18448 \end_inset
18449
18450
18451 \layout Standard
18452
18453 The stream identifiers are declared as macros in the stdio.h header.
18454 \layout Standard
18455
18456 In the libc library there exist the functions that are used to write to
18457  each of the above streams.
18458  These are
18459 \layout List
18460 \labelwidthstring 00.00.0000
18461
18462 _
18463 \begin_inset ERT
18464 status Collapsed
18465
18466 \layout Standard
18467
18468 \backslash
18469 /
18470 \end_inset
18471
18472 _stream_usart_putchar writes a character at the USART stream
18473 \layout List
18474 \labelwidthstring 00.00.0000
18475
18476 _
18477 \begin_inset ERT
18478 status Collapsed
18479
18480 \layout Standard
18481
18482 \backslash
18483 /
18484 \end_inset
18485
18486 _stream_mssp_putchar writes a character at the MSSP stream
18487 \layout List
18488 \labelwidthstring 00.00.0000
18489
18490 putchar dummy function.
18491  This writes a character to a user specified manner.
18492 \layout Standard
18493
18494 In order to increase performance
18495 \emph on
18496 putchar
18497 \emph default
18498 is declared in stdio.h as having its parameter in WREG (it has the wparam
18499  keyword).
18500  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
18501  in a user-friendly way.
18502
18503 \emph on
18504 arg
18505 \emph default
18506  is the name of the variable that holds the character to print.
18507  An example follows:
18508 \layout LyX-Code
18509
18510 #include <pic18fregs.h>
18511 \newline
18512 #include <stdio.h>
18513 \newline
18514
18515 \newline
18516 PUTCHAR( c )
18517 \layout LyX-Code
18518
18519 {
18520 \layout LyX-Code
18521
18522     PORTA = c;    /* dump character c to PORTA */
18523 \layout LyX-Code
18524
18525 }
18526 \newline
18527
18528 \newline
18529 void main(void)
18530 \layout LyX-Code
18531
18532 {
18533 \layout LyX-Code
18534
18535     stdout = STREAM_USER;    /* this is not necessery, since stdout points
18536 \layout LyX-Code
18537
18538                               * by default to STREAM_USER */
18539 \layout LyX-Code
18540
18541     printf (¨This is a printf test
18542 \backslash
18543 n¨);
18544 \layout LyX-Code
18545
18546 }
18547 \layout LyX-Code
18548
18549 \layout Subsubsection
18550
18551 Printing functions
18552 \layout Standard
18553
18554 PIC16 contains an implementation of the printf-family of functions.
18555  There exist the following functions:
18556 \layout LyX-Code
18557
18558 extern unsigned int sprintf(char *buf, char *fmt, ...);
18559 \layout LyX-Code
18560
18561 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
18562 \layout LyX-Code
18563
18564 \layout LyX-Code
18565
18566 extern unsigned int printf(char *fmt, ...);
18567 \layout LyX-Code
18568
18569 extern unsigned int vprintf(char *fmt, va_lista ap);
18570 \layout LyX-Code
18571
18572 \layout LyX-Code
18573
18574 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
18575 \layout LyX-Code
18576
18577 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
18578 \layout Standard
18579
18580 For sprintf and vsprintf
18581 \emph on
18582 buf
18583 \emph default
18584 should normally be a data pointer where the resulting string will be placed.
18585  No range checking is done so the user should allocate the necessery buffer.
18586  For fprintf and vfprintf
18587 \emph on
18588 fp
18589 \emph default
18590  should be a stream pointer (i.e.
18591  stdout, STREAM_MSSP, etc...).
18592 \layout Subsubsection
18593
18594 Signals
18595 \layout Standard
18596
18597 The PIC18F family of microcontrollers supports a number of interrupt sources.
18598  A list of these interrupts is shown in the following table:
18599 \layout Standard
18600 \align center
18601
18602 \begin_inset  Tabular
18603 <lyxtabular version="3" rows="11" columns="4">
18604 <features>
18605 <column alignment="left" valignment="top" leftline="true" width="0">
18606 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18607 <column alignment="left" valignment="top" leftline="true" width="0">
18608 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18609 <row topline="true" bottomline="true">
18610 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18611 \begin_inset Text
18612
18613 \layout Standard
18614
18615 signal name
18616 \end_inset
18617 </cell>
18618 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18619 \begin_inset Text
18620
18621 \layout Standard
18622
18623 description
18624 \end_inset
18625 </cell>
18626 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18627 \begin_inset Text
18628
18629 \layout Standard
18630
18631 signal name
18632 \end_inset
18633 </cell>
18634 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18635 \begin_inset Text
18636
18637 \layout Standard
18638
18639 descritpion
18640 \end_inset
18641 </cell>
18642 </row>
18643 <row topline="true">
18644 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18645 \begin_inset Text
18646
18647 \layout Standard
18648
18649 SIG_RB
18650 \end_inset
18651 </cell>
18652 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18653 \begin_inset Text
18654
18655 \layout Standard
18656
18657 PORTB change interrupt
18658 \end_inset
18659 </cell>
18660 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18661 \begin_inset Text
18662
18663 \layout Standard
18664
18665 SIG_EE
18666 \end_inset
18667 </cell>
18668 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18669 \begin_inset Text
18670
18671 \layout Standard
18672
18673 EEPROM/FLASH write complete interrupt
18674 \end_inset
18675 </cell>
18676 </row>
18677 <row topline="true">
18678 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18679 \begin_inset Text
18680
18681 \layout Standard
18682
18683 SIG_INT0
18684 \end_inset
18685 </cell>
18686 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18687 \begin_inset Text
18688
18689 \layout Standard
18690
18691 INT0 external interrupt
18692 \end_inset
18693 </cell>
18694 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18695 \begin_inset Text
18696
18697 \layout Standard
18698
18699 SIG_BCOL
18700 \end_inset
18701 </cell>
18702 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18703 \begin_inset Text
18704
18705 \layout Standard
18706
18707 Bus collision interrupt
18708 \end_inset
18709 </cell>
18710 </row>
18711 <row topline="true">
18712 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18713 \begin_inset Text
18714
18715 \layout Standard
18716
18717 SIG_INT1
18718 \end_inset
18719 </cell>
18720 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18721 \begin_inset Text
18722
18723 \layout Standard
18724
18725 INT1 external interrupt
18726 \end_inset
18727 </cell>
18728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18729 \begin_inset Text
18730
18731 \layout Standard
18732
18733 SIG_LVD
18734 \end_inset
18735 </cell>
18736 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18737 \begin_inset Text
18738
18739 \layout Standard
18740
18741 Low voltage detect interrupt
18742 \end_inset
18743 </cell>
18744 </row>
18745 <row topline="true">
18746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18747 \begin_inset Text
18748
18749 \layout Standard
18750
18751 SIG_INT2
18752 \end_inset
18753 </cell>
18754 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18755 \begin_inset Text
18756
18757 \layout Standard
18758
18759 INT2 external interrupt
18760 \end_inset
18761 </cell>
18762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18763 \begin_inset Text
18764
18765 \layout Standard
18766
18767 SIG_PSP
18768 \end_inset
18769 </cell>
18770 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18771 \begin_inset Text
18772
18773 \layout Standard
18774
18775 Parallel slave port interrupt
18776 \end_inset
18777 </cell>
18778 </row>
18779 <row topline="true">
18780 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18781 \begin_inset Text
18782
18783 \layout Standard
18784
18785 SIG_CCP1
18786 \end_inset
18787 </cell>
18788 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18789 \begin_inset Text
18790
18791 \layout Standard
18792
18793 CCP1 module interrupt
18794 \end_inset
18795 </cell>
18796 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18797 \begin_inset Text
18798
18799 \layout Standard
18800
18801 SIG_AD
18802 \end_inset
18803 </cell>
18804 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18805 \begin_inset Text
18806
18807 \layout Standard
18808
18809 AD convertion complete interrupt
18810 \end_inset
18811 </cell>
18812 </row>
18813 <row topline="true">
18814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18815 \begin_inset Text
18816
18817 \layout Standard
18818
18819 SIG_CCP2
18820 \end_inset
18821 </cell>
18822 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18823 \begin_inset Text
18824
18825 \layout Standard
18826
18827 CCP2 module interrupt
18828 \end_inset
18829 </cell>
18830 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18831 \begin_inset Text
18832
18833 \layout Standard
18834
18835 SIG_RC
18836 \end_inset
18837 </cell>
18838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18839 \begin_inset Text
18840
18841 \layout Standard
18842
18843 USART receive interrupt
18844 \end_inset
18845 </cell>
18846 </row>
18847 <row topline="true">
18848 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18849 \begin_inset Text
18850
18851 \layout Standard
18852
18853 SIG_TMR0
18854 \end_inset
18855 </cell>
18856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18857 \begin_inset Text
18858
18859 \layout Standard
18860
18861 TMR0 overflow interrupt
18862 \end_inset
18863 </cell>
18864 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18865 \begin_inset Text
18866
18867 \layout Standard
18868
18869 SIG_TX
18870 \end_inset
18871 </cell>
18872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18873 \begin_inset Text
18874
18875 \layout Standard
18876
18877 USART transmit interrupt
18878 \end_inset
18879 </cell>
18880 </row>
18881 <row topline="true">
18882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18883 \begin_inset Text
18884
18885 \layout Standard
18886
18887 SIG_TMR1
18888 \end_inset
18889 </cell>
18890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18891 \begin_inset Text
18892
18893 \layout Standard
18894
18895 TMR1 overflow interrupt
18896 \end_inset
18897 </cell>
18898 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18899 \begin_inset Text
18900
18901 \layout Standard
18902
18903 SIG_MSSP
18904 \end_inset
18905 </cell>
18906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18907 \begin_inset Text
18908
18909 \layout Standard
18910
18911 SSP receive/transmit interrupt
18912 \end_inset
18913 </cell>
18914 </row>
18915 <row topline="true">
18916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18917 \begin_inset Text
18918
18919 \layout Standard
18920
18921 SIG_TMR2
18922 \end_inset
18923 </cell>
18924 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18925 \begin_inset Text
18926
18927 \layout Standard
18928
18929 TMR2 matches PR2 interrupt
18930 \end_inset
18931 </cell>
18932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18933 \begin_inset Text
18934
18935 \layout Standard
18936
18937 \end_inset
18938 </cell>
18939 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18940 \begin_inset Text
18941
18942 \layout Standard
18943
18944 \end_inset
18945 </cell>
18946 </row>
18947 <row topline="true" bottomline="true">
18948 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18949 \begin_inset Text
18950
18951 \layout Standard
18952
18953 SIG_TMR3
18954 \end_inset
18955 </cell>
18956 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18957 \begin_inset Text
18958
18959 \layout Standard
18960
18961 TMR3 overflow interrupt
18962 \end_inset
18963 </cell>
18964 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18965 \begin_inset Text
18966
18967 \layout Standard
18968
18969 \end_inset
18970 </cell>
18971 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18972 \begin_inset Text
18973
18974 \layout Standard
18975
18976 \end_inset
18977 </cell>
18978 </row>
18979 </lyxtabular>
18980
18981 \end_inset
18982
18983
18984 \layout Standard
18985
18986 The prototypes for these names are defined in the header file
18987 \emph on
18988 signal.h
18989 \emph default
18990  .
18991 \layout Standard
18992
18993 In order to simplify signal handling, a number of macros is provided:
18994 \layout List
18995 \labelwidthstring 00.00.0000
18996
18997 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
18998  high priority interrupts.
18999
19000 \emph on
19001 name
19002 \emph default
19003  is the function name to use.
19004 \layout List
19005 \labelwidthstring 00.00.0000
19006
19007 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
19008  low priority interrupt.
19009
19010 \emph on
19011 name
19012 \emph default
19013  is the function name to use.
19014 \layout List
19015 \labelwidthstring 00.00.0000
19016
19017 DEF_HANDLER(sig,handler) define a handler for signal
19018 \emph on
19019 sig.
19020 \layout List
19021 \labelwidthstring 00.00.0000
19022
19023 END_DEF end the declaration of the dispatch table.
19024 \layout Standard
19025
19026 Additionally there are two more macros to simplify the declaration of the
19027  signal handler:
19028 \layout List
19029 \labelwidthstring 00.00.0000
19030
19031
19032 \series medium
19033 SIGHANDLER(handler)
19034 \series default
19035 this declares the function prototype for the
19036 \emph on
19037 handler
19038 \emph default
19039  function.
19040 \layout List
19041 \labelwidthstring 00.00.0000
19042
19043 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
19044 \layout Standard
19045
19046 An example of using the macros above is shown below:
19047 \layout LyX-Code
19048
19049 #include <pic18fregs.h>
19050 \layout LyX-Code
19051
19052 #include <signal.h>
19053 \newline
19054
19055 \newline
19056 DEF_INTHIGH(high_int)
19057 \layout LyX-Code
19058
19059 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
19060 \layout LyX-Code
19061
19062 DEF_HANDLER(SIG_BCOL, _bcol_handler)
19063 \layout LyX-Code
19064
19065 END_DEF
19066 \newline
19067
19068 \newline
19069 SIGHANDLER(_tmr0_handler)
19070 \layout LyX-Code
19071
19072 {
19073 \layout LyX-Code
19074
19075   /* action to be taken when timer 0 overflows */
19076 \layout LyX-Code
19077
19078 }
19079 \newline
19080
19081 \newline
19082 SIGHANDLERNAKED(_bcol_handler)
19083 \layout LyX-Code
19084
19085 {
19086 \layout LyX-Code
19087
19088   _asm
19089 \layout LyX-Code
19090
19091     /* action to be taken when bus collision occurs */
19092 \layout LyX-Code
19093
19094     retfie
19095 \layout LyX-Code
19096
19097  _endasm;
19098 \layout LyX-Code
19099
19100 }
19101 \layout Standard
19102
19103
19104 \series bold
19105 NOTES:
19106 \series default
19107  Special care should be taken when using the above scheme:
19108 \layout Itemize
19109
19110 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
19111 \layout Itemize
19112
19113 when declaring SIGHANDLERNAKED handler never forget to use
19114 \emph on
19115 retfie
19116 \emph default
19117  for proper returning.
19118 \layout Subsection
19119
19120 PIC16 Port -- Tips
19121 \layout Standard
19122
19123 Here you can find some general tips for compiling programs with SDCC/pic16.
19124 \layout Subsubsection
19125
19126 Stack size
19127 \layout Standard
19128
19129 The default stack size (that is 64 bytes) probably is enough for many programs.
19130  One must take care that when there are many levels of function nesting,
19131  or there is excessive usage of stack, its size should be extended.
19132  An example of such a case is the printf/sprintf family of functions.
19133  If you encounter problems like not being able to print integers, then you
19134  need to set the stack size around the maximum (256 for small stack model).
19135  The following diagram shows what happens when calling printf to print an
19136  integer:
19137 \layout LyX-Code
19138
19139 printf () --> ltoa () --> ultoa () --> divschar ()
19140 \layout Standard
19141
19142 It is should be understood that stack is easily consumed when calling complicate
19143 d functions.
19144  Using command line arguments like -
19145 \begin_inset ERT
19146 status Collapsed
19147
19148 \layout Standard
19149
19150 \backslash
19151 /
19152 \end_inset
19153
19154 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
19155  stack frames.
19156  Other ways to reduce stack usage may exist.
19157 \layout Chapter
19158
19159 Debugging with SDCDB
19160 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
19161
19162 \end_inset
19163
19164
19165 \begin_inset LatexCommand \index{sdcdb (debugger)}
19166
19167 \end_inset
19168
19169
19170 \layout Standard
19171
19172 SDCC is distributed with a source level debugger
19173 \begin_inset LatexCommand \index{Debugger}
19174
19175 \end_inset
19176
19177 .
19178  The debugger uses a command line interface, the command repertoire of the
19179  debugger has been kept as close to gdb
19180 \begin_inset LatexCommand \index{gdb}
19181
19182 \end_inset
19183
19184  (the GNU debugger) as possible.
19185  The configuration and build process is part of the standard compiler installati
19186 on, which also builds and installs the debugger in the target directory
19187  specified during configuration.
19188  The debugger allows you debug BOTH at the C source and at the ASM source
19189  level.
19190  Sdcdb is available on Unix platforms only.
19191 \layout Section
19192
19193 Compiling for Debugging
19194 \layout Standard
19195
19196 The -
19197 \begin_inset ERT
19198 status Collapsed
19199
19200 \layout Standard
19201
19202 \backslash
19203 /
19204 \end_inset
19205
19206 -debug
19207 \begin_inset LatexCommand \index{-\/-debug}
19208
19209 \end_inset
19210
19211  option must be specified for all files for which debug information is to
19212  be generated.
19213  The complier generates a .adb file for each of these files.
19214  The linker creates the .cdb
19215 \begin_inset LatexCommand \index{<file>.cdb}
19216
19217 \end_inset
19218
19219  file from the .adb
19220 \begin_inset LatexCommand \index{<file>.adb}
19221
19222 \end_inset
19223
19224  files and the address information.
19225  This .cdb is used by the debugger.
19226 \layout Section
19227
19228 How the Debugger Works
19229 \layout Standard
19230
19231 When the -
19232 \begin_inset ERT
19233 status Collapsed
19234
19235 \layout Standard
19236
19237 \backslash
19238 /
19239 \end_inset
19240
19241 -debug option is specified the compiler generates extra symbol information
19242  some of which are put into the assembler source and some are put into the
19243  .adb file.
19244   Then the linker creates the .cdb file from the individual .adb files with
19245  the address information for the symbols.
19246  The debugger reads the symbolic information generated by the compiler &
19247  the address information generated by the linker.
19248  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
19249  execution is controlled by the debugger.
19250  When a command is issued for the debugger, it translates it into appropriate
19251  commands for the simulator.
19252 \layout Section
19253
19254 Starting the Debugger
19255 \layout Standard
19256
19257 The debugger can be started using the following command line.
19258  (Assume the file you are debugging has the file name foo).
19259 \newline
19260
19261 \newline
19262
19263 \family sans
19264 \series bold
19265 sdcdb foo
19266 \newline
19267
19268 \family default
19269 \series default
19270
19271 \newline
19272 The debugger will look for the following files.
19273 \layout Itemize
19274
19275 foo.c - the source file.
19276 \layout Itemize
19277
19278 foo.cdb - the debugger symbol information file.
19279 \layout Itemize
19280
19281 foo.ihx - the Intel hex format
19282 \begin_inset LatexCommand \index{Intel hex format}
19283
19284 \end_inset
19285
19286  object file.
19287 \layout Section
19288
19289 Command Line Options.
19290 \layout Itemize
19291
19292 -
19293 \begin_inset ERT
19294 status Collapsed
19295
19296 \layout Standard
19297
19298 \backslash
19299 /
19300 \end_inset
19301
19302 -directory=<source file directory> this option can used to specify the directory
19303  search list.
19304  The debugger will look into the directory list specified for source, cdb
19305  & ihx files.
19306  The items in the directory list must be separated by ':', e.g.
19307  if the source files can be in the directories /home/src1 and /home/src2,
19308  the -
19309 \begin_inset ERT
19310 status Collapsed
19311
19312 \layout Standard
19313
19314 \backslash
19315 /
19316 \end_inset
19317
19318 -directory option should be -
19319 \begin_inset ERT
19320 status Collapsed
19321
19322 \layout Standard
19323
19324 \backslash
19325 /
19326 \end_inset
19327
19328 -directory=/home/src1:/home/src2.
19329  Note there can be no spaces in the option.
19330
19331 \layout Itemize
19332
19333 -cd <directory> - change to the <directory>.
19334 \layout Itemize
19335
19336 -fullname - used by GUI front ends.
19337 \layout Itemize
19338
19339 -cpu <cpu-type> - this argument is passed to the simulator please see the
19340  simulator docs for details.
19341 \layout Itemize
19342
19343 -X <Clock frequency > this options is passed to the simulator please see
19344  the simulator docs for details.
19345 \layout Itemize
19346
19347 -s <serial port file> passed to simulator see the simulator docs for details.
19348 \layout Itemize
19349
19350 -S <serial in,out> passed to simulator see the simulator docs for details.
19351 \layout Itemize
19352
19353 -k <port number> passed to simulator see the simulator docs for details.
19354 \layout Section
19355
19356 Debugger Commands.
19357 \layout Standard
19358
19359 As mentioned earlier the command interface for the debugger has been deliberatel
19360 y kept as close the GNU debugger gdb, as possible.
19361  This will help the integration with existing graphical user interfaces
19362  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
19363  If you use a graphical user interface for the debugger you can skip the
19364  next sections.
19365 \layout Subsubsection*
19366
19367 break [line | file:line | function | file:function]
19368 \layout Standard
19369
19370 Set breakpoint at specified line or function:
19371 \newline
19372
19373 \newline
19374
19375 \family sans
19376 \series bold
19377 sdcdb>break 100
19378 \newline
19379 sdcdb>break foo.c:100
19380 \newline
19381 sdcdb>break funcfoo
19382 \newline
19383 sdcdb>break foo.c:funcfoo
19384 \layout Subsubsection*
19385
19386 clear [line | file:line | function | file:function ]
19387 \layout Standard
19388
19389 Clear breakpoint at specified line or function:
19390 \newline
19391
19392 \newline
19393
19394 \family sans
19395 \series bold
19396 sdcdb>clear 100
19397 \newline
19398 sdcdb>clear foo.c:100
19399 \newline
19400 sdcdb>clear funcfoo
19401 \newline
19402 sdcdb>clear foo.c:funcfoo
19403 \layout Subsubsection*
19404
19405 continue
19406 \layout Standard
19407
19408 Continue program being debugged, after breakpoint.
19409 \layout Subsubsection*
19410
19411 finish
19412 \layout Standard
19413
19414 Execute till the end of the current function.
19415 \layout Subsubsection*
19416
19417 delete [n]
19418 \layout Standard
19419
19420 Delete breakpoint number 'n'.
19421  If used without any option clear ALL user defined break points.
19422 \layout Subsubsection*
19423
19424 info [break | stack | frame | registers ]
19425 \layout Itemize
19426
19427 info break - list all breakpoints
19428 \layout Itemize
19429
19430 info stack - show the function call stack.
19431 \layout Itemize
19432
19433 info frame - show information about the current execution frame.
19434 \layout Itemize
19435
19436 info registers - show content of all registers.
19437 \layout Subsubsection*
19438
19439 step
19440 \layout Standard
19441
19442 Step program until it reaches a different source line.
19443  Note: pressing <return> repeats the last command.
19444 \layout Subsubsection*
19445
19446 next
19447 \layout Standard
19448
19449 Step program, proceeding through subroutine calls.
19450 \layout Subsubsection*
19451
19452 run
19453 \layout Standard
19454
19455 Start debugged program.
19456 \layout Subsubsection*
19457
19458 ptype variable
19459 \layout Standard
19460
19461 Print type information of the variable.
19462 \layout Subsubsection*
19463
19464 print variable
19465 \layout Standard
19466
19467 print value of variable.
19468 \layout Subsubsection*
19469
19470 file filename
19471 \layout Standard
19472
19473 load the given file name.
19474  Note this is an alternate method of loading file for debugging.
19475 \layout Subsubsection*
19476
19477 frame
19478 \layout Standard
19479
19480 print information about current frame.
19481 \layout Subsubsection*
19482
19483 set srcmode
19484 \layout Standard
19485
19486 Toggle between C source & assembly source.
19487 \layout Subsubsection*
19488
19489 ! simulator command
19490 \layout Standard
19491
19492 Send the string following '!' to the simulator, the simulator response is
19493  displayed.
19494  Note the debugger does not interpret the command being sent to the simulator,
19495  so if a command like 'go' is sent the debugger can loose its execution
19496  context and may display incorrect values.
19497 \layout Subsubsection*
19498
19499 quit
19500 \layout Standard
19501
19502 "Watch me now.
19503  Iam going Down.
19504  My name is Bobby Brown"
19505 \layout Section
19506
19507 Interfacing with XEmacs
19508 \begin_inset LatexCommand \index{XEmacs}
19509
19510 \end_inset
19511
19512
19513 \begin_inset LatexCommand \index{Emacs}
19514
19515 \end_inset
19516
19517 .
19518 \layout Standard
19519
19520 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
19521  sdcdb.el and sdcdbsrc.el.
19522  These two files can be found in the $(prefix)/bin directory after the installat
19523 ion is complete.
19524  These files need to be loaded into XEmacs for the interface to work.
19525  This can be done at XEmacs startup time by inserting the following into
19526  your '.xemacs' file (which can be found in your HOME directory):
19527 \newline
19528
19529 \newline
19530
19531 \family typewriter
19532 (load-file sdcdbsrc.el)
19533 \family default
19534
19535 \newline
19536
19537 \newline
19538 .xemacs is a lisp file so the () around the command is REQUIRED.
19539  The files can also be loaded dynamically while XEmacs is running, set the
19540  environment variable 'EMACSLOADPATH' to the installation bin directory
19541  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
19542  To start the interface enter the following command:
19543 \newline
19544
19545 \newline
19546
19547 \family sans
19548 \series bold
19549 ESC-x sdcdbsrc
19550 \family default
19551 \series default
19552
19553 \newline
19554
19555 \newline
19556 You will prompted to enter the file name to be debugged.
19557
19558 \newline
19559
19560 \newline
19561 The command line options that are passed to the simulator directly are bound
19562  to default values in the file sdcdbsrc.el.
19563  The variables are listed below, these values maybe changed as required.
19564 \layout Itemize
19565
19566 sdcdbsrc-cpu-type '51
19567 \layout Itemize
19568
19569 sdcdbsrc-frequency '11059200
19570 \layout Itemize
19571
19572 sdcdbsrc-serial nil
19573 \layout Standard
19574
19575 The following is a list of key mapping for the debugger interface.
19576 \layout Standard
19577
19578 \SpecialChar ~
19579
19580 \family typewriter
19581
19582 \newline
19583 ;;\SpecialChar ~
19584 Current Listing ::
19585 \newline
19586 ;;key\SpecialChar ~
19587 \SpecialChar ~
19588 \SpecialChar ~
19589 \SpecialChar ~
19590 \SpecialChar ~
19591 \SpecialChar ~
19592 \SpecialChar ~
19593 \SpecialChar ~
19594 \SpecialChar ~
19595 \SpecialChar ~
19596 \SpecialChar ~
19597 \SpecialChar ~
19598 \SpecialChar ~
19599 \SpecialChar ~
19600 binding\SpecialChar ~
19601 \SpecialChar ~
19602 \SpecialChar ~
19603 \SpecialChar ~
19604 \SpecialChar ~
19605 \SpecialChar ~
19606 \SpecialChar ~
19607 \SpecialChar ~
19608 \SpecialChar ~
19609 \SpecialChar ~
19610 \SpecialChar ~
19611 \SpecialChar ~
19612 \SpecialChar ~
19613 \SpecialChar ~
19614 \SpecialChar ~
19615 \SpecialChar ~
19616 \SpecialChar ~
19617 \SpecialChar ~
19618 \SpecialChar ~
19619 \SpecialChar ~
19620 \SpecialChar ~
19621 \SpecialChar ~
19622 Comment
19623 \newline
19624 ;;---\SpecialChar ~
19625 \SpecialChar ~
19626 \SpecialChar ~
19627 \SpecialChar ~
19628 \SpecialChar ~
19629 \SpecialChar ~
19630 \SpecialChar ~
19631 \SpecialChar ~
19632 \SpecialChar ~
19633 \SpecialChar ~
19634 \SpecialChar ~
19635 \SpecialChar ~
19636 \SpecialChar ~
19637 \SpecialChar ~
19638 -------\SpecialChar ~
19639 \SpecialChar ~
19640 \SpecialChar ~
19641 \SpecialChar ~
19642 \SpecialChar ~
19643 \SpecialChar ~
19644 \SpecialChar ~
19645 \SpecialChar ~
19646 \SpecialChar ~
19647 \SpecialChar ~
19648 \SpecialChar ~
19649 \SpecialChar ~
19650 \SpecialChar ~
19651 \SpecialChar ~
19652 \SpecialChar ~
19653 \SpecialChar ~
19654 \SpecialChar ~
19655 \SpecialChar ~
19656 \SpecialChar ~
19657 \SpecialChar ~
19658 \SpecialChar ~
19659 \SpecialChar ~
19660 -------
19661 \newline
19662 ;;
19663 \newline
19664 ;;\SpecialChar ~
19665 n\SpecialChar ~
19666 \SpecialChar ~
19667 \SpecialChar ~
19668 \SpecialChar ~
19669 \SpecialChar ~
19670 \SpecialChar ~
19671 \SpecialChar ~
19672 \SpecialChar ~
19673 \SpecialChar ~
19674 \SpecialChar ~
19675 \SpecialChar ~
19676 \SpecialChar ~
19677 \SpecialChar ~
19678 \SpecialChar ~
19679 \SpecialChar ~
19680 sdcdb-next-from-src\SpecialChar ~
19681 \SpecialChar ~
19682 \SpecialChar ~
19683 \SpecialChar ~
19684 \SpecialChar ~
19685 \SpecialChar ~
19686 \SpecialChar ~
19687 \SpecialChar ~
19688 \SpecialChar ~
19689 \SpecialChar ~
19690 SDCDB next command
19691 \newline
19692 ;;\SpecialChar ~
19693 b\SpecialChar ~
19694 \SpecialChar ~
19695 \SpecialChar ~
19696 \SpecialChar ~
19697 \SpecialChar ~
19698 \SpecialChar ~
19699 \SpecialChar ~
19700 \SpecialChar ~
19701 \SpecialChar ~
19702 \SpecialChar ~
19703 \SpecialChar ~
19704 \SpecialChar ~
19705 \SpecialChar ~
19706 \SpecialChar ~
19707 \SpecialChar ~
19708 sdcdb-back-from-src\SpecialChar ~
19709 \SpecialChar ~
19710 \SpecialChar ~
19711 \SpecialChar ~
19712 \SpecialChar ~
19713 \SpecialChar ~
19714 \SpecialChar ~
19715 \SpecialChar ~
19716 \SpecialChar ~
19717 \SpecialChar ~
19718 SDCDB back command
19719 \newline
19720 ;;\SpecialChar ~
19721 c\SpecialChar ~
19722 \SpecialChar ~
19723 \SpecialChar ~
19724 \SpecialChar ~
19725 \SpecialChar ~
19726 \SpecialChar ~
19727 \SpecialChar ~
19728 \SpecialChar ~
19729 \SpecialChar ~
19730 \SpecialChar ~
19731 \SpecialChar ~
19732 \SpecialChar ~
19733 \SpecialChar ~
19734 \SpecialChar ~
19735 \SpecialChar ~
19736 sdcdb-cont-from-src\SpecialChar ~
19737 \SpecialChar ~
19738 \SpecialChar ~
19739 \SpecialChar ~
19740 \SpecialChar ~
19741 \SpecialChar ~
19742 \SpecialChar ~
19743 \SpecialChar ~
19744 \SpecialChar ~
19745 \SpecialChar ~
19746 SDCDB continue command
19747 \newline
19748 ;;\SpecialChar ~
19749 s\SpecialChar ~
19750 \SpecialChar ~
19751 \SpecialChar ~
19752 \SpecialChar ~
19753 \SpecialChar ~
19754 \SpecialChar ~
19755 \SpecialChar ~
19756 \SpecialChar ~
19757 \SpecialChar ~
19758 \SpecialChar ~
19759 \SpecialChar ~
19760 \SpecialChar ~
19761 \SpecialChar ~
19762 \SpecialChar ~
19763 \SpecialChar ~
19764 sdcdb-step-from-src\SpecialChar ~
19765 \SpecialChar ~
19766 \SpecialChar ~
19767 \SpecialChar ~
19768 \SpecialChar ~
19769 \SpecialChar ~
19770 \SpecialChar ~
19771 \SpecialChar ~
19772 \SpecialChar ~
19773 \SpecialChar ~
19774 SDCDB step command
19775 \newline
19776 ;;\SpecialChar ~
19777 ?\SpecialChar ~
19778 \SpecialChar ~
19779 \SpecialChar ~
19780 \SpecialChar ~
19781 \SpecialChar ~
19782 \SpecialChar ~
19783 \SpecialChar ~
19784 \SpecialChar ~
19785 \SpecialChar ~
19786 \SpecialChar ~
19787 \SpecialChar ~
19788 \SpecialChar ~
19789 \SpecialChar ~
19790 \SpecialChar ~
19791 \SpecialChar ~
19792 sdcdb-whatis-c-sexp\SpecialChar ~
19793 \SpecialChar ~
19794 \SpecialChar ~
19795 \SpecialChar ~
19796 \SpecialChar ~
19797 \SpecialChar ~
19798 \SpecialChar ~
19799 \SpecialChar ~
19800 \SpecialChar ~
19801 \SpecialChar ~
19802 SDCDB ptypecommand for data at
19803 \newline
19804 ;;\SpecialChar ~
19805 \SpecialChar ~
19806 \SpecialChar ~
19807 \SpecialChar ~
19808 \SpecialChar ~
19809 \SpecialChar ~
19810 \SpecialChar ~
19811 \SpecialChar ~
19812 \SpecialChar ~
19813 \SpecialChar ~
19814 \SpecialChar ~
19815 \SpecialChar ~
19816 \SpecialChar ~
19817 \SpecialChar ~
19818 \SpecialChar ~
19819 \SpecialChar ~
19820 \SpecialChar ~
19821 \SpecialChar ~
19822 \SpecialChar ~
19823 \SpecialChar ~
19824 \SpecialChar ~
19825 \SpecialChar ~
19826 \SpecialChar ~
19827 \SpecialChar ~
19828 \SpecialChar ~
19829 \SpecialChar ~
19830 \SpecialChar ~
19831 \SpecialChar ~
19832 \SpecialChar ~
19833 \SpecialChar ~
19834 \SpecialChar ~
19835 \SpecialChar ~
19836 \SpecialChar ~
19837 \SpecialChar ~
19838 \SpecialChar ~
19839 \SpecialChar ~
19840 \SpecialChar ~
19841 \SpecialChar ~
19842 \SpecialChar ~
19843 \SpecialChar ~
19844 \SpecialChar ~
19845 \SpecialChar ~
19846 \SpecialChar ~
19847 \SpecialChar ~
19848 \SpecialChar ~
19849 \SpecialChar ~
19850 \SpecialChar ~
19851 buffer point
19852 \newline
19853 ;;\SpecialChar ~
19854 x\SpecialChar ~
19855 \SpecialChar ~
19856 \SpecialChar ~
19857 \SpecialChar ~
19858 \SpecialChar ~
19859 \SpecialChar ~
19860 \SpecialChar ~
19861 \SpecialChar ~
19862 \SpecialChar ~
19863 \SpecialChar ~
19864 \SpecialChar ~
19865 \SpecialChar ~
19866 \SpecialChar ~
19867 \SpecialChar ~
19868 \SpecialChar ~
19869 sdcdbsrc-delete\SpecialChar ~
19870 \SpecialChar ~
19871 \SpecialChar ~
19872 \SpecialChar ~
19873 \SpecialChar ~
19874 \SpecialChar ~
19875 \SpecialChar ~
19876 \SpecialChar ~
19877 \SpecialChar ~
19878 \SpecialChar ~
19879 \SpecialChar ~
19880 \SpecialChar ~
19881 \SpecialChar ~
19882 \SpecialChar ~
19883 SDCDB Delete all breakpoints if no arg
19884 \newline
19885 ;;\SpecialChar ~
19886 \SpecialChar ~
19887 \SpecialChar ~
19888 \SpecialChar ~
19889 \SpecialChar ~
19890 \SpecialChar ~
19891 \SpecialChar ~
19892 \SpecialChar ~
19893 \SpecialChar ~
19894 \SpecialChar ~
19895 \SpecialChar ~
19896 \SpecialChar ~
19897 \SpecialChar ~
19898 \SpecialChar ~
19899 \SpecialChar ~
19900 \SpecialChar ~
19901 \SpecialChar ~
19902 \SpecialChar ~
19903 \SpecialChar ~
19904 \SpecialChar ~
19905 \SpecialChar ~
19906 \SpecialChar ~
19907 \SpecialChar ~
19908 \SpecialChar ~
19909 \SpecialChar ~
19910 \SpecialChar ~
19911 \SpecialChar ~
19912 \SpecialChar ~
19913 \SpecialChar ~
19914 \SpecialChar ~
19915 \SpecialChar ~
19916 \SpecialChar ~
19917 \SpecialChar ~
19918 \SpecialChar ~
19919 \SpecialChar ~
19920 \SpecialChar ~
19921 \SpecialChar ~
19922 \SpecialChar ~
19923 \SpecialChar ~
19924 \SpecialChar ~
19925 \SpecialChar ~
19926 \SpecialChar ~
19927 \SpecialChar ~
19928 \SpecialChar ~
19929 \SpecialChar ~
19930 \SpecialChar ~
19931 \SpecialChar ~
19932 given or delete arg (C-u arg x)
19933 \newline
19934 ;;\SpecialChar ~
19935 m\SpecialChar ~
19936 \SpecialChar ~
19937 \SpecialChar ~
19938 \SpecialChar ~
19939 \SpecialChar ~
19940 \SpecialChar ~
19941 \SpecialChar ~
19942 \SpecialChar ~
19943 \SpecialChar ~
19944 \SpecialChar ~
19945 \SpecialChar ~
19946 \SpecialChar ~
19947 \SpecialChar ~
19948 \SpecialChar ~
19949 \SpecialChar ~
19950 sdcdbsrc-frame\SpecialChar ~
19951 \SpecialChar ~
19952 \SpecialChar ~
19953 \SpecialChar ~
19954 \SpecialChar ~
19955 \SpecialChar ~
19956 \SpecialChar ~
19957 \SpecialChar ~
19958 \SpecialChar ~
19959 \SpecialChar ~
19960 \SpecialChar ~
19961 \SpecialChar ~
19962 \SpecialChar ~
19963 \SpecialChar ~
19964 \SpecialChar ~
19965 SDCDB Display current frame if no arg,
19966 \newline
19967 ;;\SpecialChar ~
19968 \SpecialChar ~
19969 \SpecialChar ~
19970 \SpecialChar ~
19971 \SpecialChar ~
19972 \SpecialChar ~
19973 \SpecialChar ~
19974 \SpecialChar ~
19975 \SpecialChar ~
19976 \SpecialChar ~
19977 \SpecialChar ~
19978 \SpecialChar ~
19979 \SpecialChar ~
19980 \SpecialChar ~
19981 \SpecialChar ~
19982 \SpecialChar ~
19983 \SpecialChar ~
19984 \SpecialChar ~
19985 \SpecialChar ~
19986 \SpecialChar ~
19987 \SpecialChar ~
19988 \SpecialChar ~
19989 \SpecialChar ~
19990 \SpecialChar ~
19991 \SpecialChar ~
19992 \SpecialChar ~
19993 \SpecialChar ~
19994 \SpecialChar ~
19995 \SpecialChar ~
19996 \SpecialChar ~
19997 \SpecialChar ~
19998 \SpecialChar ~
19999 \SpecialChar ~
20000 \SpecialChar ~
20001 \SpecialChar ~
20002 \SpecialChar ~
20003 \SpecialChar ~
20004 \SpecialChar ~
20005 \SpecialChar ~
20006 \SpecialChar ~
20007 \SpecialChar ~
20008 \SpecialChar ~
20009 \SpecialChar ~
20010 \SpecialChar ~
20011 \SpecialChar ~
20012 \SpecialChar ~
20013 \SpecialChar ~
20014 given or display frame arg
20015 \newline
20016 ;;\SpecialChar ~
20017 \SpecialChar ~
20018 \SpecialChar ~
20019 \SpecialChar ~
20020 \SpecialChar ~
20021 \SpecialChar ~
20022 \SpecialChar ~
20023 \SpecialChar ~
20024 \SpecialChar ~
20025 \SpecialChar ~
20026 \SpecialChar ~
20027 \SpecialChar ~
20028 \SpecialChar ~
20029 \SpecialChar ~
20030 \SpecialChar ~
20031 \SpecialChar ~
20032 \SpecialChar ~
20033 \SpecialChar ~
20034 \SpecialChar ~
20035 \SpecialChar ~
20036 \SpecialChar ~
20037 \SpecialChar ~
20038 \SpecialChar ~
20039 \SpecialChar ~
20040 \SpecialChar ~
20041 \SpecialChar ~
20042 \SpecialChar ~
20043 \SpecialChar ~
20044 \SpecialChar ~
20045 \SpecialChar ~
20046 \SpecialChar ~
20047 \SpecialChar ~
20048 \SpecialChar ~
20049 \SpecialChar ~
20050 \SpecialChar ~
20051 \SpecialChar ~
20052 \SpecialChar ~
20053 \SpecialChar ~
20054 \SpecialChar ~
20055 \SpecialChar ~
20056 \SpecialChar ~
20057 \SpecialChar ~
20058 \SpecialChar ~
20059 \SpecialChar ~
20060 \SpecialChar ~
20061 \SpecialChar ~
20062 \SpecialChar ~
20063 buffer point
20064 \newline
20065 ;;\SpecialChar ~
20066 !\SpecialChar ~
20067 \SpecialChar ~
20068 \SpecialChar ~
20069 \SpecialChar ~
20070 \SpecialChar ~
20071 \SpecialChar ~
20072 \SpecialChar ~
20073 \SpecialChar ~
20074 \SpecialChar ~
20075 \SpecialChar ~
20076 \SpecialChar ~
20077 \SpecialChar ~
20078 \SpecialChar ~
20079 \SpecialChar ~
20080 \SpecialChar ~
20081 sdcdbsrc-goto-sdcdb\SpecialChar ~
20082 \SpecialChar ~
20083 \SpecialChar ~
20084 \SpecialChar ~
20085 \SpecialChar ~
20086 \SpecialChar ~
20087 \SpecialChar ~
20088 \SpecialChar ~
20089 \SpecialChar ~
20090 \SpecialChar ~
20091 Goto the SDCDB output buffer
20092 \newline
20093 ;;\SpecialChar ~
20094 p\SpecialChar ~
20095 \SpecialChar ~
20096 \SpecialChar ~
20097 \SpecialChar ~
20098 \SpecialChar ~
20099 \SpecialChar ~
20100 \SpecialChar ~
20101 \SpecialChar ~
20102 \SpecialChar ~
20103 \SpecialChar ~
20104 \SpecialChar ~
20105 \SpecialChar ~
20106 \SpecialChar ~
20107 \SpecialChar ~
20108 \SpecialChar ~
20109 sdcdb-print-c-sexp\SpecialChar ~
20110 \SpecialChar ~
20111 \SpecialChar ~
20112 \SpecialChar ~
20113 \SpecialChar ~
20114 \SpecialChar ~
20115 \SpecialChar ~
20116 \SpecialChar ~
20117 \SpecialChar ~
20118 \SpecialChar ~
20119 \SpecialChar ~
20120 SDCDB print command for data at
20121 \newline
20122 ;;\SpecialChar ~
20123 \SpecialChar ~
20124 \SpecialChar ~
20125 \SpecialChar ~
20126 \SpecialChar ~
20127 \SpecialChar ~
20128 \SpecialChar ~
20129 \SpecialChar ~
20130 \SpecialChar ~
20131 \SpecialChar ~
20132 \SpecialChar ~
20133 \SpecialChar ~
20134 \SpecialChar ~
20135 \SpecialChar ~
20136 \SpecialChar ~
20137 \SpecialChar ~
20138 \SpecialChar ~
20139 \SpecialChar ~
20140 \SpecialChar ~
20141 \SpecialChar ~
20142 \SpecialChar ~
20143 \SpecialChar ~
20144 \SpecialChar ~
20145 \SpecialChar ~
20146 \SpecialChar ~
20147 \SpecialChar ~
20148 \SpecialChar ~
20149 \SpecialChar ~
20150 \SpecialChar ~
20151 \SpecialChar ~
20152 \SpecialChar ~
20153 \SpecialChar ~
20154 \SpecialChar ~
20155 \SpecialChar ~
20156 \SpecialChar ~
20157 \SpecialChar ~
20158 \SpecialChar ~
20159 \SpecialChar ~
20160 \SpecialChar ~
20161 \SpecialChar ~
20162 \SpecialChar ~
20163 \SpecialChar ~
20164 \SpecialChar ~
20165 \SpecialChar ~
20166 \SpecialChar ~
20167 \SpecialChar ~
20168 \SpecialChar ~
20169 buffer point
20170 \newline
20171 ;;\SpecialChar ~
20172 g\SpecialChar ~
20173 \SpecialChar ~
20174 \SpecialChar ~
20175 \SpecialChar ~
20176 \SpecialChar ~
20177 \SpecialChar ~
20178 \SpecialChar ~
20179 \SpecialChar ~
20180 \SpecialChar ~
20181 \SpecialChar ~
20182 \SpecialChar ~
20183 \SpecialChar ~
20184 \SpecialChar ~
20185 \SpecialChar ~
20186 \SpecialChar ~
20187 sdcdbsrc-goto-sdcdb\SpecialChar ~
20188 \SpecialChar ~
20189 \SpecialChar ~
20190 \SpecialChar ~
20191 \SpecialChar ~
20192 \SpecialChar ~
20193 \SpecialChar ~
20194 \SpecialChar ~
20195 \SpecialChar ~
20196 \SpecialChar ~
20197 Goto the SDCDB output buffer
20198 \newline
20199 ;;\SpecialChar ~
20200 t\SpecialChar ~
20201 \SpecialChar ~
20202 \SpecialChar ~
20203 \SpecialChar ~
20204 \SpecialChar ~
20205 \SpecialChar ~
20206 \SpecialChar ~
20207 \SpecialChar ~
20208 \SpecialChar ~
20209 \SpecialChar ~
20210 \SpecialChar ~
20211 \SpecialChar ~
20212 \SpecialChar ~
20213 \SpecialChar ~
20214 \SpecialChar ~
20215 sdcdbsrc-mode\SpecialChar ~
20216 \SpecialChar ~
20217 \SpecialChar ~
20218 \SpecialChar ~
20219 \SpecialChar ~
20220 \SpecialChar ~
20221 \SpecialChar ~
20222 \SpecialChar ~
20223 \SpecialChar ~
20224 \SpecialChar ~
20225 \SpecialChar ~
20226 \SpecialChar ~
20227 \SpecialChar ~
20228 \SpecialChar ~
20229 \SpecialChar ~
20230 \SpecialChar ~
20231 Toggles Sdcdbsrc mode (turns it off)
20232 \newline
20233 ;;
20234 \newline
20235 ;;\SpecialChar ~
20236 C-c\SpecialChar ~
20237 C-f\SpecialChar ~
20238 \SpecialChar ~
20239 \SpecialChar ~
20240 \SpecialChar ~
20241 \SpecialChar ~
20242 \SpecialChar ~
20243 \SpecialChar ~
20244 \SpecialChar ~
20245 \SpecialChar ~
20246 sdcdb-finish-from-src\SpecialChar ~
20247 \SpecialChar ~
20248 \SpecialChar ~
20249 \SpecialChar ~
20250 \SpecialChar ~
20251 \SpecialChar ~
20252 \SpecialChar ~
20253 \SpecialChar ~
20254 SDCDB finish command
20255 \newline
20256 ;;
20257 \newline
20258 ;;\SpecialChar ~
20259 C-x\SpecialChar ~
20260 SPC\SpecialChar ~
20261 \SpecialChar ~
20262 \SpecialChar ~
20263 \SpecialChar ~
20264 \SpecialChar ~
20265 \SpecialChar ~
20266 \SpecialChar ~
20267 \SpecialChar ~
20268 \SpecialChar ~
20269 sdcdb-break\SpecialChar ~
20270 \SpecialChar ~
20271 \SpecialChar ~
20272 \SpecialChar ~
20273 \SpecialChar ~
20274 \SpecialChar ~
20275 \SpecialChar ~
20276 \SpecialChar ~
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 \SpecialChar ~
20282 \SpecialChar ~
20283 \SpecialChar ~
20284 \SpecialChar ~
20285 \SpecialChar ~
20286 \SpecialChar ~
20287 Set break for line with point
20288 \newline
20289 ;;\SpecialChar ~
20290 ESC\SpecialChar ~
20291 t\SpecialChar ~
20292 \SpecialChar ~
20293 \SpecialChar ~
20294 \SpecialChar ~
20295 \SpecialChar ~
20296 \SpecialChar ~
20297 \SpecialChar ~
20298 \SpecialChar ~
20299 \SpecialChar ~
20300 \SpecialChar ~
20301 \SpecialChar ~
20302 sdcdbsrc-mode\SpecialChar ~
20303 \SpecialChar ~
20304 \SpecialChar ~
20305 \SpecialChar ~
20306 \SpecialChar ~
20307 \SpecialChar ~
20308 \SpecialChar ~
20309 \SpecialChar ~
20310 \SpecialChar ~
20311 \SpecialChar ~
20312 \SpecialChar ~
20313 \SpecialChar ~
20314 \SpecialChar ~
20315 \SpecialChar ~
20316 \SpecialChar ~
20317 \SpecialChar ~
20318 Toggle Sdcdbsrc mode
20319 \newline
20320 ;;\SpecialChar ~
20321 ESC\SpecialChar ~
20322 m\SpecialChar ~
20323 \SpecialChar ~
20324 \SpecialChar ~
20325 \SpecialChar ~
20326 \SpecialChar ~
20327 \SpecialChar ~
20328 \SpecialChar ~
20329 \SpecialChar ~
20330 \SpecialChar ~
20331 \SpecialChar ~
20332 \SpecialChar ~
20333 sdcdbsrc-srcmode\SpecialChar ~
20334 \SpecialChar ~
20335 \SpecialChar ~
20336 \SpecialChar ~
20337 \SpecialChar ~
20338 \SpecialChar ~
20339 \SpecialChar ~
20340 \SpecialChar ~
20341 \SpecialChar ~
20342 \SpecialChar ~
20343 \SpecialChar ~
20344 \SpecialChar ~
20345 \SpecialChar ~
20346 Toggle list mode
20347 \newline
20348 ;;
20349 \newline
20350
20351 \layout Chapter
20352 \pagebreak_top
20353 TIPS
20354 \layout Standard
20355
20356 Here are a few guidelines that will help the compiler generate more efficient
20357  code, some of the tips are specific to this compiler others are generally
20358  good programming practice.
20359 \layout Itemize
20360
20361 Use the smallest data type to represent your data-value.
20362  If it is known in advance that the value is going to be less than 256 then
20363  use an 'unsigned char' instead of a 'short' or 'int'.
20364  Please note, that ANSI C requires both signed and unsigned chars to be
20365  promoted to 'signed int' before doing any operation.
20366  This promotion can be omitted, if the result is the same.
20367  The effect of the promotion rules together with the sign-extension is often
20368  surprising:
20369 \begin_deeper
20370 \layout Verse
20371
20372
20373 \family typewriter
20374 unsigned char uc = 0xfe;
20375 \newline
20376 if (uc * uc < 0) /* this is true! */
20377 \newline
20378 {
20379 \newline
20380 \SpecialChar ~
20381 \SpecialChar ~
20382 \SpecialChar ~
20383 \SpecialChar ~
20384 ....
20385 \newline
20386 }
20387 \layout Standard
20388
20389
20390 \family typewriter
20391 uc * uc
20392 \family default
20393  is evaluated as
20394 \family typewriter
20395 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
20396 \family default
20397 .
20398
20399 \newline
20400 Another one:
20401 \layout Verse
20402
20403
20404 \family typewriter
20405 (unsigned char) -12 / (signed char) -3 = ...
20406 \layout Standard
20407
20408 No, the result is not 4:
20409 \layout Verse
20410
20411
20412 \family typewriter
20413 (int) (unsigned char) -12 / (int) (signed char) -3 =
20414 \newline
20415 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
20416 \newline
20417 (int) 0x00f4 / (int) 0xfffd =
20418 \newline
20419 (int) 0x00f4 / (int) 0xfffd =
20420 \newline
20421 (int) 244 / (int) -3 =
20422 \newline
20423 (int) -81 = (int) 0xffaf;
20424 \layout Standard
20425
20426 Don't complain, that gcc gives you a different result.
20427  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
20428  Therefore the results are different.
20429 \newline
20430 From
20431 \begin_inset Quotes sld
20432 \end_inset
20433
20434 comp.lang.c FAQ
20435 \begin_inset Quotes srd
20436 \end_inset
20437
20438 :
20439 \layout Quote
20440
20441 If well-defined overflow characteristics are important and negative values
20442  are not, or if you want to steer clear of sign-extension problems when
20443  manipulating bits or bytes, use one of the corresponding unsigned types.
20444  (Beware when mixing signed and unsigned values in expressions, though.)
20445 \newline
20446 Although character types (especially unsigned char) can be used as "tiny"
20447  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
20448 ble sign extension and increased code size.
20449 \end_deeper
20450 \layout Itemize
20451
20452 Use unsigned when it is known in advance that the value is not going to
20453  be negative.
20454  This helps especially if you are doing division or multiplication, bit-shifting
20455  or are using an array index.
20456 \layout Itemize
20457
20458 NEVER jump into a LOOP.
20459 \layout Itemize
20460
20461 Declare the variables to be local
20462 \begin_inset LatexCommand \index{local variables}
20463
20464 \end_inset
20465
20466  whenever possible, especially loop control variables (induction).
20467 \layout Itemize
20468
20469 Since the compiler does not always do implicit integral promotion, the programme
20470 r should do an explicit cast when integral promotion is required.
20471 \layout Itemize
20472
20473 Reducing the size of division, multiplication & modulus operations can reduce
20474  code size substantially.
20475  Take the following code for example.
20476 \begin_deeper
20477 \layout Verse
20478
20479
20480 \family typewriter
20481 foobar(unsigned int p1, unsigned char ch)
20482 \newline
20483 {
20484 \newline
20485 \SpecialChar ~
20486 \SpecialChar ~
20487 \SpecialChar ~
20488 \SpecialChar ~
20489 unsigned char ch1 = p1 % ch ;
20490 \newline
20491 \SpecialChar ~
20492 \SpecialChar ~
20493 \SpecialChar ~
20494 \SpecialChar ~
20495 ....
20496 \newline
20497 }
20498 \layout Standard
20499
20500 For the modulus operation the variable ch will be promoted to unsigned int
20501  first then the modulus operation will be performed (this will lead to a
20502  call to support routine _moduint()), and the result will be casted to a
20503  char.
20504  If the code is changed to
20505 \layout Verse
20506
20507
20508 \family typewriter
20509 foobar(unsigned int p1, unsigned char ch)
20510 \newline
20511 {
20512 \newline
20513 \SpecialChar ~
20514 \SpecialChar ~
20515 \SpecialChar ~
20516 \SpecialChar ~
20517 unsigned char ch1 = (unsigned char)p1 % ch ;
20518 \newline
20519 \SpecialChar ~
20520 \SpecialChar ~
20521 \SpecialChar ~
20522 \SpecialChar ~
20523 ....
20524 \newline
20525 }
20526 \layout Standard
20527
20528 It would substantially reduce the code generated (future versions of the
20529  compiler will be smart enough to detect such optimization opportunities).
20530 \end_deeper
20531 \layout Itemize
20532
20533 Have a look at the assembly listing to get a
20534 \begin_inset Quotes sld
20535 \end_inset
20536
20537 feeling
20538 \begin_inset Quotes srd
20539 \end_inset
20540
20541  for the code generation.
20542 \layout Section
20543
20544 Tools
20545 \begin_inset LatexCommand \index{Tools}
20546
20547 \end_inset
20548
20549  included in the distribution
20550 \layout Standard
20551 \align center
20552
20553 \begin_inset  Tabular
20554 <lyxtabular version="3" rows="12" columns="3">
20555 <features>
20556 <column alignment="center" valignment="top" leftline="true" width="0pt">
20557 <column alignment="center" valignment="top" leftline="true" width="0pt">
20558 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
20559 <row topline="true" bottomline="true">
20560 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20561 \begin_inset Text
20562
20563 \layout Standard
20564
20565 Name
20566 \end_inset
20567 </cell>
20568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20569 \begin_inset Text
20570
20571 \layout Standard
20572
20573 Purpose
20574 \end_inset
20575 </cell>
20576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20577 \begin_inset Text
20578
20579 \layout Standard
20580
20581 Directory
20582 \end_inset
20583 </cell>
20584 </row>
20585 <row topline="true">
20586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20587 \begin_inset Text
20588
20589 \layout Standard
20590
20591 uCsim
20592 \end_inset
20593 </cell>
20594 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20595 \begin_inset Text
20596
20597 \layout Standard
20598
20599 Simulator for various architectures
20600 \end_inset
20601 </cell>
20602 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20603 \begin_inset Text
20604
20605 \layout Standard
20606
20607 sdcc/sim/ucsim
20608 \end_inset
20609 </cell>
20610 </row>
20611 <row topline="true">
20612 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20613 \begin_inset Text
20614
20615 \layout Standard
20616
20617 keil2sdcc.pl
20618 \end_inset
20619 </cell>
20620 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20621 \begin_inset Text
20622
20623 \layout Standard
20624
20625 header file conversion
20626 \end_inset
20627 </cell>
20628 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20629 \begin_inset Text
20630
20631 \layout Standard
20632
20633 sdcc/support/scripts
20634 \end_inset
20635 </cell>
20636 </row>
20637 <row topline="true">
20638 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20639 \begin_inset Text
20640
20641 \layout Standard
20642
20643 mh2h.c
20644 \end_inset
20645 </cell>
20646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20647 \begin_inset Text
20648
20649 \layout Standard
20650
20651 header file conversion
20652 \end_inset
20653 </cell>
20654 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20655 \begin_inset Text
20656
20657 \layout Standard
20658
20659 sdcc/support/scripts
20660 \end_inset
20661 </cell>
20662 </row>
20663 <row topline="true">
20664 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20665 \begin_inset Text
20666
20667 \layout Standard
20668
20669 as-gbz80
20670 \end_inset
20671 </cell>
20672 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20673 \begin_inset Text
20674
20675 \layout Standard
20676
20677 Assembler
20678 \end_inset
20679 </cell>
20680 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20681 \begin_inset Text
20682
20683 \layout Standard
20684
20685
20686 \family roman
20687 \series medium
20688 \shape up
20689 \size normal
20690 \emph off
20691 \bar no
20692 \noun off
20693 \color none
20694 sdcc/bin
20695 \end_inset
20696 </cell>
20697 </row>
20698 <row topline="true">
20699 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20700 \begin_inset Text
20701
20702 \layout Standard
20703
20704 as-z80
20705 \end_inset
20706 </cell>
20707 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20708 \begin_inset Text
20709
20710 \layout Standard
20711
20712 Assembler
20713 \end_inset
20714 </cell>
20715 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20716 \begin_inset Text
20717
20718 \layout Standard
20719
20720
20721 \family roman
20722 \series medium
20723 \shape up
20724 \size normal
20725 \emph off
20726 \bar no
20727 \noun off
20728 \color none
20729 sdcc/bin
20730 \end_inset
20731 </cell>
20732 </row>
20733 <row topline="true">
20734 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20735 \begin_inset Text
20736
20737 \layout Standard
20738
20739 asx8051
20740 \end_inset
20741 </cell>
20742 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20743 \begin_inset Text
20744
20745 \layout Standard
20746
20747 Assembler
20748 \end_inset
20749 </cell>
20750 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20751 \begin_inset Text
20752
20753 \layout Standard
20754
20755
20756 \family roman
20757 \series medium
20758 \shape up
20759 \size normal
20760 \emph off
20761 \bar no
20762 \noun off
20763 \color none
20764 sdcc/bin
20765 \end_inset
20766 </cell>
20767 </row>
20768 <row topline="true">
20769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20770 \begin_inset Text
20771
20772 \layout Standard
20773
20774 sdcdb
20775 \end_inset
20776 </cell>
20777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20778 \begin_inset Text
20779
20780 \layout Standard
20781
20782 Simulator
20783 \end_inset
20784 </cell>
20785 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20786 \begin_inset Text
20787
20788 \layout Standard
20789
20790
20791 \family roman
20792 \series medium
20793 \shape up
20794 \size normal
20795 \emph off
20796 \bar no
20797 \noun off
20798 \color none
20799 sdcc/bin
20800 \end_inset
20801 </cell>
20802 </row>
20803 <row topline="true">
20804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20805 \begin_inset Text
20806
20807 \layout Standard
20808
20809 aslink
20810 \end_inset
20811 </cell>
20812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20813 \begin_inset Text
20814
20815 \layout Standard
20816
20817 Linker
20818 \end_inset
20819 </cell>
20820 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20821 \begin_inset Text
20822
20823 \layout Standard
20824
20825
20826 \family roman
20827 \series medium
20828 \shape up
20829 \size normal
20830 \emph off
20831 \bar no
20832 \noun off
20833 \color none
20834 sdcc/bin
20835 \end_inset
20836 </cell>
20837 </row>
20838 <row topline="true">
20839 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20840 \begin_inset Text
20841
20842 \layout Standard
20843
20844 link-z80
20845 \end_inset
20846 </cell>
20847 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20848 \begin_inset Text
20849
20850 \layout Standard
20851
20852 Linker
20853 \end_inset
20854 </cell>
20855 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20856 \begin_inset Text
20857
20858 \layout Standard
20859
20860
20861 \family roman
20862 \series medium
20863 \shape up
20864 \size normal
20865 \emph off
20866 \bar no
20867 \noun off
20868 \color none
20869 sdcc/bin
20870 \end_inset
20871 </cell>
20872 </row>
20873 <row topline="true">
20874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20875 \begin_inset Text
20876
20877 \layout Standard
20878
20879 link-gbz80
20880 \end_inset
20881 </cell>
20882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20883 \begin_inset Text
20884
20885 \layout Standard
20886
20887 Linker
20888 \end_inset
20889 </cell>
20890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20891 \begin_inset Text
20892
20893 \layout Standard
20894
20895
20896 \family roman
20897 \series medium
20898 \shape up
20899 \size normal
20900 \emph off
20901 \bar no
20902 \noun off
20903 \color none
20904 sdcc/bin
20905 \end_inset
20906 </cell>
20907 </row>
20908 <row topline="true" bottomline="true">
20909 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20910 \begin_inset Text
20911
20912 \layout Standard
20913
20914 packihx
20915 \end_inset
20916 </cell>
20917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20918 \begin_inset Text
20919
20920 \layout Standard
20921
20922 ihx packer
20923 \end_inset
20924 </cell>
20925 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20926 \begin_inset Text
20927
20928 \layout Standard
20929
20930
20931 \family roman
20932 \series medium
20933 \shape up
20934 \size normal
20935 \emph off
20936 \bar no
20937 \noun off
20938 \color none
20939 sdcc/bin
20940 \end_inset
20941 </cell>
20942 </row>
20943 </lyxtabular>
20944
20945 \end_inset
20946
20947
20948 \newline
20949
20950 \layout Section
20951
20952 Documentation
20953 \begin_inset LatexCommand \index{Documentation}
20954
20955 \end_inset
20956
20957  included in the distribution
20958 \layout Standard
20959 \align center
20960
20961 \begin_inset  Tabular
20962 <lyxtabular version="3" rows="10" columns="2">
20963 <features>
20964 <column alignment="left" valignment="top" leftline="true" width="0">
20965 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
20966 <row topline="true" bottomline="true">
20967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20968 \begin_inset Text
20969
20970 \layout Standard
20971
20972 Subject / Title
20973 \end_inset
20974 </cell>
20975 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20976 \begin_inset Text
20977
20978 \layout Standard
20979
20980 Where to get / filename
20981 \end_inset
20982 </cell>
20983 </row>
20984 <row topline="true">
20985 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20986 \begin_inset Text
20987
20988 \layout Standard
20989
20990 SDCC Compiler User Guide
20991 \end_inset
20992 </cell>
20993 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20994 \begin_inset Text
20995
20996 \layout Standard
20997
20998 You're reading it right now
20999 \end_inset
21000 </cell>
21001 </row>
21002 <row topline="true">
21003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21004 \begin_inset Text
21005
21006 \layout Standard
21007
21008 Changelog of SDCC
21009 \end_inset
21010 </cell>
21011 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21012 \begin_inset Text
21013
21014 \layout Standard
21015
21016 sdcc/Changelog
21017 \end_inset
21018 </cell>
21019 </row>
21020 <row topline="true">
21021 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21022 \begin_inset Text
21023
21024 \layout Standard
21025
21026 ASXXXX
21027 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
21028
21029 \end_inset
21030
21031
21032 \begin_inset LatexCommand \index{Assembler documentation}
21033
21034 \end_inset
21035
21036  Assemblers and ASLINK
21037 \begin_inset LatexCommand \index{aslink}
21038
21039 \end_inset
21040
21041
21042 \begin_inset LatexCommand \index{Linker documentation}
21043
21044 \end_inset
21045
21046  Relocating Linker
21047 \end_inset
21048 </cell>
21049 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21050 \begin_inset Text
21051
21052 \layout Standard
21053
21054 sdcc/as/doc/asxhtm.html
21055 \end_inset
21056 </cell>
21057 </row>
21058 <row topline="true">
21059 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21060 \begin_inset Text
21061
21062 \layout Standard
21063
21064 SDCC regression test
21065 \begin_inset LatexCommand \index{Regression test}
21066
21067 \end_inset
21068
21069
21070 \end_inset
21071 </cell>
21072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21073 \begin_inset Text
21074
21075 \layout Standard
21076
21077 sdcc/doc/test_suite_spec.pdf
21078 \end_inset
21079 </cell>
21080 </row>
21081 <row topline="true">
21082 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21083 \begin_inset Text
21084
21085 \layout Standard
21086
21087 Various notes
21088 \end_inset
21089 </cell>
21090 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21091 \begin_inset Text
21092
21093 \layout Standard
21094
21095 sdcc/doc/*
21096 \end_inset
21097 </cell>
21098 </row>
21099 <row topline="true">
21100 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21101 \begin_inset Text
21102
21103 \layout Standard
21104
21105 Notes on debugging with sdcdb
21106 \begin_inset LatexCommand \index{sdcdb (debugger)}
21107
21108 \end_inset
21109
21110
21111 \end_inset
21112 </cell>
21113 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21114 \begin_inset Text
21115
21116 \layout Standard
21117
21118 sdcc/debugger/README
21119 \end_inset
21120 </cell>
21121 </row>
21122 <row topline="true">
21123 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21124 \begin_inset Text
21125
21126 \layout Standard
21127
21128 Software simulator for microcontrollers
21129 \end_inset
21130 </cell>
21131 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21132 \begin_inset Text
21133
21134 \layout Standard
21135
21136
21137 \family roman
21138 \series medium
21139 \shape up
21140 \size normal
21141 \emph off
21142 \bar no
21143 \noun off
21144 \color none
21145 sdcc/sim/ucsim/doc
21146 \family default
21147 \series default
21148 \shape default
21149 \size default
21150 \emph default
21151 \bar default
21152 \noun default
21153 \color default
21154 /index.html
21155 \end_inset
21156 </cell>
21157 </row>
21158 <row topline="true">
21159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21160 \begin_inset Text
21161
21162 \layout Standard
21163
21164 Temporary notes on the pic16
21165 \begin_inset LatexCommand \index{PIC16}
21166
21167 \end_inset
21168
21169  port
21170 \end_inset
21171 </cell>
21172 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21173 \begin_inset Text
21174
21175 \layout Standard
21176
21177 sdcc/src/pic16/NOTES
21178 \end_inset
21179 </cell>
21180 </row>
21181 <row topline="true" bottomline="true">
21182 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21183 \begin_inset Text
21184
21185 \layout Standard
21186
21187 SDCC internal documentation (debugging file format)
21188 \end_inset
21189 </cell>
21190 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21191 \begin_inset Text
21192
21193 \layout Standard
21194
21195 sdcc/doc/
21196 \family roman
21197 \series medium
21198 \shape up
21199 \size normal
21200 \emph off
21201 \bar no
21202 \noun off
21203 \color none
21204 cdbfileformat.pd
21205 \family default
21206 \series default
21207 \shape default
21208 \size default
21209 \emph default
21210 \bar default
21211 \noun default
21212 \color default
21213 f
21214 \end_inset
21215 </cell>
21216 </row>
21217 </lyxtabular>
21218
21219 \end_inset
21220
21221
21222 \newline
21223
21224 \layout Section
21225
21226 Related open source tools
21227 \begin_inset LatexCommand \index{Related tools}
21228
21229 \end_inset
21230
21231
21232 \layout Standard
21233 \align center
21234
21235 \begin_inset  Tabular
21236 <lyxtabular version="3" rows="11" columns="3">
21237 <features>
21238 <column alignment="center" valignment="top" leftline="true" width="0pt">
21239 <column alignment="block" valignment="top" leftline="true" width="30line%">
21240 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
21241 <row topline="true" bottomline="true">
21242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21243 \begin_inset Text
21244
21245 \layout Standard
21246
21247 Name
21248 \end_inset
21249 </cell>
21250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21251 \begin_inset Text
21252
21253 \layout Standard
21254
21255 Purpose
21256 \end_inset
21257 </cell>
21258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21259 \begin_inset Text
21260
21261 \layout Standard
21262
21263 Where to get
21264 \end_inset
21265 </cell>
21266 </row>
21267 <row topline="true">
21268 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21269 \begin_inset Text
21270
21271 \layout Standard
21272
21273 gpsim
21274 \begin_inset LatexCommand \index{gpsim (pic simulator)}
21275
21276 \end_inset
21277
21278
21279 \end_inset
21280 </cell>
21281 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21282 \begin_inset Text
21283
21284 \layout Standard
21285
21286 PIC simulator
21287 \end_inset
21288 </cell>
21289 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21290 \begin_inset Text
21291
21292 \layout Standard
21293
21294
21295 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
21296
21297 \end_inset
21298
21299
21300 \end_inset
21301 </cell>
21302 </row>
21303 <row topline="true">
21304 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21305 \begin_inset Text
21306
21307 \layout Standard
21308
21309 gputils
21310 \begin_inset LatexCommand \index{gputils (pic tools)}
21311
21312 \end_inset
21313
21314
21315 \end_inset
21316 </cell>
21317 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21318 \begin_inset Text
21319
21320 \layout Standard
21321
21322 GNU PIC utilities
21323 \end_inset
21324 </cell>
21325 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21326 \begin_inset Text
21327
21328 \layout Standard
21329
21330
21331 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
21332
21333 \end_inset
21334
21335
21336 \end_inset
21337 </cell>
21338 </row>
21339 <row topline="true">
21340 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21341 \begin_inset Text
21342
21343 \layout Standard
21344
21345 flP5
21346 \end_inset
21347 </cell>
21348 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21349 \begin_inset Text
21350
21351 \layout Standard
21352
21353 PIC programmer
21354 \end_inset
21355 </cell>
21356 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21357 \begin_inset Text
21358
21359 \layout Standard
21360
21361
21362 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
21363
21364 \end_inset
21365
21366
21367 \end_inset
21368 </cell>
21369 </row>
21370 <row topline="true">
21371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21372 \begin_inset Text
21373
21374 \layout Standard
21375
21376 indent
21377 \begin_inset LatexCommand \index{indent (source formatting tool)}
21378
21379 \end_inset
21380
21381
21382 \end_inset
21383 </cell>
21384 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21385 \begin_inset Text
21386
21387 \layout Standard
21388
21389 Formats C source - Master of the white spaces
21390 \end_inset
21391 </cell>
21392 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21393 \begin_inset Text
21394
21395 \layout Standard
21396
21397
21398 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
21399
21400 \end_inset
21401
21402
21403 \end_inset
21404 </cell>
21405 </row>
21406 <row topline="true">
21407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21408 \begin_inset Text
21409
21410 \layout Standard
21411
21412 srecord
21413 \begin_inset LatexCommand \index{srecord (tool)}
21414
21415 \end_inset
21416
21417
21418 \end_inset
21419 </cell>
21420 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21421 \begin_inset Text
21422
21423 \layout Standard
21424
21425 Object file conversion, checksumming, ...
21426 \end_inset
21427 </cell>
21428 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21429 \begin_inset Text
21430
21431 \layout Standard
21432
21433
21434 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
21435
21436 \end_inset
21437
21438
21439 \end_inset
21440 </cell>
21441 </row>
21442 <row topline="true">
21443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21444 \begin_inset Text
21445
21446 \layout Standard
21447
21448 objdump
21449 \begin_inset LatexCommand \index{objdump (tool)}
21450
21451 \end_inset
21452
21453
21454 \end_inset
21455 </cell>
21456 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21457 \begin_inset Text
21458
21459 \layout Standard
21460
21461 Object file conversion, ...
21462 \end_inset
21463 </cell>
21464 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21465 \begin_inset Text
21466
21467 \layout Standard
21468
21469 Part of binutils (should be there anyway)
21470 \end_inset
21471 </cell>
21472 </row>
21473 <row topline="true">
21474 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21475 \begin_inset Text
21476
21477 \layout Standard
21478
21479 doxygen
21480 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
21481
21482 \end_inset
21483
21484
21485 \end_inset
21486 </cell>
21487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21488 \begin_inset Text
21489
21490 \layout Standard
21491
21492 Source code documentation system
21493 \end_inset
21494 </cell>
21495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21496 \begin_inset Text
21497
21498 \layout Standard
21499
21500
21501 \begin_inset LatexCommand \url{http://www.doxygen.org}
21502
21503 \end_inset
21504
21505
21506 \end_inset
21507 </cell>
21508 </row>
21509 <row topline="true">
21510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21511 \begin_inset Text
21512
21513 \layout Standard
21514
21515 kdevelop
21516 \end_inset
21517 </cell>
21518 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21519 \begin_inset Text
21520
21521 \layout Standard
21522
21523 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
21524 \end_inset
21525 </cell>
21526 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21527 \begin_inset Text
21528
21529 \layout Standard
21530
21531
21532 \begin_inset LatexCommand \url{http://www.kdevelop.org}
21533
21534 \end_inset
21535
21536
21537 \end_inset
21538 </cell>
21539 </row>
21540 <row topline="true">
21541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21542 \begin_inset Text
21543
21544 \layout Standard
21545
21546 splint
21547 \begin_inset LatexCommand \index{splint (syntax checking tool)}
21548
21549 \end_inset
21550
21551
21552 \end_inset
21553 </cell>
21554 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21555 \begin_inset Text
21556
21557 \layout Standard
21558
21559 Statically checks c sources (has anyone adapted splint for SDCC?)
21560 \end_inset
21561 </cell>
21562 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21563 \begin_inset Text
21564
21565 \layout Standard
21566
21567
21568 \begin_inset LatexCommand \url{http://www.splint.org}
21569
21570 \end_inset
21571
21572
21573 \end_inset
21574 </cell>
21575 </row>
21576 <row topline="true" bottomline="true">
21577 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21578 \begin_inset Text
21579
21580 \layout Standard
21581
21582 ddd
21583 \begin_inset LatexCommand \index{ddd (debugger)}
21584
21585 \end_inset
21586
21587
21588 \end_inset
21589 </cell>
21590 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21591 \begin_inset Text
21592
21593 \layout Standard
21594
21595 Debugger, serves nicely as GUI to sdcdb
21596 \begin_inset LatexCommand \index{sdcdb (debugger)}
21597
21598 \end_inset
21599
21600  (Unix only)
21601 \end_inset
21602 </cell>
21603 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21604 \begin_inset Text
21605
21606 \layout Standard
21607
21608
21609 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
21610
21611 \end_inset
21612
21613
21614 \end_inset
21615 </cell>
21616 </row>
21617 </lyxtabular>
21618
21619 \end_inset
21620
21621
21622 \newline
21623
21624 \layout Section
21625
21626 Related documentation / recommended reading
21627 \layout Standard
21628 \align center
21629
21630 \begin_inset  Tabular
21631 <lyxtabular version="3" rows="6" columns="3">
21632 <features>
21633 <column alignment="center" valignment="top" leftline="true" width="0pt">
21634 <column alignment="block" valignment="top" leftline="true" width="30line%">
21635 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
21636 <row topline="true" bottomline="true">
21637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21638 \begin_inset Text
21639
21640 \layout Standard
21641
21642 Name
21643 \end_inset
21644 </cell>
21645 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21646 \begin_inset Text
21647
21648 \layout Standard
21649
21650 Subject / Title
21651 \end_inset
21652 </cell>
21653 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21654 \begin_inset Text
21655
21656 \layout Standard
21657
21658 Where to get
21659 \end_inset
21660 </cell>
21661 </row>
21662 <row topline="true">
21663 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21664 \begin_inset Text
21665
21666 \layout Standard
21667
21668
21669 \family roman
21670 \series medium
21671 \shape up
21672 \size normal
21673 \emph off
21674 \bar no
21675 \noun off
21676 \color none
21677 c-refcard.pdf
21678 \end_inset
21679 </cell>
21680 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21681 \begin_inset Text
21682
21683 \layout Standard
21684
21685 C Reference Card
21686 \begin_inset LatexCommand \index{C Reference card}
21687
21688 \end_inset
21689
21690 , 2 pages
21691 \end_inset
21692 </cell>
21693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21694 \begin_inset Text
21695
21696 \layout Standard
21697
21698
21699 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
21700
21701 \end_inset
21702
21703
21704 \end_inset
21705 </cell>
21706 </row>
21707 <row topline="true">
21708 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21709 \begin_inset Text
21710
21711 \layout Standard
21712
21713 c-faq
21714 \end_inset
21715 </cell>
21716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21717 \begin_inset Text
21718
21719 \layout Standard
21720
21721 C-FAQ-list
21722 \end_inset
21723 </cell>
21724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21725 \begin_inset Text
21726
21727 \layout Standard
21728
21729
21730 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
21731
21732 \end_inset
21733
21734
21735 \end_inset
21736 </cell>
21737 </row>
21738 <row topline="true">
21739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21740 \begin_inset Text
21741
21742 \layout Standard
21743
21744 \end_inset
21745 </cell>
21746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21747 \begin_inset Text
21748
21749 \layout Standard
21750
21751 Latest datasheet of the target CPU
21752 \end_inset
21753 </cell>
21754 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21755 \begin_inset Text
21756
21757 \layout Standard
21758
21759 vendor
21760 \end_inset
21761 </cell>
21762 </row>
21763 <row topline="true">
21764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21765 \begin_inset Text
21766
21767 \layout Standard
21768
21769 \end_inset
21770 </cell>
21771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21772 \begin_inset Text
21773
21774 \layout Standard
21775
21776 Revision history of datasheet
21777 \end_inset
21778 </cell>
21779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21780 \begin_inset Text
21781
21782 \layout Standard
21783
21784 vendor
21785 \end_inset
21786 </cell>
21787 </row>
21788 <row topline="true" bottomline="true">
21789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21790 \begin_inset Text
21791
21792 \layout Standard
21793
21794 S.
21795  S.
21796  Muchnick
21797 \end_inset
21798 </cell>
21799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21800 \begin_inset Text
21801
21802 \layout Standard
21803
21804 Advanced Compiler Design and Implementation
21805 \end_inset
21806 </cell>
21807 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21808 \begin_inset Text
21809
21810 \layout Standard
21811
21812 bookstore (very dedicated, probably read other books first)
21813 \end_inset
21814 </cell>
21815 </row>
21816 </lyxtabular>
21817
21818 \end_inset
21819
21820
21821 \newline
21822
21823 \layout Section
21824
21825 Some Questions
21826 \layout Standard
21827
21828 Some questions answered, some pointers given - it might be time to in turn
21829  ask
21830 \emph on
21831 you
21832 \emph default
21833  some questions:
21834 \layout Itemize
21835
21836 can you solve your project with the selected microcontroller? Would you
21837  find out early or rather late that your target is too small/slow/whatever?
21838  Can you switch to a slightly better device if it doesn't fit?
21839 \layout Itemize
21840
21841 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
21842  and/or another programming language be more adequate? Would an operating
21843  system on the target device help?
21844 \layout Itemize
21845
21846 if you solved the problem, will the marketing department be happy?
21847 \layout Itemize
21848
21849 if the marketing department is happy, will customers be happy?
21850 \layout Itemize
21851
21852 if you're the project manager, marketing department and maybe even the customer
21853  in one person, have you tried to see the project from the outside?
21854 \layout Itemize
21855
21856 is the project done if you think it is done? Or is just that other interface/pro
21857 tocol/feature/configuration/option missing? How about website, manual(s),
21858  internationali(z|s)ation, packaging, labels, 2nd source for components,
21859  electromagnetic compatability/interference, documentation for production,
21860  production test software, update mechanism, patent issues?
21861 \layout Itemize
21862
21863 is your project adequately positioned in that magic triangle: fame, fortune,
21864  fun?
21865 \layout Standard
21866
21867 Maybe not all answers to these questions are known and some answers may
21868  even be
21869 \emph on
21870 no
21871 \emph default
21872 , nevertheless knowing these questions may help you to avoid burnout
21873 \begin_inset Foot
21874 collapsed false
21875
21876 \layout Standard
21877
21878 burnout is bad for electronic devices, programmers and motorcycle tyres
21879 \end_inset
21880
21881 .
21882  Chances are you didn't want to hear some of them...
21883 \layout Chapter
21884
21885 Support
21886 \begin_inset LatexCommand \index{Support}
21887
21888 \end_inset
21889
21890
21891 \layout Standard
21892
21893 SDCC has grown to be a large project.
21894  The compiler alone (without the preprocessor, assembler and linker) is
21895  well over 100,000 lines of code (blank stripped).
21896  The open source nature of this project is a key to its continued growth
21897  and support.
21898  You gain the benefit and support of many active software developers and
21899  end users.
21900  Is SDCC perfect? No, that's why we need your help.
21901  The developers take pride in fixing reported bugs.
21902  You can help by reporting the bugs and helping other SDCC users.
21903  There are lots of ways to contribute, and we encourage you to take part
21904  in making SDCC a great software package.
21905
21906 \layout Standard
21907
21908 The SDCC project is hosted on the SDCC sourceforge site at
21909 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
21910
21911 \end_inset
21912
21913 .
21914  You'll find the complete set of mailing lists
21915 \begin_inset LatexCommand \index{Mailing list(s)}
21916
21917 \end_inset
21918
21919 , forums, bug reporting system, patch submission
21920 \begin_inset LatexCommand \index{Patch submission}
21921
21922 \end_inset
21923
21924  system, download
21925 \begin_inset LatexCommand \index{download}
21926
21927 \end_inset
21928
21929  area and cvs code repository
21930 \begin_inset LatexCommand \index{cvs code repository}
21931
21932 \end_inset
21933
21934  there.
21935 \layout Section
21936
21937 Reporting Bugs
21938 \begin_inset LatexCommand \index{Bug reporting}
21939
21940 \end_inset
21941
21942
21943 \begin_inset LatexCommand \index{Reporting bugs}
21944
21945 \end_inset
21946
21947
21948 \layout Standard
21949
21950 The recommended way of reporting bugs is using the infrastructure of the
21951  sourceforge site.
21952  You can follow the status of bug reports there and have an overview about
21953  the known bugs.
21954 \layout Standard
21955
21956 Bug reports are automatically forwarded to the developer mailing list and
21957  will be fixed ASAP.
21958  When reporting a bug, it is very useful to include a small test program
21959  (the smaller the better) which reproduces the problem.
21960  If you can isolate the problem by looking at the generated assembly code,
21961  this can be very helpful.
21962  Compiling your program with the -
21963 \begin_inset ERT
21964 status Collapsed
21965
21966 \layout Standard
21967
21968 \backslash
21969 /
21970 \end_inset
21971
21972 -dumpall
21973 \begin_inset LatexCommand \index{-\/-dumpall}
21974
21975 \end_inset
21976
21977  option can sometimes be useful in locating optimization problems.
21978  When reporting a bug please maker sure you:
21979 \layout Enumerate
21980
21981 Attach the code you are compiling with SDCC.
21982
21983 \layout Enumerate
21984
21985 Specify the exact command you use to run SDCC, or attach your Makefile.
21986
21987 \layout Enumerate
21988
21989 Specify the SDCC version (type "
21990 \family sans
21991 \series bold
21992 sdcc -v
21993 \family default
21994 \series default
21995 "), your platform, and operating system.
21996
21997 \layout Enumerate
21998
21999 Provide an exact copy of any error message or incorrect output.
22000
22001 \layout Enumerate
22002
22003 Put something meaningful in the subject of your message.
22004 \layout Standard
22005
22006 Please attempt to include these 5 important parts, as applicable, in all
22007  requests for support or when reporting any problems or bugs with SDCC.
22008  Though this will make your message lengthy, it will greatly improve your
22009  chance that SDCC users and developers will be able to help you.
22010  Some SDCC developers are frustrated by bug reports without code provided
22011  that they can use to reproduce and ultimately fix the problem, so please
22012  be sure to provide sample code if you are reporting a bug!
22013 \layout Standard
22014
22015 Please have a short check that you are using a recent version of SDCC and
22016  the bug is not yet known.
22017  This is the link for reporting bugs:
22018 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
22019
22020 \end_inset
22021
22022 .
22023 \layout Section
22024
22025 Requesting Features
22026 \begin_inset LatexCommand \label{sub:Requesting-Features}
22027
22028 \end_inset
22029
22030
22031 \begin_inset LatexCommand \index{Feature request}
22032
22033 \end_inset
22034
22035
22036 \begin_inset LatexCommand \index{Requesting features}
22037
22038 \end_inset
22039
22040
22041 \layout Standard
22042
22043 Like bug reports feature requests are forwarded to the developer mailing
22044  list.
22045  This is the link for requesting features:
22046 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
22047
22048 \end_inset
22049
22050 .
22051 \layout Section
22052
22053 Submitting patches
22054 \layout Standard
22055
22056 Like bug reports contributed patches are forwarded to the developer mailing
22057  list.
22058  This is the link for submitting patches
22059 \begin_inset LatexCommand \index{Patch submission}
22060
22061 \end_inset
22062
22063 :
22064 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
22065
22066 \end_inset
22067
22068 .
22069 \layout Standard
22070
22071 You need to specify some parameters to the
22072 \family typewriter
22073 diff
22074 \family default
22075  command for the patches to be useful.
22076  If you modified more than one file a patch created f.e.
22077  with
22078 \family sans
22079 \series bold
22080
22081 \begin_inset Quotes sld
22082 \end_inset
22083
22084 diff -Naur unmodified_directory modified_directory >my_changes.patch
22085 \begin_inset Quotes srd
22086 \end_inset
22087
22088
22089 \family default
22090 \series default
22091  will be fine, otherwise
22092 \family sans
22093 \series bold
22094
22095 \begin_inset Quotes sld
22096 \end_inset
22097
22098 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
22099 \begin_inset Quotes srd
22100 \end_inset
22101
22102
22103 \series default
22104
22105 \family default
22106 will do.
22107 \layout Section
22108
22109 Getting Help
22110 \layout Standard
22111
22112 These links should take you directly to the
22113 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
22114
22115 \end_inset
22116
22117
22118 \begin_inset Foot
22119 collapsed false
22120
22121 \layout Standard
22122
22123 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
22124  automated messages (mid 2003)
22125 \end_inset
22126
22127  and the
22128 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
22129
22130 \end_inset
22131
22132 , lists
22133 \begin_inset LatexCommand \index{Mailing list(s)}
22134
22135 \end_inset
22136
22137  and forums are archived and searchable so if you are lucky someone already
22138  had a similar problem.
22139  While mails to the lists themselves are delivered promptly their web front
22140  end on sourceforge sometimes shows a severe time lag (up to several weeks),
22141  if you're seriously using SDCC please consider subscribing to the lists.
22142 \layout Section
22143
22144 ChangeLog
22145 \layout Standard
22146
22147 You can follow the status of the cvs version
22148 \begin_inset LatexCommand \index{version}
22149
22150 \end_inset
22151
22152  of SDCC by watching the Changelog
22153 \begin_inset LatexCommand \index{Changelog}
22154
22155 \end_inset
22156
22157  in the cvs-repository
22158 \newline
22159
22160 \size footnotesize
22161
22162 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
22163
22164 \end_inset
22165
22166 .
22167 \layout Section
22168
22169 Release policy
22170 \begin_inset LatexCommand \index{Release policy}
22171
22172 \end_inset
22173
22174
22175 \layout Standard
22176
22177 Historically there often were long delays between official releases and
22178  the sourceforge download area tends to get not updated at all.
22179  Excuses in the past might have referred to problems with live range analysis,
22180  but as this was fixed a while ago, the current problem is that another
22181  excuse has to be found.
22182  Kidding aside, we have to get better there! On the other hand there are
22183  daily snapshots available at
22184 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
22185
22186 \end_inset
22187
22188 , and you can always build the very last version (hopefully with many bugs
22189  fixed, and features added) from the source code available at
22190 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
22191
22192 \end_inset
22193
22194 .
22195 \layout Section
22196
22197 Examples
22198 \begin_inset LatexCommand \index{Examples}
22199
22200 \end_inset
22201
22202
22203 \layout Standard
22204
22205 You'll find some small examples in the directory
22206 \emph on
22207 sdcc/device/examples/.
22208
22209 \emph default
22210 More examples and libraries are available at
22211 \emph on
22212  The SDCC Open Knowledge Resource
22213 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
22214
22215 \end_inset
22216
22217
22218 \emph default
22219 web site or at
22220 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
22221
22222 \end_inset
22223
22224 .
22225 \layout Comment
22226
22227 I did insert a reference to Paul's web site here although it seems rather
22228  dedicated to a specific 8032 board (I think it's okay because it f.e.
22229  shows LCD/Harddisc interface and has a free 8051 monitor.
22230  Independent 8032 board vendors face hard competition of heavily subsidized
22231  development boards anyway).
22232 \layout Comment
22233
22234 Maybe we should include some links to real world applications.
22235  Preferably pointer to pointers (one for each architecture) so this stays
22236  manageable here?
22237 \layout Section
22238
22239 Quality control
22240 \begin_inset LatexCommand \index{Quality control}
22241
22242 \end_inset
22243
22244
22245 \layout Standard
22246
22247 The compiler is passed through nightly compile and build checks.
22248  The so called
22249 \shape italic
22250 regression tests
22251 \shape default
22252
22253 \begin_inset LatexCommand \index{Regression test}
22254
22255 \end_inset
22256
22257  check that SDCC itself compiles flawlessly on several platforms and checks
22258  the quality of the code generated by SDCC by running the code through simulator
22259 s.
22260  There is a separate document
22261 \shape italic
22262 test_suite.pdf
22263 \begin_inset LatexCommand \index{Test suite}
22264
22265 \end_inset
22266
22267
22268 \shape default
22269  about this.
22270 \layout Standard
22271
22272 You'll find the test code in the directory
22273 \shape italic
22274 sdcc/support/regression
22275 \shape default
22276 .
22277  You can run these tests manually by running
22278 \family sans
22279 make
22280 \family default
22281  in this directory (or f.e.
22282
22283 \family sans
22284 \series bold
22285
22286 \begin_inset Quotes sld
22287 \end_inset
22288
22289 make test-mcs51
22290 \begin_inset Quotes srd
22291 \end_inset
22292
22293
22294 \family default
22295 \series default
22296  if you don't want to run the complete tests).
22297  The test code might also be interesting if you want to look for examples
22298 \begin_inset LatexCommand \index{Examples}
22299
22300 \end_inset
22301
22302  checking corner cases of SDCC or if you plan to submit patches
22303 \begin_inset LatexCommand \index{Patch submission}
22304
22305 \end_inset
22306
22307 .
22308 \layout Standard
22309
22310 The pic port uses a different set of regression tests, you'll find them
22311  in the directory
22312 \shape italic
22313 sdcc/src/regression
22314 \shape default
22315 .
22316 \layout Chapter
22317 \pagebreak_top
22318 SDCC Technical Data
22319 \layout Section
22320
22321 Optimizations
22322 \begin_inset LatexCommand \index{Optimizations}
22323
22324 \end_inset
22325
22326
22327 \layout Standard
22328
22329 SDCC performs a host of standard optimizations in addition to some MCU specific
22330  optimizations.
22331
22332 \layout Subsection
22333
22334 Sub-expression Elimination
22335 \begin_inset LatexCommand \index{Subexpression elimination}
22336
22337 \end_inset
22338
22339
22340 \layout Standard
22341
22342 The compiler does local and
22343 \emph on
22344 g
22345 \emph default
22346 lobal
22347 \emph on
22348 c
22349 \emph default
22350 ommon
22351 \emph on
22352 s
22353 \emph default
22354 ubexpression
22355 \emph on
22356 e
22357 \emph default
22358 limination, e.g.:
22359 \layout Verse
22360
22361
22362 \family typewriter
22363 i = x + y + 1;
22364 \newline
22365 j = x + y;
22366 \layout Standard
22367
22368 will be translated to
22369 \layout Verse
22370
22371
22372 \family typewriter
22373 iTemp = x + y;
22374 \newline
22375 i = iTemp + 1;
22376 \newline
22377 j = iTemp;
22378 \layout Standard
22379
22380 Some subexpressions are not as obvious as the above example, e.g.:
22381 \layout Verse
22382
22383
22384 \family typewriter
22385 a->b[i].c = 10;
22386 \newline
22387 a->b[i].d = 11;
22388 \layout Standard
22389
22390 In this case the address arithmetic a->b[i] will be computed only once;
22391  the equivalent code in C would be.
22392 \layout Verse
22393
22394
22395 \family typewriter
22396 iTemp = a->b[i];
22397 \newline
22398 iTemp.c = 10;
22399 \newline
22400 iTemp.d = 11;
22401 \layout Standard
22402
22403 The compiler will try to keep these temporary variables in registers.
22404 \layout Subsection
22405
22406 Dead-Code Elimination
22407 \begin_inset LatexCommand \index{Dead-code elimination}
22408
22409 \end_inset
22410
22411
22412 \layout Verse
22413
22414
22415 \family typewriter
22416 int global;
22417 \newline
22418
22419 \newline
22420 void f () {
22421 \newline
22422 \SpecialChar ~
22423 \SpecialChar ~
22424 int i;
22425 \newline
22426 \SpecialChar ~
22427 \SpecialChar ~
22428 i = 1; \SpecialChar ~
22429 \SpecialChar ~
22430 \SpecialChar ~
22431 \SpecialChar ~
22432 \SpecialChar ~
22433 /* dead store */
22434 \newline
22435 \SpecialChar ~
22436 \SpecialChar ~
22437 global = 1;\SpecialChar ~
22438 /* dead store */
22439 \newline
22440 \SpecialChar ~
22441 \SpecialChar ~
22442 global = 2;
22443 \newline
22444 \SpecialChar ~
22445 \SpecialChar ~
22446 return;
22447 \newline
22448 \SpecialChar ~
22449 \SpecialChar ~
22450 global = 3;\SpecialChar ~
22451 /* unreachable */
22452 \newline
22453 }
22454 \layout Standard
22455
22456 will be changed to
22457 \layout Verse
22458
22459
22460 \family typewriter
22461 int global;
22462 \newline
22463
22464 \newline
22465 void f () {
22466 \newline
22467 \SpecialChar ~
22468 \SpecialChar ~
22469 global = 2;
22470 \newline
22471 }
22472 \layout Subsection
22473
22474 Copy-Propagation
22475 \begin_inset LatexCommand \index{Copy propagation}
22476
22477 \end_inset
22478
22479
22480 \layout Verse
22481
22482
22483 \family typewriter
22484 int f() {
22485 \newline
22486 \SpecialChar ~
22487 \SpecialChar ~
22488 int i, j;
22489 \newline
22490 \SpecialChar ~
22491 \SpecialChar ~
22492 i = 10;
22493 \newline
22494 \SpecialChar ~
22495 \SpecialChar ~
22496 j = i;
22497 \newline
22498 \SpecialChar ~
22499 \SpecialChar ~
22500 return j;
22501 \newline
22502 }
22503 \layout Standard
22504
22505 will be changed to
22506 \layout Verse
22507
22508
22509 \family typewriter
22510 int f() {
22511 \newline
22512 \SpecialChar ~
22513 \SpecialChar ~
22514 int i, j;
22515 \newline
22516 \SpecialChar ~
22517 \SpecialChar ~
22518 i = 10;
22519 \newline
22520 \SpecialChar ~
22521 \SpecialChar ~
22522 j = 10;
22523 \newline
22524 \SpecialChar ~
22525 \SpecialChar ~
22526 return 10;
22527 \newline
22528 }
22529 \layout Standard
22530
22531 Note: the dead stores created by this copy propagation will be eliminated
22532  by dead-code elimination.
22533 \layout Subsection
22534
22535 Loop Optimizations
22536 \begin_inset LatexCommand \index{Loop optimization}
22537
22538 \end_inset
22539
22540
22541 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
22542
22543 \end_inset
22544
22545
22546 \layout Standard
22547
22548 Two types of loop optimizations are done by SDCC
22549 \emph on
22550 loop invariant
22551 \emph default
22552  lifting and
22553 \emph on
22554  strength reduction
22555 \emph default
22556  of loop induction variables.
22557  In addition to the strength reduction the optimizer marks the induction
22558  variables and the register allocator tries to keep the induction variables
22559  in registers for the duration of the loop.
22560  Because of this preference of the register allocator
22561 \begin_inset LatexCommand \index{Register allocation}
22562
22563 \end_inset
22564
22565 , loop induction optimization causes an increase in register pressure, which
22566  may cause unwanted spilling of other temporary variables into the stack
22567 \begin_inset LatexCommand \index{stack}
22568
22569 \end_inset
22570
22571  / data space.
22572  The compiler will generate a warning message when it is forced to allocate
22573  extra space either on the stack or data space.
22574  If this extra space allocation is undesirable then induction optimization
22575  can be eliminated either for the entire source file (with -
22576 \begin_inset ERT
22577 status Collapsed
22578
22579 \layout Standard
22580
22581 \backslash
22582 /
22583 \end_inset
22584
22585 -noinduction option) or for a given function only using #pragma\SpecialChar ~
22586 noinduction
22587 \begin_inset LatexCommand \index{\#pragma noinduction}
22588
22589 \end_inset
22590
22591 .
22592 \newline
22593
22594 \newline
22595 Loop Invariant:
22596 \layout Verse
22597
22598
22599 \family typewriter
22600 for (i = 0 ; i < 100 ; i ++)
22601 \newline
22602 \SpecialChar ~
22603 \SpecialChar ~
22604 \SpecialChar ~
22605 \SpecialChar ~
22606 f += k + l;
22607 \layout Standard
22608
22609 changed to
22610 \layout Verse
22611
22612
22613 \family typewriter
22614 itemp = k + l;
22615 \newline
22616 for (i = 0; i < 100; i++)
22617 \newline
22618 \SpecialChar ~
22619 \SpecialChar ~
22620 \SpecialChar ~
22621 \SpecialChar ~
22622 f += itemp;
22623 \layout Standard
22624
22625 As mentioned previously some loop invariants are not as apparent, all static
22626  address computations are also moved out of the loop.
22627 \newline
22628
22629 \newline
22630 Strength Reduction
22631 \begin_inset LatexCommand \index{Strength reduction}
22632
22633 \end_inset
22634
22635 , this optimization substitutes an expression by a cheaper expression:
22636 \layout Verse
22637
22638
22639 \family typewriter
22640 for (i=0;i < 100; i++)
22641 \newline
22642 \SpecialChar ~
22643 \SpecialChar ~
22644 \SpecialChar ~
22645 \SpecialChar ~
22646 ar[i*5] = i*3;
22647 \layout Standard
22648
22649 changed to
22650 \layout Verse
22651
22652
22653 \family typewriter
22654 itemp1 = 0;
22655 \newline
22656 itemp2 = 0;
22657 \newline
22658 for (i=0;i< 100;i++) {
22659 \newline
22660 \SpecialChar ~
22661 \SpecialChar ~
22662 \SpecialChar ~
22663 \SpecialChar ~
22664 ar[itemp1] = itemp2;
22665 \newline
22666 \SpecialChar ~
22667 \SpecialChar ~
22668 \SpecialChar ~
22669 \SpecialChar ~
22670 itemp1 += 5;
22671 \newline
22672 \SpecialChar ~
22673 \SpecialChar ~
22674 \SpecialChar ~
22675 \SpecialChar ~
22676 itemp2 += 3;
22677 \newline
22678 }
22679 \layout Standard
22680
22681 The more expensive multiplication
22682 \begin_inset LatexCommand \index{Multiplication}
22683
22684 \end_inset
22685
22686  is changed to a less expensive addition.
22687 \layout Subsection
22688
22689 Loop Reversing
22690 \begin_inset LatexCommand \index{Loop reversing}
22691
22692 \end_inset
22693
22694
22695 \layout Standard
22696
22697 This optimization is done to reduce the overhead of checking loop boundaries
22698  for every iteration.
22699  Some simple loops can be reversed and implemented using a
22700 \begin_inset Quotes eld
22701 \end_inset
22702
22703 decrement and jump if not zero
22704 \begin_inset Quotes erd
22705 \end_inset
22706
22707  instruction.
22708  SDCC checks for the following criterion to determine if a loop is reversible
22709  (note: more sophisticated compilers use data-dependency analysis to make
22710  this determination, SDCC uses a more simple minded analysis).
22711 \layout Itemize
22712
22713 The 'for' loop is of the form
22714 \newline
22715
22716 \newline
22717
22718 \family typewriter
22719 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
22720  += 1])
22721 \newline
22722 \SpecialChar ~
22723 \SpecialChar ~
22724 \SpecialChar ~
22725 \SpecialChar ~
22726 <for body>
22727 \layout Itemize
22728
22729 The <for body> does not contain
22730 \begin_inset Quotes eld
22731 \end_inset
22732
22733 continue
22734 \begin_inset Quotes erd
22735 \end_inset
22736
22737  or 'break
22738 \begin_inset Quotes erd
22739 \end_inset
22740
22741 .
22742 \layout Itemize
22743
22744 All goto's are contained within the loop.
22745 \layout Itemize
22746
22747 No function calls within the loop.
22748 \layout Itemize
22749
22750 The loop control variable <sym> is not assigned any value within the loop
22751 \layout Itemize
22752
22753 The loop control variable does NOT participate in any arithmetic operation
22754  within the loop.
22755 \layout Itemize
22756
22757 There are NO switch statements in the loop.
22758 \layout Subsection
22759
22760 Algebraic Simplifications
22761 \layout Standard
22762
22763 SDCC does numerous algebraic simplifications, the following is a small sub-set
22764  of these optimizations.
22765 \layout Verse
22766
22767
22768 \family typewriter
22769 i = j + 0;\SpecialChar ~
22770 \SpecialChar ~
22771 \SpecialChar ~
22772 \SpecialChar ~
22773  /* changed to: */\SpecialChar ~
22774 \SpecialChar ~
22775 \SpecialChar ~
22776 \SpecialChar ~
22777  i = j;
22778 \newline
22779 i /= 2;\SpecialChar ~
22780 \SpecialChar ~
22781 \SpecialChar ~
22782 \SpecialChar ~
22783 \SpecialChar ~
22784 \SpecialChar ~
22785 \SpecialChar ~
22786  /* changed to: */\SpecialChar ~
22787 \SpecialChar ~
22788 \SpecialChar ~
22789 \SpecialChar ~
22790  i >>= 1;
22791 \newline
22792 i = j - j;\SpecialChar ~
22793 \SpecialChar ~
22794 \SpecialChar ~
22795 \SpecialChar ~
22796  /* changed to: */\SpecialChar ~
22797 \SpecialChar ~
22798 \SpecialChar ~
22799 \SpecialChar ~
22800  i = 0;
22801 \newline
22802 i = j / 1;\SpecialChar ~
22803 \SpecialChar ~
22804 \SpecialChar ~
22805 \SpecialChar ~
22806  /* changed to: */\SpecialChar ~
22807 \SpecialChar ~
22808 \SpecialChar ~
22809 \SpecialChar ~
22810  i = j;
22811 \layout Standard
22812
22813 Note the subexpressions
22814 \begin_inset LatexCommand \index{Subexpression}
22815
22816 \end_inset
22817
22818  given above are generally introduced by macro expansions or as a result
22819  of copy/constant propagation.
22820 \layout Subsection
22821
22822 'switch' Statements
22823 \begin_inset LatexCommand \label{sub:'switch'-Statements}
22824
22825 \end_inset
22826
22827
22828 \begin_inset LatexCommand \index{switch statement}
22829
22830 \end_inset
22831
22832
22833 \layout Standard
22834
22835 SDCC can optimize switch statements to jump tables
22836 \begin_inset LatexCommand \index{jump tables}
22837
22838 \end_inset
22839
22840 .
22841  It makes the decision based on an estimate of the generated code size.
22842  SDCC is quite liberal in the requirements for jump table generation:
22843 \layout Itemize
22844
22845 The labels need not be in order, and the starting number need not be one
22846  or zero, the case labels are in numerical sequence or not too many case
22847  labels are missing.
22848 \begin_deeper
22849 \layout Verse
22850
22851
22852 \family typewriter
22853 switch(i) {\SpecialChar ~
22854 \SpecialChar ~
22855 \SpecialChar ~
22856 \SpecialChar ~
22857 \SpecialChar ~
22858 \SpecialChar ~
22859 \SpecialChar ~
22860 \SpecialChar ~
22861 \SpecialChar ~
22862 \SpecialChar ~
22863 \SpecialChar ~
22864 \SpecialChar ~
22865 \SpecialChar ~
22866 \SpecialChar ~
22867 \SpecialChar ~
22868 \SpecialChar ~
22869 \SpecialChar ~
22870 \SpecialChar ~
22871 \SpecialChar ~
22872 \SpecialChar ~
22873 \SpecialChar ~
22874 \SpecialChar ~
22875 \SpecialChar ~
22876 \SpecialChar ~
22877 \SpecialChar ~
22878 \SpecialChar ~
22879 switch (i) {
22880 \newline
22881 \SpecialChar ~
22882 \SpecialChar ~
22883 \SpecialChar ~
22884 case 4: ...\SpecialChar ~
22885 \SpecialChar ~
22886 \SpecialChar ~
22887 \SpecialChar ~
22888 \SpecialChar ~
22889 \SpecialChar ~
22890 \SpecialChar ~
22891 \SpecialChar ~
22892 \SpecialChar ~
22893 \SpecialChar ~
22894 \SpecialChar ~
22895 \SpecialChar ~
22896 \SpecialChar ~
22897 \SpecialChar ~
22898 \SpecialChar ~
22899 \SpecialChar ~
22900 \SpecialChar ~
22901 \SpecialChar ~
22902 \SpecialChar ~
22903 \SpecialChar ~
22904 \SpecialChar ~
22905 \SpecialChar ~
22906 \SpecialChar ~
22907 \SpecialChar ~
22908 \SpecialChar ~
22909 \SpecialChar ~
22910 case 0: ...
22911
22912 \newline
22913 \SpecialChar ~
22914 \SpecialChar ~
22915 \SpecialChar ~
22916 case 5: ...\SpecialChar ~
22917 \SpecialChar ~
22918 \SpecialChar ~
22919 \SpecialChar ~
22920 \SpecialChar ~
22921 \SpecialChar ~
22922 \SpecialChar ~
22923 \SpecialChar ~
22924 \SpecialChar ~
22925 \SpecialChar ~
22926 \SpecialChar ~
22927 \SpecialChar ~
22928 \SpecialChar ~
22929 \SpecialChar ~
22930 \SpecialChar ~
22931 \SpecialChar ~
22932 \SpecialChar ~
22933 \SpecialChar ~
22934 \SpecialChar ~
22935 \SpecialChar ~
22936 \SpecialChar ~
22937 \SpecialChar ~
22938 \SpecialChar ~
22939 \SpecialChar ~
22940 \SpecialChar ~
22941 \SpecialChar ~
22942 case 1: ...
22943
22944 \newline
22945 \SpecialChar ~
22946 \SpecialChar ~
22947 \SpecialChar ~
22948 case 3: ...\SpecialChar ~
22949 \SpecialChar ~
22950 \SpecialChar ~
22951 \SpecialChar ~
22952 \SpecialChar ~
22953 \SpecialChar ~
22954 \SpecialChar ~
22955 \SpecialChar ~
22956 \SpecialChar ~
22957 \SpecialChar ~
22958 \SpecialChar ~
22959 \SpecialChar ~
22960 \SpecialChar ~
22961 \SpecialChar ~
22962 \SpecialChar ~
22963 \SpecialChar ~
22964 \SpecialChar ~
22965 \SpecialChar ~
22966 \SpecialChar ~
22967 \SpecialChar ~
22968 \SpecialChar ~
22969 \SpecialChar ~
22970 \SpecialChar ~
22971 \SpecialChar ~
22972 \SpecialChar ~
22973 \SpecialChar ~
22974
22975 \newline
22976 \SpecialChar ~
22977 \SpecialChar ~
22978 \SpecialChar ~
22979 case 6: ...\SpecialChar ~
22980 \SpecialChar ~
22981 \SpecialChar ~
22982 \SpecialChar ~
22983 \SpecialChar ~
22984 \SpecialChar ~
22985 \SpecialChar ~
22986 \SpecialChar ~
22987 \SpecialChar ~
22988 \SpecialChar ~
22989 \SpecialChar ~
22990 \SpecialChar ~
22991 \SpecialChar ~
22992 \SpecialChar ~
22993 \SpecialChar ~
22994 \SpecialChar ~
22995 \SpecialChar ~
22996 \SpecialChar ~
22997 \SpecialChar ~
22998 \SpecialChar ~
22999 \SpecialChar ~
23000 \SpecialChar ~
23001 \SpecialChar ~
23002 \SpecialChar ~
23003 \SpecialChar ~
23004 \SpecialChar ~
23005 case 3: ...
23006
23007 \newline
23008 \SpecialChar ~
23009 \SpecialChar ~
23010 \SpecialChar ~
23011 case 7: ...\SpecialChar ~
23012 \SpecialChar ~
23013 \SpecialChar ~
23014 \SpecialChar ~
23015 \SpecialChar ~
23016 \SpecialChar ~
23017 \SpecialChar ~
23018 \SpecialChar ~
23019 \SpecialChar ~
23020 \SpecialChar ~
23021 \SpecialChar ~
23022 \SpecialChar ~
23023 \SpecialChar ~
23024 \SpecialChar ~
23025 \SpecialChar ~
23026 \SpecialChar ~
23027 \SpecialChar ~
23028 \SpecialChar ~
23029 \SpecialChar ~
23030 \SpecialChar ~
23031 \SpecialChar ~
23032 \SpecialChar ~
23033 \SpecialChar ~
23034 \SpecialChar ~
23035 \SpecialChar ~
23036 \SpecialChar ~
23037 case 4: ...
23038
23039 \newline
23040 \SpecialChar ~
23041 \SpecialChar ~
23042 \SpecialChar ~
23043 case 8: ...\SpecialChar ~
23044 \SpecialChar ~
23045 \SpecialChar ~
23046 \SpecialChar ~
23047 \SpecialChar ~
23048 \SpecialChar ~
23049 \SpecialChar ~
23050 \SpecialChar ~
23051 \SpecialChar ~
23052 \SpecialChar ~
23053 \SpecialChar ~
23054 \SpecialChar ~
23055 \SpecialChar ~
23056 \SpecialChar ~
23057 \SpecialChar ~
23058 \SpecialChar ~
23059 \SpecialChar ~
23060 \SpecialChar ~
23061 \SpecialChar ~
23062 \SpecialChar ~
23063 \SpecialChar ~
23064 \SpecialChar ~
23065 \SpecialChar ~
23066 \SpecialChar ~
23067 \SpecialChar ~
23068 \SpecialChar ~
23069 case 5: ...
23070
23071 \newline
23072 \SpecialChar ~
23073 \SpecialChar ~
23074 \SpecialChar ~
23075 case 9: ...\SpecialChar ~
23076 \SpecialChar ~
23077 \SpecialChar ~
23078 \SpecialChar ~
23079 \SpecialChar ~
23080 \SpecialChar ~
23081 \SpecialChar ~
23082 \SpecialChar ~
23083 \SpecialChar ~
23084 \SpecialChar ~
23085 \SpecialChar ~
23086 \SpecialChar ~
23087 \SpecialChar ~
23088 \SpecialChar ~
23089 \SpecialChar ~
23090 \SpecialChar ~
23091 \SpecialChar ~
23092 \SpecialChar ~
23093 \SpecialChar ~
23094 \SpecialChar ~
23095 \SpecialChar ~
23096 \SpecialChar ~
23097 \SpecialChar ~
23098 \SpecialChar ~
23099 \SpecialChar ~
23100 \SpecialChar ~
23101 case 6: ...
23102
23103 \newline
23104 \SpecialChar ~
23105 \SpecialChar ~
23106 \SpecialChar ~
23107 case 10: ...\SpecialChar ~
23108 \SpecialChar ~
23109 \SpecialChar ~
23110 \SpecialChar ~
23111 \SpecialChar ~
23112 \SpecialChar ~
23113 \SpecialChar ~
23114 \SpecialChar ~
23115 \SpecialChar ~
23116 \SpecialChar ~
23117 \SpecialChar ~
23118 \SpecialChar ~
23119 \SpecialChar ~
23120 \SpecialChar ~
23121 \SpecialChar ~
23122 \SpecialChar ~
23123 \SpecialChar ~
23124 \SpecialChar ~
23125 \SpecialChar ~
23126 \SpecialChar ~
23127 \SpecialChar ~
23128 \SpecialChar ~
23129 \SpecialChar ~
23130 \SpecialChar ~
23131 \SpecialChar ~
23132 case 7: ...
23133
23134 \newline
23135 \SpecialChar ~
23136 \SpecialChar ~
23137 \SpecialChar ~
23138 case 11: ...\SpecialChar ~
23139 \SpecialChar ~
23140 \SpecialChar ~
23141 \SpecialChar ~
23142 \SpecialChar ~
23143 \SpecialChar ~
23144 \SpecialChar ~
23145 \SpecialChar ~
23146 \SpecialChar ~
23147 \SpecialChar ~
23148 \SpecialChar ~
23149 \SpecialChar ~
23150 \SpecialChar ~
23151 \SpecialChar ~
23152 \SpecialChar ~
23153 \SpecialChar ~
23154 \SpecialChar ~
23155 \SpecialChar ~
23156 \SpecialChar ~
23157 \SpecialChar ~
23158 \SpecialChar ~
23159 \SpecialChar ~
23160 \SpecialChar ~
23161 \SpecialChar ~
23162 \SpecialChar ~
23163 case 8: ...
23164
23165 \newline
23166 }\SpecialChar ~
23167 \SpecialChar ~
23168 \SpecialChar ~
23169 \SpecialChar ~
23170 \SpecialChar ~
23171 \SpecialChar ~
23172 \SpecialChar ~
23173 \SpecialChar ~
23174 \SpecialChar ~
23175 \SpecialChar ~
23176 \SpecialChar ~
23177 \SpecialChar ~
23178 \SpecialChar ~
23179 \SpecialChar ~
23180 \SpecialChar ~
23181 \SpecialChar ~
23182 \SpecialChar ~
23183 \SpecialChar ~
23184 \SpecialChar ~
23185 \SpecialChar ~
23186 \SpecialChar ~
23187 \SpecialChar ~
23188 \SpecialChar ~
23189 \SpecialChar ~
23190 \SpecialChar ~
23191 \SpecialChar ~
23192 \SpecialChar ~
23193 \SpecialChar ~
23194 \SpecialChar ~
23195 \SpecialChar ~
23196 \SpecialChar ~
23197 \SpecialChar ~
23198 \SpecialChar ~
23199 \SpecialChar ~
23200 \SpecialChar ~
23201 \SpecialChar ~
23202 }
23203 \layout Standard
23204
23205 Both the above switch statements will be implemented using a jump-table.
23206  The example to the right side is slightly more efficient as the check for
23207  the lower boundary of the jump-table is not needed.
23208 \end_deeper
23209 \layout Itemize
23210
23211 The number of case labels is not larger than supported by the target architectur
23212 e.
23213 \layout Itemize
23214
23215 If the case labels are not in numerical sequence ('gaps' between cases)
23216  SDCC checks whether a jump table with additionally inserted dummy cases
23217  is still attractive.
23218
23219 \layout Itemize
23220
23221 If the starting number is not zero and a check for the lower boundary of
23222  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
23223  ...
23224  .
23225 \layout Standard
23226
23227 Switch statements which have large gaps in the numeric sequence or those
23228  that have too many case labels can be split into more than one switch statement
23229  for efficient code generation, e.g.:
23230 \layout Verse
23231
23232
23233 \family typewriter
23234 switch (i) {
23235 \newline
23236 \SpecialChar ~
23237 \SpecialChar ~
23238 case 1: ...
23239
23240 \newline
23241 \SpecialChar ~
23242 \SpecialChar ~
23243 case 2: ...
23244
23245 \newline
23246 \SpecialChar ~
23247 \SpecialChar ~
23248 case 3: ...
23249
23250 \newline
23251 \SpecialChar ~
23252 \SpecialChar ~
23253 case 4: ...
23254
23255 \newline
23256 \SpecialChar ~
23257 \SpecialChar ~
23258 case 5: ...
23259
23260 \newline
23261 \SpecialChar ~
23262 \SpecialChar ~
23263 case 6: ...
23264
23265 \newline
23266 \SpecialChar ~
23267 \SpecialChar ~
23268 case 7: ...
23269
23270 \newline
23271 \SpecialChar ~
23272 \SpecialChar ~
23273 case 101: ...
23274
23275 \newline
23276 \SpecialChar ~
23277 \SpecialChar ~
23278 case 102: ...
23279
23280 \newline
23281 \SpecialChar ~
23282 \SpecialChar ~
23283 case 103: ...
23284
23285 \newline
23286 \SpecialChar ~
23287 \SpecialChar ~
23288 case 104: ...
23289
23290 \newline
23291 \SpecialChar ~
23292 \SpecialChar ~
23293 case 105: ...
23294
23295 \newline
23296 \SpecialChar ~
23297 \SpecialChar ~
23298 case 106: ...
23299
23300 \newline
23301 \SpecialChar ~
23302 \SpecialChar ~
23303 case 107: ...
23304
23305 \newline
23306 }
23307 \layout Standard
23308
23309 If the above switch statement is broken down into two switch statements
23310 \layout Verse
23311
23312
23313 \family typewriter
23314 switch (i) {
23315 \newline
23316 \SpecialChar ~
23317 \SpecialChar ~
23318 case 1: ...
23319
23320 \newline
23321 \SpecialChar ~
23322 \SpecialChar ~
23323 case 2: ...
23324
23325 \newline
23326 \SpecialChar ~
23327 \SpecialChar ~
23328 case 3: ...
23329
23330 \newline
23331 \SpecialChar ~
23332 \SpecialChar ~
23333 case 4: ...
23334
23335 \newline
23336 \SpecialChar ~
23337 \SpecialChar ~
23338 case 5: ...
23339
23340 \newline
23341 \SpecialChar ~
23342 \SpecialChar ~
23343 case 6: ...
23344
23345 \newline
23346 \SpecialChar ~
23347 \SpecialChar ~
23348 case 7: ...
23349
23350 \newline
23351 }
23352 \layout Standard
23353
23354 and
23355 \layout Verse
23356
23357
23358 \family typewriter
23359 switch (i) {
23360 \newline
23361 \SpecialChar ~
23362 \SpecialChar ~
23363 case 101: ...
23364
23365 \newline
23366 \SpecialChar ~
23367 \SpecialChar ~
23368 case 102: ...
23369
23370 \newline
23371 \SpecialChar ~
23372 \SpecialChar ~
23373 case 103: ...
23374
23375 \newline
23376 \SpecialChar ~
23377 \SpecialChar ~
23378 case 104: ...
23379
23380 \newline
23381 \SpecialChar ~
23382 \SpecialChar ~
23383 case 105: ...
23384
23385 \newline
23386 \SpecialChar ~
23387 \SpecialChar ~
23388 case 106: ...
23389
23390 \newline
23391 \SpecialChar ~
23392 \SpecialChar ~
23393 case 107: ...
23394
23395 \newline
23396 }
23397 \layout Standard
23398
23399 then both the switch statements will be implemented using jump-tables whereas
23400  the unmodified switch statement will not be.
23401 \layout Comment
23402
23403 There might be reasons which SDCC cannot know about to either favour or
23404  not favour jump tables.
23405  If the target system has to be as quick for the last switch case as for
23406  the first (pro jump table), or if the switch argument is known to be zero
23407  in the majority of the cases (contra jump table).
23408 \layout Standard
23409
23410 The pragma nojtbound
23411 \begin_inset LatexCommand \index{\#pragma nojtbound}
23412
23413 \end_inset
23414
23415  can be used to turn off checking the
23416 \emph on
23417 j
23418 \emph default
23419 ump
23420 \emph on
23421 t
23422 \emph default
23423 able
23424 \emph on
23425 bound
23426 \emph default
23427 aries.
23428  It has no effect if a default label is supplied.
23429  Use of this pragma is dangerous: if the switch argument is not matched
23430  by a case statement the processor will happily jump into Nirvana.
23431 \layout Subsection
23432
23433 Bit-shifting Operations
23434 \begin_inset LatexCommand \index{Bit shifting}
23435
23436 \end_inset
23437
23438 .
23439 \layout Standard
23440
23441 Bit shifting is one of the most frequently used operation in embedded programmin
23442 g.
23443  SDCC tries to implement bit-shift operations in the most efficient way
23444  possible, e.g.:
23445 \layout Verse
23446
23447
23448 \family typewriter
23449 unsigned char i;
23450 \newline
23451 ...
23452
23453 \newline
23454 i >>= 4;
23455 \newline
23456 ...
23457 \layout Standard
23458
23459 generates the following code:
23460 \layout Verse
23461
23462
23463 \family typewriter
23464 mov\SpecialChar ~
23465  a,_i
23466 \newline
23467 swap a
23468 \newline
23469 anl\SpecialChar ~
23470  a,#0x0f
23471 \newline
23472 mov\SpecialChar ~
23473  _i,a
23474 \layout Standard
23475
23476 In general SDCC will never setup a loop if the shift count is known.
23477  Another example:
23478 \layout Verse
23479
23480
23481 \family typewriter
23482 unsigned int i;
23483 \newline
23484 ...
23485
23486 \newline
23487 i >>= 9;
23488 \newline
23489 ...
23490 \layout Standard
23491
23492 will generate:
23493 \layout Verse
23494
23495
23496 \family typewriter
23497 mov\SpecialChar ~
23498 \SpecialChar ~
23499 a,(_i + 1)
23500 \newline
23501 mov\SpecialChar ~
23502 \SpecialChar ~
23503 (_i + 1),#0x00
23504 \newline
23505 clr\SpecialChar ~
23506 \SpecialChar ~
23507 c
23508 \newline
23509 rrc\SpecialChar ~
23510 \SpecialChar ~
23511 a
23512 \newline
23513 mov\SpecialChar ~
23514 \SpecialChar ~
23515 _i,a
23516 \layout Subsection
23517
23518 Bit-rotation
23519 \begin_inset LatexCommand \index{Bit rotation}
23520
23521 \end_inset
23522
23523
23524 \layout Standard
23525
23526 A special case of the bit-shift operation is bit rotation
23527 \begin_inset LatexCommand \index{rotating bits}
23528
23529 \end_inset
23530
23531 , SDCC recognizes the following expression to be a left bit-rotation:
23532 \layout Verse
23533
23534
23535 \family typewriter
23536 \series bold
23537 unsigned
23538 \series default
23539 \SpecialChar ~
23540 \SpecialChar ~
23541 char i;\SpecialChar ~
23542 \SpecialChar ~
23543 \SpecialChar ~
23544 \SpecialChar ~
23545 \SpecialChar ~
23546 \SpecialChar ~
23547 \SpecialChar ~
23548 \SpecialChar ~
23549 \SpecialChar ~
23550 \SpecialChar ~
23551 \SpecialChar ~
23552 /* unsigned is needed for rotation */
23553 \newline
23554 ...
23555
23556 \newline
23557 i = ((i << 1) | (i >> 7));
23558 \family default
23559
23560 \newline
23561
23562 \family typewriter
23563 ...
23564 \layout Standard
23565
23566 will generate the following code:
23567 \layout Verse
23568
23569
23570 \family typewriter
23571 mov\SpecialChar ~
23572 \SpecialChar ~
23573 a,_i
23574 \newline
23575 rl\SpecialChar ~
23576 \SpecialChar ~
23577 \SpecialChar ~
23578 a
23579 \newline
23580 mov\SpecialChar ~
23581 \SpecialChar ~
23582 _i,a
23583 \layout Standard
23584
23585 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
23586 ns of this case will also be recognized as bit-rotation, i.e.:
23587 \layout Verse
23588
23589
23590 \family typewriter
23591 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
23592 \layout Subsection
23593
23594 Nibble and Byte Swapping
23595 \layout Standard
23596
23597 Other special cases of the bit-shift operations are nibble or byte swapping
23598 \begin_inset LatexCommand \index{swapping nibbles/bytes}
23599
23600 \end_inset
23601
23602 , SDCC recognizes the following expressions:
23603 \layout Verse
23604
23605
23606 \family typewriter
23607 \series bold
23608 unsigned
23609 \series default
23610 \SpecialChar ~
23611 \SpecialChar ~
23612 char i;
23613 \newline
23614
23615 \series bold
23616 unsigned
23617 \series default
23618 \SpecialChar ~
23619 \SpecialChar ~
23620 int j;
23621 \newline
23622 ...
23623
23624 \newline
23625 i = ((i << 4) | (i >> 4));
23626 \family default
23627
23628 \newline
23629
23630 \family typewriter
23631 j = ((j << 8) | (j >> 8));
23632 \layout Standard
23633
23634 and generates a swap instruction for the nibble swapping
23635 \begin_inset LatexCommand \index{Nibble swapping}
23636
23637 \end_inset
23638
23639  or move instructions for the byte swapping
23640 \begin_inset LatexCommand \index{Byte swapping}
23641
23642 \end_inset
23643
23644 .
23645  The
23646 \begin_inset Quotes sld
23647 \end_inset
23648
23649 j
23650 \begin_inset Quotes srd
23651 \end_inset
23652
23653  example can be used to convert from little to big-endian or vice versa.
23654  If you want to change the endianness of a
23655 \emph on
23656 signed
23657 \emph default
23658  integer you have to cast to
23659 \family typewriter
23660 (unsigned int)
23661 \family default
23662  first.
23663 \layout Standard
23664
23665 Note that SDCC stores numbers in little-endian
23666 \begin_inset Foot
23667 collapsed false
23668
23669 \layout Standard
23670
23671 Usually 8-bit processors don't care much about endianness.
23672  This is not the case for the standard 8051 which only has an instruction
23673  to increment its
23674 \emph on
23675 dptr
23676 \emph default
23677
23678 \begin_inset LatexCommand \index{DPTR}
23679
23680 \end_inset
23681
23682 -datapointer
23683 \emph on
23684
23685 \emph default
23686 so little-endian is the more efficient byte order.
23687 \end_inset
23688
23689
23690 \begin_inset LatexCommand \index{little-endian}
23691
23692 \end_inset
23693
23694
23695 \begin_inset LatexCommand \index{Endianness}
23696
23697 \end_inset
23698
23699  format (i.e.
23700  lowest order first).
23701 \layout Subsection
23702
23703 Highest Order Bit
23704 \begin_inset LatexCommand \index{Highest Order Bit}
23705
23706 \end_inset
23707
23708
23709 \layout Standard
23710
23711 It is frequently required to obtain the highest order bit of an integral
23712  type (long, int, short or char types).
23713  SDCC recognizes the following expression to yield the highest order bit
23714  and generates optimized code for it, e.g.:
23715 \layout Verse
23716
23717
23718 \family typewriter
23719 unsigned int gint;
23720 \newline
23721
23722 \newline
23723 foo () {
23724 \newline
23725 \SpecialChar ~
23726 \SpecialChar ~
23727 unsigned char hob;
23728 \newline
23729 \SpecialChar ~
23730 \SpecialChar ~
23731 ...
23732
23733 \newline
23734 \SpecialChar ~
23735 \SpecialChar ~
23736 hob = (gint >> 15) & 1;
23737 \newline
23738 \SpecialChar ~
23739 \SpecialChar ~
23740 ..
23741
23742 \newline
23743 }
23744 \layout Standard
23745
23746 will generate the following code:
23747 \layout Verse
23748
23749
23750 \family typewriter
23751 \SpecialChar ~
23752 \SpecialChar ~
23753 \SpecialChar ~
23754 \SpecialChar ~
23755 \SpecialChar ~
23756 \SpecialChar ~
23757 \SpecialChar ~
23758 \SpecialChar ~
23759 \SpecialChar ~
23760 \SpecialChar ~
23761 \SpecialChar ~
23762 \SpecialChar ~
23763 \SpecialChar ~
23764 \SpecialChar ~
23765 \SpecialChar ~
23766 \SpecialChar ~
23767 \SpecialChar ~
23768 \SpecialChar ~
23769 \SpecialChar ~
23770 \SpecialChar ~
23771 \SpecialChar ~
23772 \SpecialChar ~
23773 \SpecialChar ~
23774 \SpecialChar ~
23775 \SpecialChar ~
23776  61 ;\SpecialChar ~
23777  hob.c 7
23778 \newline
23779 000A E5*01\SpecialChar ~
23780 \SpecialChar ~
23781 \SpecialChar ~
23782 \SpecialChar ~
23783 \SpecialChar ~
23784 \SpecialChar ~
23785 \SpecialChar ~
23786 \SpecialChar ~
23787 \SpecialChar ~
23788 \SpecialChar ~
23789 \SpecialChar ~
23790 \SpecialChar ~
23791 \SpecialChar ~
23792 \SpecialChar ~
23793 \SpecialChar ~
23794  62\SpecialChar ~
23795 \SpecialChar ~
23796 \SpecialChar ~
23797 \SpecialChar ~
23798 \SpecialChar ~
23799 \SpecialChar ~
23800 \SpecialChar ~
23801 \SpecialChar ~
23802  mov\SpecialChar ~
23803 \SpecialChar ~
23804  a,(_gint + 1)
23805 \newline
23806 000C 23\SpecialChar ~
23807 \SpecialChar ~
23808 \SpecialChar ~
23809 \SpecialChar ~
23810 \SpecialChar ~
23811 \SpecialChar ~
23812 \SpecialChar ~
23813 \SpecialChar ~
23814 \SpecialChar ~
23815 \SpecialChar ~
23816 \SpecialChar ~
23817 \SpecialChar ~
23818 \SpecialChar ~
23819 \SpecialChar ~
23820 \SpecialChar ~
23821 \SpecialChar ~
23822 \SpecialChar ~
23823 \SpecialChar ~
23824  63\SpecialChar ~
23825 \SpecialChar ~
23826 \SpecialChar ~
23827 \SpecialChar ~
23828 \SpecialChar ~
23829 \SpecialChar ~
23830 \SpecialChar ~
23831 \SpecialChar ~
23832  rl\SpecialChar ~
23833 \SpecialChar ~
23834 \SpecialChar ~
23835  a
23836 \newline
23837 000D 54 01\SpecialChar ~
23838 \SpecialChar ~
23839 \SpecialChar ~
23840 \SpecialChar ~
23841 \SpecialChar ~
23842 \SpecialChar ~
23843 \SpecialChar ~
23844 \SpecialChar ~
23845 \SpecialChar ~
23846 \SpecialChar ~
23847 \SpecialChar ~
23848 \SpecialChar ~
23849 \SpecialChar ~
23850 \SpecialChar ~
23851 \SpecialChar ~
23852  64\SpecialChar ~
23853 \SpecialChar ~
23854 \SpecialChar ~
23855 \SpecialChar ~
23856 \SpecialChar ~
23857 \SpecialChar ~
23858 \SpecialChar ~
23859 \SpecialChar ~
23860  anl\SpecialChar ~
23861 \SpecialChar ~
23862  a,#0x01
23863 \newline
23864 000F F5*02\SpecialChar ~
23865 \SpecialChar ~
23866 \SpecialChar ~
23867 \SpecialChar ~
23868 \SpecialChar ~
23869 \SpecialChar ~
23870 \SpecialChar ~
23871 \SpecialChar ~
23872 \SpecialChar ~
23873 \SpecialChar ~
23874 \SpecialChar ~
23875 \SpecialChar ~
23876 \SpecialChar ~
23877 \SpecialChar ~
23878 \SpecialChar ~
23879  65\SpecialChar ~
23880 \SpecialChar ~
23881 \SpecialChar ~
23882 \SpecialChar ~
23883 \SpecialChar ~
23884 \SpecialChar ~
23885 \SpecialChar ~
23886 \SpecialChar ~
23887  mov\SpecialChar ~
23888 \SpecialChar ~
23889  _foo_hob_1_1,a
23890 \layout Standard
23891
23892 Variations of this case however will
23893 \emph on
23894 not
23895 \emph default
23896  be recognized.
23897  It is a standard C expression, so I heartily recommend this be the only
23898  way to get the highest order bit, (it is portable).
23899  Of course it will be recognized even if it is embedded in other expressions,
23900  e.g.:
23901 \layout Verse
23902
23903
23904 \family typewriter
23905 xyz = gint + ((gint >> 15) & 1);
23906 \layout Standard
23907
23908 will still be recognized.
23909 \layout Subsection
23910
23911 Peephole Optimizer
23912 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
23913
23914 \end_inset
23915
23916
23917 \begin_inset LatexCommand \index{Peephole optimizer}
23918
23919 \end_inset
23920
23921
23922 \layout Standard
23923
23924 The compiler uses a rule based, pattern matching and re-writing mechanism
23925  for peep-hole optimization.
23926  It is inspired by
23927 \emph on
23928 copt
23929 \emph default
23930  a peep-hole optimizer by Christopher W.
23931  Fraser (cwfraser@microsoft.com).
23932  A default set of rules are compiled into the compiler, additional rules
23933  may be added with the
23934 \emph on
23935 -
23936 \begin_inset ERT
23937 status Collapsed
23938
23939 \layout Standard
23940
23941 \backslash
23942 /
23943 \end_inset
23944
23945 -peep-file
23946 \begin_inset LatexCommand \index{-\/-peep-file}
23947
23948 \end_inset
23949
23950  <filename>
23951 \emph default
23952  option.
23953  The rule language is best illustrated with examples.
23954 \layout Verse
23955
23956
23957 \family typewriter
23958 replace {
23959 \newline
23960 \SpecialChar ~
23961 \SpecialChar ~
23962 mov %1,a
23963 \newline
23964 \SpecialChar ~
23965 \SpecialChar ~
23966 mov a,%1
23967 \newline
23968 } by {
23969 \newline
23970 \SpecialChar ~
23971 \SpecialChar ~
23972 mov %1,a
23973 \newline
23974 }
23975 \layout Standard
23976
23977 The above rule will change the following assembly
23978 \begin_inset LatexCommand \index{Assembler routines}
23979
23980 \end_inset
23981
23982  sequence:
23983 \layout Verse
23984
23985
23986 \family typewriter
23987 mov r1,a
23988 \newline
23989 mov a,r1
23990 \layout Standard
23991
23992 to
23993 \layout Verse
23994
23995
23996 \family typewriter
23997 mov r1,a
23998 \layout Standard
23999
24000 Note: All occurrences of a
24001 \emph on
24002 %n
24003 \emph default
24004  (pattern variable) must denote the same string.
24005  With the above rule, the assembly sequence:
24006 \layout Verse
24007
24008
24009 \family typewriter
24010 mov r1,a
24011 \newline
24012 mov a,r2
24013 \layout Standard
24014
24015 will remain unmodified.
24016 \newline
24017
24018 \newline
24019 Other special case optimizations may be added by the user (via
24020 \emph on
24021 -
24022 \begin_inset ERT
24023 status Collapsed
24024
24025 \layout Standard
24026
24027 \backslash
24028 /
24029 \end_inset
24030
24031 -peep-file option
24032 \emph default
24033 ).
24034  E.g.
24035  some variants of the 8051 MCU
24036 \begin_inset LatexCommand \index{MCS51 variants}
24037
24038 \end_inset
24039
24040  allow only
24041 \family typewriter
24042 ajmp
24043 \family default
24044  and
24045 \family typewriter
24046 acall
24047 \family default
24048 .
24049  The following two rules will change all
24050 \family typewriter
24051 ljmp
24052 \family default
24053  and
24054 \family typewriter
24055 lcall
24056 \family default
24057  to
24058 \family typewriter
24059 ajmp
24060 \family default
24061  and
24062 \family typewriter
24063 acall
24064 \layout Verse
24065
24066
24067 \family typewriter
24068 replace { lcall %1 } by { acall %1 }
24069 \newline
24070 replace { ljmp %1 } by { ajmp %1 }
24071 \layout Standard
24072
24073 The
24074 \emph on
24075 inline-assembler code
24076 \emph default
24077  is also passed through the peep hole optimizer, thus the peephole optimizer
24078  can also be used as an assembly level macro expander.
24079  The rules themselves are MCU dependent whereas the rule language infra-structur
24080 e is MCU independent.
24081  Peephole optimization rules for other MCU can be easily programmed using
24082  the rule language.
24083 \newline
24084
24085 \newline
24086 The syntax for a rule is as follows:
24087 \layout Verse
24088
24089
24090 \family typewriter
24091 rule := replace [ restart ] '{' <assembly sequence> '
24092 \backslash
24093 n'
24094 \newline
24095 \SpecialChar ~
24096  \SpecialChar ~
24097  \SpecialChar ~
24098  \SpecialChar ~
24099  \SpecialChar ~
24100  \SpecialChar ~
24101  \SpecialChar ~
24102  \SpecialChar ~
24103  \SpecialChar ~
24104  \SpecialChar ~
24105  \SpecialChar ~
24106  \SpecialChar ~
24107  \SpecialChar ~
24108  \SpecialChar ~
24109  '}' by '{' '
24110 \backslash
24111 n'
24112 \newline
24113 \SpecialChar ~
24114  \SpecialChar ~
24115  \SpecialChar ~
24116  \SpecialChar ~
24117  \SpecialChar ~
24118  \SpecialChar ~
24119  \SpecialChar ~
24120  \SpecialChar ~
24121  \SpecialChar ~
24122  \SpecialChar ~
24123  \SpecialChar ~
24124  \SpecialChar ~
24125  \SpecialChar ~
24126  \SpecialChar ~
24127  \SpecialChar ~
24128  \SpecialChar ~
24129  <assembly sequence> '
24130 \backslash
24131 n'
24132 \newline
24133 \SpecialChar ~
24134  \SpecialChar ~
24135  \SpecialChar ~
24136  \SpecialChar ~
24137  \SpecialChar ~
24138  \SpecialChar ~
24139  \SpecialChar ~
24140  \SpecialChar ~
24141  \SpecialChar ~
24142  \SpecialChar ~
24143  \SpecialChar ~
24144  \SpecialChar ~
24145  \SpecialChar ~
24146  \SpecialChar ~
24147  '}' [if <functionName> ] '
24148 \backslash
24149 n'
24150 \layout Standard
24151
24152 <assembly sequence> := assembly instruction (each instruction including
24153  labels must be on a separate line).
24154 \newline
24155
24156 \newline
24157 The optimizer will apply to the rules one by one from the top in the sequence
24158  of their appearance, it will terminate when all rules are exhausted.
24159  If the 'restart' option is specified, then the optimizer will start matching
24160  the rules again from the top, this option for a rule is expensive (performance)
24161 , it is intended to be used in situations where a transformation will trigger
24162  the same rule again.
24163  An example of this (not a good one, it has side effects) is the following
24164  rule:
24165 \layout Verse
24166
24167
24168 \family typewriter
24169 replace restart {
24170 \newline
24171 \SpecialChar ~
24172 \SpecialChar ~
24173 pop %1
24174 \newline
24175 \SpecialChar ~
24176 \SpecialChar ~
24177 push %1 } by {
24178 \newline
24179 \SpecialChar ~
24180 \SpecialChar ~
24181 ; nop
24182 \newline
24183 }
24184 \layout Standard
24185
24186 Note that the replace pattern cannot be a blank, but can be a comment line.
24187  Without the 'restart' option only the innermost 'pop' 'push' pair would
24188  be eliminated, i.e.:
24189 \layout Verse
24190
24191
24192 \family typewriter
24193 pop ar1
24194 \newline
24195 pop ar2
24196 \newline
24197 push ar2
24198 \newline
24199 push ar1
24200 \layout Standard
24201
24202 would result in:
24203 \layout Verse
24204
24205
24206 \family typewriter
24207 pop ar1
24208 \newline
24209 ; nop
24210 \newline
24211 push ar1
24212 \layout Standard
24213
24214
24215 \emph on
24216 with
24217 \emph default
24218  the restart option the rule will be applied again to the resulting code
24219  and then all the pop-push pairs will be eliminated to yield:
24220 \layout Verse
24221
24222
24223 \family typewriter
24224 ; nop
24225 \newline
24226 ; nop
24227 \layout Standard
24228
24229 A conditional function can be attached to a rule.
24230  Attaching rules are somewhat more involved, let me illustrate this with
24231  an example.
24232 \layout Verse
24233
24234
24235 \family typewriter
24236 replace {
24237 \newline
24238 \SpecialChar ~
24239  \SpecialChar ~
24240  \SpecialChar ~
24241 ljmp %5
24242 \newline
24243 %2:
24244 \newline
24245 } by {
24246 \newline
24247 \SpecialChar ~
24248  \SpecialChar ~
24249  \SpecialChar ~
24250 sjmp %5
24251 \newline
24252 %2:
24253 \newline
24254 } if labelInRange
24255 \layout Standard
24256
24257 The optimizer does a look-up of a function name table defined in function
24258
24259 \emph on
24260 callFuncByName
24261 \emph default
24262  in the source file SDCCpeeph.c, with the name
24263 \emph on
24264 labelInRange
24265 \emph default
24266 .
24267  If it finds a corresponding entry the function is called.
24268  Note there can be no parameters specified for these functions, in this
24269  case the use of
24270 \emph on
24271 %5
24272 \emph default
24273  is crucial, since the function
24274 \emph on
24275 labelInRange
24276 \emph default
24277  expects to find the label in that particular variable (the hash table containin
24278 g the variable bindings is passed as a parameter).
24279  If you want to code more such functions, take a close look at the function
24280  labelInRange and the calling mechanism in source file SDCCpeeph.c.
24281  Currently implemented are
24282 \emph on
24283 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
24284  24bitMode, portIsDS390, 24bitModeAndPortDS390
24285 \emph default
24286 and
24287 \emph on
24288  notVolatile
24289 \emph default
24290 .
24291 \layout Standard
24292
24293 I know this whole thing is a little kludgey, but maybe some day we will
24294  have some better means.
24295  If you are looking at this file, you will see the default rules that are
24296  compiled into the compiler, you can add your own rules in the default set
24297  there if you get tired of specifying the -
24298 \begin_inset ERT
24299 status Collapsed
24300
24301 \layout Standard
24302
24303 \backslash
24304 /
24305 \end_inset
24306
24307 -peep-file option.
24308 \layout Section
24309
24310 ANSI-Compliance
24311 \begin_inset LatexCommand \index{ANSI-compliance}
24312
24313 \end_inset
24314
24315
24316 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
24317
24318 \end_inset
24319
24320
24321 \layout Standard
24322
24323 Deviations from the compliance:
24324 \layout Itemize
24325
24326 functions are not reentrant
24327 \begin_inset LatexCommand \index{reentrant}
24328
24329 \end_inset
24330
24331  unless explicitly declared as such or the
24332 \series bold
24333 -
24334 \begin_inset ERT
24335 status Collapsed
24336
24337 \layout Standard
24338
24339 \backslash
24340 /
24341 \end_inset
24342
24343 -stack-auto
24344 \begin_inset LatexCommand \index{-\/-stack-auto}
24345
24346 \end_inset
24347
24348
24349 \series default
24350  command line option is specified.
24351 \layout Itemize
24352
24353 structures and unions cannot be assigned values directly, cannot be passed
24354  as function parameters or assigned to each other and cannot be a return
24355  value from a function, e.g.:
24356 \begin_deeper
24357 \layout Verse
24358
24359
24360 \family typewriter
24361 struct s { ...
24362  };
24363 \newline
24364 struct s s1, s2;
24365 \newline
24366 foo()
24367 \newline
24368 {
24369 \newline
24370 \SpecialChar ~
24371 \SpecialChar ~
24372 \SpecialChar ~
24373 \SpecialChar ~
24374 ...
24375
24376 \newline
24377 \SpecialChar ~
24378 \SpecialChar ~
24379 \SpecialChar ~
24380 \SpecialChar ~
24381 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
24382 \newline
24383 \SpecialChar ~
24384 \SpecialChar ~
24385 \SpecialChar ~
24386 \SpecialChar ~
24387 ...
24388
24389 \newline
24390 }
24391 \newline
24392 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
24393  */
24394 \newline
24395 {
24396 \newline
24397 \SpecialChar ~
24398 \SpecialChar ~
24399 \SpecialChar ~
24400 \SpecialChar ~
24401 struct s rets;
24402 \newline
24403 \SpecialChar ~
24404 \SpecialChar ~
24405 \SpecialChar ~
24406 \SpecialChar ~
24407 ...
24408
24409 \newline
24410 \SpecialChar ~
24411 \SpecialChar ~
24412 \SpecialChar ~
24413 \SpecialChar ~
24414 return rets;/* is invalid in SDCC although allowed in ANSI */
24415 \newline
24416 }
24417 \end_deeper
24418 \layout Itemize
24419
24420 'long long
24421 \begin_inset LatexCommand \index{long long (not supported)}
24422
24423 \end_inset
24424
24425 ' (64 bit integers
24426 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
24427
24428 \end_inset
24429
24430 ) not supported.
24431 \layout Itemize
24432
24433 'double
24434 \begin_inset LatexCommand \index{double (not supported)}
24435
24436 \end_inset
24437
24438 ' precision floating point
24439 \begin_inset LatexCommand \index{Floating point support}
24440
24441 \end_inset
24442
24443 not supported.
24444 \layout Itemize
24445
24446 No support for setjmp
24447 \begin_inset LatexCommand \index{setjmp (not supported)}
24448
24449 \end_inset
24450
24451  and longjmp
24452 \begin_inset LatexCommand \index{longjmp (not supported)}
24453
24454 \end_inset
24455
24456  (for now).
24457 \layout Itemize
24458
24459 Certain words that are valid identifiers in the standard may be reserved
24460  words in SDCC unless the
24461 \series bold
24462 -
24463 \begin_inset ERT
24464 status Collapsed
24465
24466 \layout Standard
24467
24468 \backslash
24469 /
24470 \end_inset
24471
24472 -std-c89
24473 \begin_inset LatexCommand \index{-\/-std-c89}
24474
24475 \end_inset
24476
24477  or -
24478 \begin_inset ERT
24479 status Collapsed
24480
24481 \layout Standard
24482
24483 \backslash
24484 /
24485 \end_inset
24486
24487 -std-c99
24488 \begin_inset LatexCommand \index{-\/-std-c99}
24489
24490 \end_inset
24491
24492
24493 \series default
24494  command line options are used.
24495 \layout Itemize
24496
24497 Old K&R style
24498 \begin_inset LatexCommand \index{K\&R style}
24499
24500 \end_inset
24501
24502  function declarations are NOT allowed.
24503 \begin_deeper
24504 \layout Verse
24505
24506
24507 \family typewriter
24508 foo(i,j) /* this old style of function declarations */
24509 \newline
24510 int i,j; /* are valid in ANSI but not valid in SDCC */
24511 \newline
24512 {
24513 \newline
24514 \SpecialChar ~
24515 \SpecialChar ~
24516 \SpecialChar ~
24517 \SpecialChar ~
24518 ...
24519
24520 \newline
24521 }
24522 \end_deeper
24523 \layout Itemize
24524
24525 Certain words that are valid identifiers in the standard may be reserved
24526  words in SDCC unless the
24527 \series bold
24528 -
24529 \begin_inset ERT
24530 status Collapsed
24531
24532 \layout Standard
24533
24534 \backslash
24535 /
24536 \end_inset
24537
24538 -std-c89
24539 \begin_inset LatexCommand \index{-\/-std-c89}
24540
24541 \end_inset
24542
24543  or -
24544 \begin_inset ERT
24545 status Collapsed
24546
24547 \layout Standard
24548
24549 \backslash
24550 /
24551 \end_inset
24552
24553 -std-c99
24554 \begin_inset LatexCommand \index{-\/-std-c99}
24555
24556 \end_inset
24557
24558
24559 \series default
24560  command line options are used.
24561  These may include (depending on the selected processor): 'at', 'banked',
24562  'bit', 'code', 'critical', 'data', 'eeprom', 'far', 'flash', 'idata', 'interrup
24563 t', 'near', 'nonbanked', 'pdata', 'reentrant', 'sbit', 'sfr', 'shadowregs',
24564  'sram', 'using', 'wparam', 'xdata', '_overlay', '_asm', '_endasm', and
24565  '_naked'.
24566  Compliant equivalents of these keywords are always available in a form
24567  that begin with two underscores, f.e.
24568  '__data' instead of 'data'.
24569 \layout Section
24570
24571 Cyclomatic Complexity
24572 \begin_inset LatexCommand \index{Cyclomatic complexity}
24573
24574 \end_inset
24575
24576
24577 \layout Standard
24578
24579 Cyclomatic complexity of a function is defined as the number of independent
24580  paths the program can take during execution of the function.
24581  This is an important number since it defines the number test cases you
24582  have to generate to validate the function.
24583  The accepted industry standard for complexity number is 10, if the cyclomatic
24584  complexity reported by SDCC exceeds 10 you should think about simplification
24585  of the function logic.
24586  Note that the complexity level is not related to the number of lines of
24587  code in a function.
24588  Large functions can have low complexity, and small functions can have large
24589  complexity levels.
24590
24591 \newline
24592
24593 \newline
24594 SDCC uses the following formula to compute the complexity:
24595 \newline
24596
24597 \layout Standard
24598
24599 complexity = (number of edges in control flow graph) - (number of nodes
24600  in control flow graph) + 2;
24601 \newline
24602
24603 \newline
24604 Having said that the industry standard is 10, you should be aware that in
24605  some cases it be may unavoidable to have a complexity level of less than
24606  10.
24607  For example if you have switch statement with more than 10 case labels,
24608  each case label adds one to the complexity level.
24609  The complexity level is by no means an absolute measure of the algorithmic
24610  complexity of the function, it does however provide a good starting point
24611  for which functions you might look at for further optimization.
24612 \layout Section
24613
24614 Retargetting for other Processors
24615 \layout Standard
24616
24617 The issues for retargetting the compiler are far too numerous to be covered
24618  by this document.
24619  What follows is a brief description of each of the seven phases of the
24620  compiler and its MCU dependency.
24621 \layout Itemize
24622
24623 Parsing the source and building the annotated parse tree.
24624  This phase is largely MCU independent (except for the language extensions).
24625  Syntax & semantic checks are also done in this phase, along with some initial
24626  optimizations like back patching labels and the pattern matching optimizations
24627  like bit-rotation etc.
24628 \layout Itemize
24629
24630 The second phase involves generating an intermediate code which can be easy
24631  manipulated during the later phases.
24632  This phase is entirely MCU independent.
24633  The intermediate code generation assumes the target machine has unlimited
24634  number of registers, and designates them with the name iTemp.
24635  The compiler can be made to dump a human readable form of the code generated
24636  by using the -
24637 \begin_inset ERT
24638 status Collapsed
24639
24640 \layout Standard
24641
24642 \backslash
24643 /
24644 \end_inset
24645
24646 -dumpraw option.
24647 \layout Itemize
24648
24649 This phase does the bulk of the standard optimizations and is also MCU independe
24650 nt.
24651  This phase can be broken down into several sub-phases:
24652 \newline
24653
24654 \newline
24655 Break down intermediate code (iCode) into basic blocks.
24656 \newline
24657 Do control flow & data flow analysis on the basic blocks.
24658 \newline
24659 Do local common subexpression elimination, then global subexpression elimination
24660 \newline
24661 Dead code elimination
24662 \newline
24663 Loop optimizations
24664 \newline
24665 If loop optimizations caused any changes then do 'global subexpression eliminati
24666 on' and 'dead code elimination' again.
24667 \layout Itemize
24668
24669 This phase determines the live-ranges; by live range I mean those iTemp
24670  variables defined by the compiler that still survive after all the optimization
24671 s.
24672  Live range analysis
24673 \begin_inset LatexCommand \index{Live range analysis}
24674
24675 \end_inset
24676
24677  is essential for register allocation, since these computation determines
24678  which of these iTemps will be assigned to registers, and for how long.
24679 \layout Itemize
24680
24681 Phase five is register allocation.
24682  There are two parts to this process.
24683 \newline
24684
24685 \newline
24686 The first part I call 'register packing' (for lack of a better term).
24687  In this case several MCU specific expression folding is done to reduce
24688  register pressure.
24689 \newline
24690
24691 \newline
24692 The second part is more MCU independent and deals with allocating registers
24693  to the remaining live ranges.
24694  A lot of MCU specific code does creep into this phase because of the limited
24695  number of index registers available in the 8051.
24696 \layout Itemize
24697
24698 The Code generation phase is (unhappily), entirely MCU dependent and very
24699  little (if any at all) of this code can be reused for other MCU.
24700  However the scheme for allocating a homogenized assembler operand for each
24701  iCode operand may be reused.
24702 \layout Itemize
24703
24704 As mentioned in the optimization section the peep-hole optimizer is rule
24705  based system, which can reprogrammed for other MCUs.
24706 \layout Chapter
24707
24708 Compiler internals
24709 \begin_inset LatexCommand \index{Compiler internals}
24710
24711 \end_inset
24712
24713
24714 \layout Section
24715
24716 The anatomy of the compiler
24717 \begin_inset LatexCommand \label{sub:The-anatomy-of}
24718
24719 \end_inset
24720
24721
24722 \layout Standard
24723
24724
24725 \shape italic
24726 This is an excerpt from an article published in Circuit Cellar Magazine
24727  in august 2000.
24728  It's a little outdated (the compiler is much more efficient now and user/develo
24729 per friendly), but pretty well exposes the guts of it all.
24730 \shape default
24731
24732 \newline
24733
24734 \newline
24735 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
24736  It is fairly easy to retarget for other 8-bit MCU.
24737  Here we take a look at some of the internals of the compiler.
24738
24739 \layout Paragraph*
24740
24741 Parsing
24742 \begin_inset LatexCommand \index{Parsing}
24743
24744 \end_inset
24745
24746
24747 \layout Standard
24748
24749 Parsing the input source file and creating an AST (Annotated Syntax Tree
24750 \begin_inset LatexCommand \index{Annotated syntax tree}
24751
24752 \end_inset
24753
24754 ).
24755  This phase also involves propagating types (annotating each node of the
24756  parse tree with type information) and semantic analysis.
24757  There are some MCU specific parsing rules.
24758  For example the storage classes, the extended storage classes are MCU specific
24759  while there may be a xdata storage class for 8051 there is no such storage
24760  class for z80 or Atmel AVR.
24761  SDCC allows MCU specific storage class extensions, i.e.
24762  xdata will be treated as a storage class specifier when parsing 8051 C
24763  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
24764  C code.
24765 \layout Paragraph*
24766
24767 Generating iCode
24768 \begin_inset LatexCommand \index{iCode}
24769
24770 \end_inset
24771
24772
24773 \layout Standard
24774
24775 Intermediate code generation.
24776  In this phase the AST is broken down into three-operand form (iCode).
24777  These three operand forms are represented as doubly linked lists.
24778  ICode is the term given to the intermediate form generated by the compiler.
24779  ICode example section shows some examples of iCode generated for some simple
24780  C source functions.
24781 \layout Paragraph*
24782
24783 Optimizations
24784 \begin_inset LatexCommand \index{Optimizations}
24785
24786 \end_inset
24787
24788 .
24789 \layout Standard
24790
24791 Bulk of the target independent optimizations is performed in this phase.
24792  The optimizations include constant propagation, common sub-expression eliminati
24793 on, loop invariant code movement, strength reduction of loop induction variables
24794  and dead-code elimination.
24795 \layout Paragraph*
24796
24797 Live range analysis
24798 \begin_inset LatexCommand \index{Live range analysis}
24799
24800 \end_inset
24801
24802
24803 \layout Standard
24804
24805 During intermediate code generation phase, the compiler assumes the target
24806  machine has infinite number of registers and generates a lot of temporary
24807  variables.
24808  The live range computation determines the lifetime of each of these compiler-ge
24809 nerated temporaries.
24810  A picture speaks a thousand words.
24811  ICode example sections show the live range annotations for each of the
24812  operand.
24813  It is important to note here, each iCode is assigned a number in the order
24814  of its execution in the function.
24815  The live ranges are computed in terms of these numbers.
24816  The from number is the number of the iCode which first defines the operand
24817  and the to number signifies the iCode which uses this operand last.
24818 \layout Paragraph*
24819
24820 Register Allocation
24821 \begin_inset LatexCommand \index{Register allocation}
24822
24823 \end_inset
24824
24825
24826 \layout Standard
24827
24828 The register allocation determines the type and number of registers needed
24829  by each operand.
24830  In most MCUs only a few registers can be used for indirect addressing.
24831  In case of 8051 for example the registers R0 & R1 can be used to indirectly
24832  address the internal ram and DPTR to indirectly address the external ram.
24833  The compiler will try to allocate the appropriate register to pointer variables
24834  if it can.
24835  ICode example section shows the operands annotated with the registers assigned
24836  to them.
24837  The compiler will try to keep operands in registers as much as possible;
24838  there are several schemes the compiler uses to do achieve this.
24839  When the compiler runs out of registers the compiler will check to see
24840  if there are any live operands which is not used or defined in the current
24841  basic block being processed, if there are any found then it will push that
24842  operand and use the registers in this block, the operand will then be popped
24843  at the end of the basic block.
24844
24845 \layout Standard
24846
24847 There are other MCU specific considerations in this phase.
24848  Some MCUs have an accumulator; very short-lived operands could be assigned
24849  to the accumulator instead of a general-purpose register.
24850 \layout Paragraph*
24851
24852 Code generation
24853 \layout Standard
24854
24855 Figure II gives a table of iCode operations supported by the compiler.
24856  The code generation involves translating these operations into corresponding
24857  assembly code for the processor.
24858  This sounds overly simple but that is the essence of code generation.
24859  Some of the iCode operations are generated on a MCU specific manner for
24860  example, the z80 port does not use registers to pass parameters so the
24861  SEND and RECV iCode operations will not be generated, and it also does
24862  not support JUMPTABLES.
24863
24864 \newline
24865
24866 \series bold
24867 \shape italic
24868 \color red
24869 <Where is Figure II?>
24870 \layout Comment
24871
24872 In the original article Figure II was announced to be downloadable on
24873 \shape italic
24874 Circuit Cellar
24875 \shape default
24876 's web site.
24877  Unfortunately it never seemed to have shown up there, so: where is Figure
24878  II?
24879 \layout Paragraph*
24880
24881 ICode Example
24882 \begin_inset LatexCommand \index{iCode}
24883
24884 \end_inset
24885
24886
24887 \layout Standard
24888
24889 This section shows some details of iCode.
24890  The example C code does not do anything useful; it is used as an example
24891  to illustrate the intermediate code generated by the compiler.
24892 \layout Verse
24893
24894
24895 \family typewriter
24896 1.\SpecialChar ~
24897 xdata int * p;
24898 \newline
24899 2.\SpecialChar ~
24900 int gint;
24901 \newline
24902 3.\SpecialChar ~
24903 /* This function does nothing useful.
24904  It is used
24905 \newline
24906 4.\SpecialChar ~
24907 \SpecialChar ~
24908 \SpecialChar ~
24909 \SpecialChar ~
24910 for the purpose of explaining iCode */
24911 \newline
24912 5.\SpecialChar ~
24913 short function (data int *x)
24914 \newline
24915 6.\SpecialChar ~
24916 {
24917 \newline
24918 7.\SpecialChar ~
24919 \SpecialChar ~
24920 \SpecialChar ~
24921 short i=10; \SpecialChar ~
24922 \SpecialChar ~
24923 /* dead initialization eliminated */
24924 \newline
24925 8.\SpecialChar ~
24926 \SpecialChar ~
24927 \SpecialChar ~
24928 short sum=10; /* dead initialization eliminated */
24929 \newline
24930 9.\SpecialChar ~
24931 \SpecialChar ~
24932 \SpecialChar ~
24933 short mul;
24934 \newline
24935 10.\SpecialChar ~
24936 \SpecialChar ~
24937 int j ;
24938 \newline
24939 11.\SpecialChar ~
24940 \SpecialChar ~
24941 while (*x) *x++ = *p++;
24942 \newline
24943 12.\SpecialChar ~
24944 \SpecialChar ~
24945 \SpecialChar ~
24946 \SpecialChar ~
24947 sum = 0 ;
24948 \newline
24949 13.\SpecialChar ~
24950 \SpecialChar ~
24951 mul = 0;
24952 \newline
24953 14.\SpecialChar ~
24954 \SpecialChar ~
24955 /* compiler detects i,j to be induction variables */
24956 \newline
24957 15.\SpecialChar ~
24958 \SpecialChar ~
24959 for (i = 0, j = 10 ; i < 10 ; i++, j
24960 \family default
24961 -
24962 \begin_inset ERT
24963 status Collapsed
24964
24965 \layout Standard
24966
24967 \backslash
24968 /
24969 \end_inset
24970
24971 -
24972 \family typewriter
24973 ) {
24974 \newline
24975 16.\SpecialChar ~
24976 \SpecialChar ~
24977 \SpecialChar ~
24978 \SpecialChar ~
24979 sum += i;
24980 \newline
24981 17.\SpecialChar ~
24982 \SpecialChar ~
24983 \SpecialChar ~
24984 \SpecialChar ~
24985 mul += i * 3; \SpecialChar ~
24986 \SpecialChar ~
24987 /* this multiplication remains */
24988 \newline
24989 18.\SpecialChar ~
24990 \SpecialChar ~
24991 \SpecialChar ~
24992 \SpecialChar ~
24993 gint += j * 3;\SpecialChar ~
24994 \SpecialChar ~
24995 /* this multiplication changed to addition */
24996 \newline
24997 19.\SpecialChar ~
24998 \SpecialChar ~
24999 }
25000 \newline
25001 20.\SpecialChar ~
25002 \SpecialChar ~
25003 return sum+mul;
25004 \newline
25005 21.\SpecialChar ~
25006 }
25007 \layout Standard
25008
25009 In addition to the operands each iCode contains information about the filename
25010  and line it corresponds to in the source file.
25011  The first field in the listing should be interpreted as follows:
25012 \newline
25013
25014 \shape italic
25015 \size footnotesize
25016 Filename(linenumber: iCode Execution sequence number : ICode hash table
25017  key : loop depth of the iCode).
25018 \shape default
25019 \size default
25020
25021 \newline
25022 Then follows the human readable form of the ICode operation.
25023  Each operand of this triplet form can be of three basic types a) compiler
25024  generated temporary b) user defined variable c) a constant value.
25025  Note that local variables and parameters are replaced by compiler generated
25026  temporaries.
25027  Live ranges
25028 \begin_inset LatexCommand \index{Live range analysis}
25029
25030 \end_inset
25031
25032  are computed only for temporaries (i.e.
25033  live ranges are not computed for global variables).
25034  Registers
25035 \begin_inset LatexCommand \index{Register allocation}
25036
25037 \end_inset
25038
25039  are allocated for temporaries only.
25040  Operands are formatted in the following manner:
25041 \newline
25042
25043 \shape italic
25044 \size footnotesize
25045 Operand Name [lr live-from : live-to ] { type information } [ registers
25046  allocated ].
25047 \shape default
25048 \size default
25049
25050 \newline
25051 As mentioned earlier the live ranges are computed in terms of the execution
25052  sequence number of the iCodes, for example
25053 \newline
25054 the iTemp0 is live from (i.e.
25055  first defined in iCode with execution sequence number 3, and is last used
25056  in the iCode with sequence number 5).
25057  For induction variables such as iTemp21 the live range computation extends
25058  the lifetime from the start to the end of the loop.
25059 \newline
25060 The register allocator used the live range information to allocate registers,
25061  the same registers may be used for different temporaries if their live
25062  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
25063  iTemp17 since their live ranges do not overlap.
25064  In addition the allocator also takes into consideration the type and usage
25065  of a temporary, for example itemp6 is a pointer to near space and is used
25066  as to fetch data from (i.e.
25067  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
25068  Some short lived temporaries are allocated to special registers which have
25069  meaning to the code generator e.g.
25070  iTemp13 is allocated to a pseudo register CC which tells the back end that
25071  the temporary is used only for a conditional jump the code generation makes
25072  use of this information to optimize a compare and jump ICode.
25073 \newline
25074 There are several loop optimizations
25075 \begin_inset LatexCommand \index{Loop optimization}
25076
25077 \end_inset
25078
25079  performed by the compiler.
25080  It can detect induction variables iTemp21(i) and iTemp23(j).
25081  Also note the compiler does selective strength reduction
25082 \begin_inset LatexCommand \index{Strength reduction}
25083
25084 \end_inset
25085
25086 , i.e.
25087  the multiplication of an induction variable in line 18 (gint = j * 3) is
25088  changed to addition, a new temporary iTemp17 is allocated and assigned
25089  a initial value, a constant 3 is then added for each iteration of the loop.
25090  The compiler does not change the multiplication
25091 \begin_inset LatexCommand \index{Multiplication}
25092
25093 \end_inset
25094
25095  in line 17 however since the processor does support an 8 * 8 bit multiplication.
25096 \newline
25097 Note the dead code elimination
25098 \begin_inset LatexCommand \index{Dead-code elimination}
25099
25100 \end_inset
25101
25102  optimization eliminated the dead assignments in line 7 & 8 to I and sum
25103  respectively.
25104 \newline
25105
25106 \layout Standard
25107
25108
25109 \size footnotesize
25110 Sample.c (5:1:0:0) _entry($9) :
25111 \layout Standard
25112
25113
25114 \size footnotesize
25115 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
25116 \layout Standard
25117
25118
25119 \size footnotesize
25120 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
25121 \layout Standard
25122
25123
25124 \size footnotesize
25125 Sample.c(11:4:53:0) preHeaderLbl0($11) :
25126 \layout Standard
25127
25128
25129 \size footnotesize
25130 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
25131  * int}[r2]
25132 \layout Standard
25133
25134
25135 \size footnotesize
25136 Sample.c(11:6:5:1) _whilecontinue_0($1) :
25137 \layout Standard
25138
25139
25140 \size footnotesize
25141 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
25142  int}[r0]]
25143 \layout Standard
25144
25145
25146 \size footnotesize
25147 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
25148 \layout Standard
25149
25150
25151 \size footnotesize
25152 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
25153  * int}
25154 \layout Standard
25155
25156
25157 \size footnotesize
25158 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
25159  {short}
25160 \layout Standard
25161
25162
25163 \size footnotesize
25164 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
25165  * int}[DPTR]]
25166 \layout Standard
25167
25168
25169 \size footnotesize
25170 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
25171 }[r2 r3]
25172 \layout Standard
25173
25174
25175 \size footnotesize
25176 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
25177  * int}[r0] + 0x2 {short}
25178 \layout Standard
25179
25180
25181 \size footnotesize
25182 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
25183 \layout Standard
25184
25185
25186 \size footnotesize
25187 Sample.c(11:17:21:0)_whilebreak_0($3) :
25188 \layout Standard
25189
25190
25191 \size footnotesize
25192 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
25193 \layout Standard
25194
25195
25196 \size footnotesize
25197 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
25198 \layout Standard
25199
25200
25201 \size footnotesize
25202 Sample.c(15:20:54:0)preHeaderLbl1($13) :
25203 \layout Standard
25204
25205
25206 \size footnotesize
25207 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
25208 \layout Standard
25209
25210
25211 \size footnotesize
25212 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
25213 \layout Standard
25214
25215
25216 \size footnotesize
25217 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
25218 \layout Standard
25219
25220
25221 \size footnotesize
25222 Sample.c(15:24:26:1)_forcond_0($4) :
25223 \layout Standard
25224
25225
25226 \size footnotesize
25227 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
25228  < 0xa {short}
25229 \layout Standard
25230
25231
25232 \size footnotesize
25233 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
25234 \layout Standard
25235
25236
25237 \size footnotesize
25238 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
25239  + ITemp21 [lr21:38]{short}[r4]
25240 \layout Standard
25241
25242
25243 \size footnotesize
25244 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
25245  * 0x3 {short}
25246 \layout Standard
25247
25248
25249 \size footnotesize
25250 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
25251  + iTemp15 [lr29:30]{short}[r1]
25252 \layout Standard
25253
25254
25255 \size footnotesize
25256 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
25257  r0]- 0x3 {short}
25258 \layout Standard
25259
25260
25261 \size footnotesize
25262 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
25263 int}[r7 r0]
25264 \layout Standard
25265
25266
25267 \size footnotesize
25268 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
25269  + 0x1 {short}
25270 \layout Standard
25271
25272
25273 \size footnotesize
25274 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
25275  r6]- 0x1 {short}
25276 \layout Standard
25277
25278
25279 \size footnotesize
25280 Sample.c(19:38:47:1) goto _forcond_0($4)
25281 \layout Standard
25282
25283
25284 \size footnotesize
25285 Sample.c(19:39:48:0)_forbreak_0($7) :
25286 \layout Standard
25287
25288
25289 \size footnotesize
25290 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
25291  + ITemp11 [lr19:40]{short}[r3]
25292 \layout Standard
25293
25294
25295 \size footnotesize
25296 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
25297 \layout Standard
25298
25299
25300 \size footnotesize
25301 Sample.c(20:42:51:0)_return($8) :
25302 \layout Standard
25303
25304
25305 \size footnotesize
25306 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
25307 \size default
25308
25309 \newline
25310
25311 \newline
25312 Finally the code generated for this function:
25313 \newline
25314
25315 \layout Standard
25316
25317
25318 \size footnotesize
25319 .area DSEG (DATA)
25320 \layout Standard
25321
25322
25323 \size footnotesize
25324 _p::
25325 \layout Standard
25326
25327
25328 \size footnotesize
25329 \SpecialChar ~
25330 \SpecialChar ~
25331 .ds 2
25332 \layout Standard
25333
25334
25335 \size footnotesize
25336 _gint::
25337 \layout Standard
25338
25339
25340 \size footnotesize
25341 \SpecialChar ~
25342 \SpecialChar ~
25343 .ds 2
25344 \layout Standard
25345
25346
25347 \size footnotesize
25348 ; sample.c 5
25349 \layout Standard
25350
25351
25352 \size footnotesize
25353 ; ----------------------------------------------
25354 \layout Standard
25355
25356
25357 \size footnotesize
25358 ; function function
25359 \layout Standard
25360
25361
25362 \size footnotesize
25363 ; ----------------------------------------------
25364 \layout Standard
25365
25366
25367 \size footnotesize
25368 _function:
25369 \layout Standard
25370
25371
25372 \size footnotesize
25373 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
25374 \layout Standard
25375
25376
25377 \size footnotesize
25378 \SpecialChar ~
25379 \SpecialChar ~
25380 mov r2,dpl
25381 \layout Standard
25382
25383
25384 \size footnotesize
25385 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
25386 \layout Standard
25387
25388
25389 \size footnotesize
25390 \SpecialChar ~
25391 \SpecialChar ~
25392 mov ar0,r2
25393 \layout Standard
25394
25395
25396 \size footnotesize
25397 ;_whilecontinue_0($1) :
25398 \layout Standard
25399
25400
25401 \size footnotesize
25402 00101$:
25403 \layout Standard
25404
25405
25406 \size footnotesize
25407 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
25408 \layout Standard
25409
25410
25411 \size footnotesize
25412 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
25413 \layout Standard
25414
25415
25416 \size footnotesize
25417 \SpecialChar ~
25418 \SpecialChar ~
25419 mov ar2,@r0
25420 \layout Standard
25421
25422
25423 \size footnotesize
25424 \SpecialChar ~
25425 \SpecialChar ~
25426 inc r0
25427 \layout Standard
25428
25429
25430 \size footnotesize
25431 \SpecialChar ~
25432 \SpecialChar ~
25433 mov ar3,@r0
25434 \layout Standard
25435
25436
25437 \size footnotesize
25438 \SpecialChar ~
25439 \SpecialChar ~
25440 dec r0
25441 \layout Standard
25442
25443
25444 \size footnotesize
25445 \SpecialChar ~
25446 \SpecialChar ~
25447 mov a,r2
25448 \layout Standard
25449
25450
25451 \size footnotesize
25452 \SpecialChar ~
25453 \SpecialChar ~
25454 orl a,r3
25455 \layout Standard
25456
25457
25458 \size footnotesize
25459 \SpecialChar ~
25460 \SpecialChar ~
25461 jz 00103$
25462 \layout Standard
25463
25464
25465 \size footnotesize
25466 00114$:
25467 \layout Standard
25468
25469
25470 \size footnotesize
25471 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
25472 \layout Standard
25473
25474
25475 \size footnotesize
25476 \SpecialChar ~
25477 \SpecialChar ~
25478 mov dpl,_p
25479 \layout Standard
25480
25481
25482 \size footnotesize
25483 \SpecialChar ~
25484 \SpecialChar ~
25485 mov dph,(_p + 1)
25486 \layout Standard
25487
25488
25489 \size footnotesize
25490 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
25491 \layout Standard
25492
25493
25494 \size footnotesize
25495 \SpecialChar ~
25496 \SpecialChar ~
25497 mov a,#0x02
25498 \layout Standard
25499
25500
25501 \size footnotesize
25502 \SpecialChar ~
25503 \SpecialChar ~
25504 add a,_p
25505 \layout Standard
25506
25507
25508 \size footnotesize
25509 \SpecialChar ~
25510 \SpecialChar ~
25511 mov _p,a
25512 \layout Standard
25513
25514
25515 \size footnotesize
25516 \SpecialChar ~
25517 \SpecialChar ~
25518 clr a
25519 \layout Standard
25520
25521
25522 \size footnotesize
25523 \SpecialChar ~
25524 \SpecialChar ~
25525 addc a,(_p + 1)
25526 \layout Standard
25527
25528
25529 \size footnotesize
25530 \SpecialChar ~
25531 \SpecialChar ~
25532 mov (_p + 1),a
25533 \layout Standard
25534
25535
25536 \size footnotesize
25537 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
25538 \layout Standard
25539
25540
25541 \size footnotesize
25542 \SpecialChar ~
25543 \SpecialChar ~
25544 movx a,@dptr
25545 \layout Standard
25546
25547
25548 \size footnotesize
25549 \SpecialChar ~
25550 \SpecialChar ~
25551 mov r2,a
25552 \layout Standard
25553
25554
25555 \size footnotesize
25556 \SpecialChar ~
25557 \SpecialChar ~
25558 inc dptr
25559 \layout Standard
25560
25561
25562 \size footnotesize
25563 \SpecialChar ~
25564 \SpecialChar ~
25565 movx a,@dptr
25566 \layout Standard
25567
25568
25569 \size footnotesize
25570 \SpecialChar ~
25571 \SpecialChar ~
25572 mov r3,a
25573 \layout Standard
25574
25575
25576 \size footnotesize
25577 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
25578 \layout Standard
25579
25580
25581 \size footnotesize
25582 \SpecialChar ~
25583 \SpecialChar ~
25584 mov @r0,ar2
25585 \layout Standard
25586
25587
25588 \size footnotesize
25589 \SpecialChar ~
25590 \SpecialChar ~
25591 inc r0
25592 \layout Standard
25593
25594
25595 \size footnotesize
25596 \SpecialChar ~
25597 \SpecialChar ~
25598 mov @r0,ar3
25599 \layout Standard
25600
25601
25602 \size footnotesize
25603 ; iTemp6 [lr5:16]{_near * int}[r0] =
25604 \layout Standard
25605
25606
25607 \size footnotesize
25608 ; iTemp6 [lr5:16]{_near * int}[r0] +
25609 \layout Standard
25610
25611
25612 \size footnotesize
25613 ; 0x2 {short}
25614 \layout Standard
25615
25616
25617 \size footnotesize
25618 \SpecialChar ~
25619 \SpecialChar ~
25620 inc r0
25621 \layout Standard
25622
25623
25624 \size footnotesize
25625 ; goto _whilecontinue_0($1)
25626 \layout Standard
25627
25628
25629 \size footnotesize
25630 \SpecialChar ~
25631 \SpecialChar ~
25632 sjmp 00101$
25633 \layout Standard
25634
25635
25636 \size footnotesize
25637 ; _whilebreak_0($3) :
25638 \layout Standard
25639
25640
25641 \size footnotesize
25642 00103$:
25643 \layout Standard
25644
25645
25646 \size footnotesize
25647 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
25648 \layout Standard
25649
25650
25651 \size footnotesize
25652 \SpecialChar ~
25653 \SpecialChar ~
25654 mov r2,#0x00
25655 \layout Standard
25656
25657
25658 \size footnotesize
25659 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
25660 \layout Standard
25661
25662
25663 \size footnotesize
25664 \SpecialChar ~
25665 \SpecialChar ~
25666 mov r3,#0x00
25667 \layout Standard
25668
25669
25670 \size footnotesize
25671 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
25672 \layout Standard
25673
25674
25675 \size footnotesize
25676 \SpecialChar ~
25677 \SpecialChar ~
25678 mov r4,#0x00
25679 \layout Standard
25680
25681
25682 \size footnotesize
25683 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
25684 \layout Standard
25685
25686
25687 \size footnotesize
25688 \SpecialChar ~
25689 \SpecialChar ~
25690 mov r5,#0x0A
25691 \layout Standard
25692
25693
25694 \size footnotesize
25695 \SpecialChar ~
25696 \SpecialChar ~
25697 mov r6,#0x00
25698 \layout Standard
25699
25700
25701 \size footnotesize
25702 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
25703 \layout Standard
25704
25705
25706 \size footnotesize
25707 \SpecialChar ~
25708 \SpecialChar ~
25709 mov r7,#0x1E
25710 \layout Standard
25711
25712
25713 \size footnotesize
25714 \SpecialChar ~
25715 \SpecialChar ~
25716 mov r0,#0x00
25717 \layout Standard
25718
25719
25720 \size footnotesize
25721 ; _forcond_0($4) :
25722 \layout Standard
25723
25724
25725 \size footnotesize
25726 00104$:
25727 \layout Standard
25728
25729
25730 \size footnotesize
25731 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
25732 \layout Standard
25733
25734
25735 \size footnotesize
25736 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
25737 \layout Standard
25738
25739
25740 \size footnotesize
25741 \SpecialChar ~
25742 \SpecialChar ~
25743 clr c
25744 \layout Standard
25745
25746
25747 \size footnotesize
25748 \SpecialChar ~
25749 \SpecialChar ~
25750 mov a,r4
25751 \layout Standard
25752
25753
25754 \size footnotesize
25755 \SpecialChar ~
25756 \SpecialChar ~
25757 xrl a,#0x80
25758 \layout Standard
25759
25760
25761 \size footnotesize
25762 \SpecialChar ~
25763 \SpecialChar ~
25764 subb a,#0x8a
25765 \layout Standard
25766
25767
25768 \size footnotesize
25769 \SpecialChar ~
25770 \SpecialChar ~
25771 jnc 00107$
25772 \layout Standard
25773
25774
25775 \size footnotesize
25776 00115$:
25777 \layout Standard
25778
25779
25780 \size footnotesize
25781 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
25782 \layout Standard
25783
25784
25785 \size footnotesize
25786 ; iTemp21 [lr21:38]{short}[r4]
25787 \layout Standard
25788
25789
25790 \size footnotesize
25791 \SpecialChar ~
25792 \SpecialChar ~
25793 mov a,r4
25794 \layout Standard
25795
25796
25797 \size footnotesize
25798 \SpecialChar ~
25799 \SpecialChar ~
25800 add a,r2
25801 \layout Standard
25802
25803
25804 \size footnotesize
25805 \SpecialChar ~
25806 \SpecialChar ~
25807 mov r2,a
25808 \layout Standard
25809
25810
25811 \size footnotesize
25812 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
25813 \layout Standard
25814
25815
25816 \size footnotesize
25817 \SpecialChar ~
25818 \SpecialChar ~
25819 mov b,#0x03
25820 \layout Standard
25821
25822
25823 \size footnotesize
25824 \SpecialChar ~
25825 \SpecialChar ~
25826 mov a,r4
25827 \layout Standard
25828
25829
25830 \size footnotesize
25831 \SpecialChar ~
25832 \SpecialChar ~
25833 mul ab
25834 \layout Standard
25835
25836
25837 \size footnotesize
25838 \SpecialChar ~
25839 \SpecialChar ~
25840 mov r1,a
25841 \layout Standard
25842
25843
25844 \size footnotesize
25845 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
25846 \layout Standard
25847
25848
25849 \size footnotesize
25850 ; iTemp15 [lr29:30]{short}[r1]
25851 \layout Standard
25852
25853
25854 \size footnotesize
25855 \SpecialChar ~
25856 \SpecialChar ~
25857 add a,r3
25858 \layout Standard
25859
25860
25861 \size footnotesize
25862 \SpecialChar ~
25863 \SpecialChar ~
25864 mov r3,a
25865 \layout Standard
25866
25867
25868 \size footnotesize
25869 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
25870 \layout Standard
25871
25872
25873 \size footnotesize
25874 \SpecialChar ~
25875 \SpecialChar ~
25876 mov a,r7
25877 \layout Standard
25878
25879
25880 \size footnotesize
25881 \SpecialChar ~
25882 \SpecialChar ~
25883 add a,#0xfd
25884 \layout Standard
25885
25886
25887 \size footnotesize
25888 \SpecialChar ~
25889 \SpecialChar ~
25890 mov r7,a
25891 \layout Standard
25892
25893
25894 \size footnotesize
25895 \SpecialChar ~
25896 \SpecialChar ~
25897 mov a,r0
25898 \layout Standard
25899
25900
25901 \size footnotesize
25902 \SpecialChar ~
25903 \SpecialChar ~
25904 addc a,#0xff
25905 \layout Standard
25906
25907
25908 \size footnotesize
25909 \SpecialChar ~
25910 \SpecialChar ~
25911 mov r0,a
25912 \layout Standard
25913
25914
25915 \size footnotesize
25916 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
25917 \layout Standard
25918
25919
25920 \size footnotesize
25921 \SpecialChar ~
25922 \SpecialChar ~
25923 mov a,r7
25924 \layout Standard
25925
25926
25927 \size footnotesize
25928 \SpecialChar ~
25929 \SpecialChar ~
25930 add a,_gint
25931 \layout Standard
25932
25933
25934 \size footnotesize
25935 \SpecialChar ~
25936 \SpecialChar ~
25937 mov _gint,a
25938 \layout Standard
25939
25940
25941 \size footnotesize
25942 \SpecialChar ~
25943 \SpecialChar ~
25944 mov a,r0
25945 \layout Standard
25946
25947
25948 \size footnotesize
25949 \SpecialChar ~
25950 \SpecialChar ~
25951 addc a,(_gint + 1)
25952 \layout Standard
25953
25954
25955 \size footnotesize
25956 \SpecialChar ~
25957 \SpecialChar ~
25958 mov (_gint + 1),a
25959 \layout Standard
25960
25961
25962 \size footnotesize
25963 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
25964 \layout Standard
25965
25966
25967 \size footnotesize
25968 \SpecialChar ~
25969 \SpecialChar ~
25970 inc r4
25971 \layout Standard
25972
25973
25974 \size footnotesize
25975 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
25976 \layout Standard
25977
25978
25979 \size footnotesize
25980 \SpecialChar ~
25981 \SpecialChar ~
25982 dec r5
25983 \layout Standard
25984
25985
25986 \size footnotesize
25987 \SpecialChar ~
25988 \SpecialChar ~
25989 cjne r5,#0xff,00104$
25990 \layout Standard
25991
25992
25993 \size footnotesize
25994 \SpecialChar ~
25995 \SpecialChar ~
25996 dec r6
25997 \layout Standard
25998
25999
26000 \size footnotesize
26001 ; goto _forcond_0($4)
26002 \layout Standard
26003
26004
26005 \size footnotesize
26006 \SpecialChar ~
26007 \SpecialChar ~
26008 sjmp 00104$
26009 \layout Standard
26010
26011
26012 \size footnotesize
26013 ; _forbreak_0($7) :
26014 \layout Standard
26015
26016
26017 \size footnotesize
26018 00107$:
26019 \layout Standard
26020
26021
26022 \size footnotesize
26023 ; ret iTemp24 [lr40:41]{short}
26024 \layout Standard
26025
26026
26027 \size footnotesize
26028 \SpecialChar ~
26029 \SpecialChar ~
26030 mov a,r3
26031 \layout Standard
26032
26033
26034 \size footnotesize
26035 \SpecialChar ~
26036 \SpecialChar ~
26037 add a,r2
26038 \layout Standard
26039
26040
26041 \size footnotesize
26042 \SpecialChar ~
26043 \SpecialChar ~
26044 mov dpl,a
26045 \layout Standard
26046
26047
26048 \size footnotesize
26049 ; _return($8) :
26050 \layout Standard
26051
26052
26053 \size footnotesize
26054 00108$:
26055 \layout Standard
26056
26057
26058 \size footnotesize
26059 \SpecialChar ~
26060 \SpecialChar ~
26061 ret
26062 \newline
26063
26064 \layout Section
26065
26066 A few words about basic block successors, predecessors and dominators
26067 \layout Standard
26068
26069 Successors are basic blocks
26070 \begin_inset LatexCommand \index{Basic blocks}
26071
26072 \end_inset
26073
26074  that might execute after this basic block.
26075 \newline
26076 Predecessors are basic blocks that might execute before reaching this basic
26077  block.
26078 \newline
26079 Dominators are basic blocks that WILL execute before reaching this basic
26080  block.
26081 \newline
26082
26083 \layout Standard
26084
26085 [basic block 1]
26086 \layout Standard
26087
26088 if (something)
26089 \layout Standard
26090
26091 \SpecialChar ~
26092 \SpecialChar ~
26093 \SpecialChar ~
26094 \SpecialChar ~
26095 [basic block 2]
26096 \layout Standard
26097
26098 else
26099 \layout Standard
26100
26101 \SpecialChar ~
26102 \SpecialChar ~
26103 \SpecialChar ~
26104 \SpecialChar ~
26105 [basic block 3]
26106 \layout Standard
26107
26108 [basic block 4]
26109 \newline
26110
26111 \layout Standard
26112
26113 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
26114 \layout Standard
26115
26116 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
26117 \layout Standard
26118
26119 c) domVect of [BB4] = BB1 ...
26120  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
26121  was executed.
26122 \layout Chapter
26123
26124 Acknowledgments
26125 \layout Standard
26126
26127
26128 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
26129
26130 \end_inset
26131
26132
26133 \newline
26134
26135 \newline
26136
26137 \emph on
26138 Thanks to all the other volunteer developers who have helped with coding,
26139  testing, web-page creation, distribution sets, etc.
26140  You know who you are :-)
26141 \emph default
26142
26143 \newline
26144
26145 \layout Standard
26146
26147 This document was initially written by Sandeep Dutta
26148 \layout Standard
26149
26150 All product names mentioned herein may be trademarks
26151 \begin_inset LatexCommand \index{Trademarks}
26152
26153 \end_inset
26154
26155  of their respective companies.
26156
26157 \layout Section*
26158
26159 Alphabetical index
26160 \layout Standard
26161
26162 To avoid confusion, the installation and building options for SDCC itself
26163  (chapter 2) are not part of the index.
26164 \layout Standard
26165
26166
26167 \begin_inset LatexCommand \printindex{}
26168
26169 \end_inset
26170
26171
26172 \the_end