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.4.8
  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, Motorola HC08 and Zilog Z80 based MCUs.
 145  It can be retargetted for other microprocessors, support for Microchip
 146  PIC, Atmel AVR is under development.
 147  The entire source code for the compiler is distributed under GPL.
 148  SDCC uses ASXXXX
 149 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
 150
 151 \end_inset
 152
 153  & ASLINK
 154 \begin_inset LatexCommand \index{aslink}
 155
 156 \end_inset
 157
 158 , an open source retargettable assembler & linker.
 159  SDCC has extensive language extensions suitable for utilizing various microcont
 160 rollers and underlying hardware effectively.
 161
 162 \newline
 163
 164 \newline
 165 In addition to the MCU specific optimizations SDCC also does a host of standard
 166  optimizations like:
 167 \layout Itemize
 168
 169 global sub expression elimination,
 170 \layout Itemize
 171
 172 loop optimizations (loop invariant, strength reduction of induction variables
 173  and loop reversing),
 174 \layout Itemize
 175
 176 constant folding & propagation,
 177 \layout Itemize
 178
 179 copy propagation,
 180 \layout Itemize
 181
 182 dead code elimination
 183 \layout Itemize
 184
 185 jump tables for
 186 \emph on
 187 switch
 188 \emph default
 189  statements.
 190 \layout Standard
 191
 192 For the back-end SDCC uses a global register allocation scheme which should
 193  be well suited for other 8 bit MCUs.
 194
 195 \newline
 196
 197 \newline
 198 The peep hole optimizer uses a rule based substitution mechanism which is
 199  MCU independent.
 200
 201 \newline
 202
 203 \newline
 204 Supported data-types are:
 205 \layout Itemize
 206
 207 char (8 bits, 1 byte),
 208 \layout Itemize
 209
 210 short and int (16 bits, 2 bytes),
 211 \layout Itemize
 212
 213 long (32 bit, 4 bytes)
 214 \layout Itemize
 215
 216 float (4 byte IEEE).
 217
 218 \layout Standard
 219
 220 The compiler also allows
 221 \emph on
 222 inline assembler code
 223 \emph default
 224  to be embedded anywhere in a function.
 225  In addition, routines developed in assembly can also be called.
 226 \newline
 227
 228 \newline
 229 SDCC also provides an option (-
 230 \begin_inset ERT
 231 status Collapsed
 232
 233 \layout Standard
 234
 235 \backslash
 236 /
 237 \end_inset
 238
 239 -cyclomatic) to report the relative complexity of a function.
 240  These functions can then be further optimized, or hand coded in assembly
 241  if needed.
 242
 243 \newline
 244
 245 \newline
 246 SDCC also comes with a companion source level debugger SDCDB, the debugger
 247  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 248
 249 \newline
 250
 251 \newline
 252 The latest version can be downloaded from
 253 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 254
 255 \end_inset
 256
 257 .
 258
 259 \series bold
 260
 261 \series default
 262 \emph on
 263 Please note: the compiler will probably always be some steps ahead of this
 264  documentation
 265 \series bold
 266 \emph default
 267
 268 \begin_inset LatexCommand \index{Status of documentation}
 269
 270 \end_inset
 271
 272
 273 \begin_inset Foot
 274 collapsed false
 275
 276 \layout Standard
 277
 278 Obviously this has pros and cons
 279 \end_inset
 280
 281 .
 282 \layout Section
 283
 284 Open Source
 285 \layout Standard
 286
 287 All packages used in this compiler system are
 288 \emph on
 289 open source
 290 \emph default
 291  and
 292 \emph on
 293 freeware
 294 \emph default
 295 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 296  etc) is distributed with the package.
 297  This documentation is maintained using a freeware word processor (LyX).
 298 \newline
 299 This program is free software; you can redistribute it and/or modify it
 300  under the terms of the GNU General Public License
 301 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 302
 303 \end_inset
 304
 305  as published by the Free Software Foundation; either version 2, or (at
 306  your option) any later version.
 307  This program is distributed in the hope that it will be useful, but WITHOUT
 308  ANY WARRANTY; without even the implied warranty
 309 \begin_inset LatexCommand \index{warranty}
 310
 311 \end_inset
 312
 313  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 314  See the GNU General Public License for more details.
 315  You should have received a copy of the GNU General Public License along
 316  with this program; if not, write to the Free Software Foundation, 59 Temple
 317  Place - Suite 330, Boston, MA 02111-1307, USA.
 318  In other words, you are welcome to use, share and improve this program.
 319  You are forbidden to forbid anyone else to use, share and improve what
 320  you give them.
 321  Help stamp out software-hoarding!
 322 \layout Section
 323
 324 Typographic conventions
 325 \begin_inset LatexCommand \index{Typographic conventions}
 326
 327 \end_inset
 328
 329
 330 \layout Standard
 331
 332 Throughout this manual, we will use the following convention.
 333  Commands you have to type in are printed in
 334 \family sans
 335 \series bold
 336 "sans serif"
 337 \series default
 338 .
 339
 340 \family default
 341  Code samples are printed in
 342 \family typewriter
 343 typewriter font.
 344
 345 \family default
 346  Interesting items and new terms are printed in
 347 \emph on
 348 italic.
 349 \layout Section
 350
 351 Compatibility with previous versions
 352 \layout Standard
 353
 354 This version has numerous bug fixes compared with the previous version.
 355  But we also introduced some incompatibilities with older versions.
 356  Not just for the fun of it, but to make the compiler more stable, efficient
 357  and ANSI compliant
 358 \begin_inset LatexCommand \index{ANSI-compliance}
 359
 360 \end_inset
 361
 362  (see section
 363 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 364
 365 \end_inset
 366
 367  for ANSI-Compliance).
 368
 369 \newline
 370
 371 \layout Itemize
 372
 373 short is now equivalent to int (16 bits), it used to be equivalent to char
 374  (8 bits) which is not ANSI compliant
 375 \layout Itemize
 376
 377 the default directory for gcc-builds where include, library and documentation
 378  files are stored is now in /usr/local/share
 379 \layout Itemize
 380
 381 char type parameters to vararg functions are casted to int unless explicitly
 382  casted, e.g.:
 383 \newline
 384
 385 \family typewriter
 386 \SpecialChar ~
 387 \SpecialChar ~
 388 char a=3;
 389 \newline
 390 \SpecialChar ~
 391 \SpecialChar ~
 392 printf ("%d %c
 393 \backslash
 394 n", a, (char)a);
 395 \family default
 396
 397 \newline
 398  will push a as an int and as a char resp.
 399 \layout Itemize
 400
 401 option -
 402 \begin_inset ERT
 403 status Collapsed
 404
 405 \layout Standard
 406
 407 \backslash
 408 /
 409 \end_inset
 410
 411 -regextend has been removed
 412 \layout Itemize
 413
 414 option -
 415 \begin_inset ERT
 416 status Collapsed
 417
 418 \layout Standard
 419
 420 \backslash
 421 /
 422 \end_inset
 423
 424 -noregparms has been removed
 425 \layout Itemize
 426
 427 option -
 428 \begin_inset ERT
 429 status Collapsed
 430
 431 \layout Standard
 432
 433 \backslash
 434 /
 435 \end_inset
 436
 437 -stack-after-data has been removed
 438 \layout Standard
 439
 440
 441 \emph on
 442 <pending: more incompatibilities?>
 443 \layout Section
 444
 445 System Requirements
 446 \layout Standard
 447
 448 What do you need before you start installation of SDCC? A computer, and
 449  a desire to compute.
 450  The preferred method of installation is to compile SDCC from source using
 451  GNU gcc and make.
 452  For Windows some pre-compiled binary distributions are available for your
 453  convenience.
 454  You should have some experience with command line tools and compiler use.
 455 \layout Section
 456
 457 Other Resources
 458 \layout Standard
 459
 460 The SDCC home page at
 461 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 462
 463 \end_inset
 464
 465  is a great place to find distribution sets.
 466  You can also find links to the user mailing lists that offer help or discuss
 467  SDCC with other SDCC users.
 468  Web links to other SDCC related sites can also be found here.
 469  This document can be found in the DOC directory of the source package as
 470  a text or HTML file.
 471  A pdf version of this document is available at
 472 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 473
 474 \end_inset
 475
 476 .
 477  Some of the other tools (simulator and assembler) included with SDCC contain
 478  their own documentation and can be found in the source distribution.
 479  If you want the latest unreleased software, the complete source package
 480  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 481 \layout Section
 482
 483 Wishes for the future
 484 \layout Standard
 485
 486 There are (and always will be) some things that could be done.
 487  Here are some I can think of:
 488 \newline
 489
 490 \layout Standard
 491
 492
 493 \family typewriter
 494 char KernelFunction3(char p) at 0x340;
 495 \newline
 496
 497 \layout Standard
 498
 499
 500 \family typewriter
 501 code banking
 502 \begin_inset LatexCommand \index{code banking (not supported)}
 503
 504 \end_inset
 505
 506  support for mcs51
 507 \newline
 508
 509 \newline
 510
 511 \family default
 512 If you can think of some more, please see the section
 513 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 514
 515 \end_inset
 516
 517  about filing feature requests
 518 \begin_inset LatexCommand \index{Requesting features}
 519
 520 \end_inset
 521
 522
 523 \begin_inset LatexCommand \index{Feature request}
 524
 525 \end_inset
 526
 527 .
 528 \newline
 529
 530 \layout Chapter
 531
 532 Installing SDCC
 533 \begin_inset LatexCommand \index{Installation}
 534
 535 \end_inset
 536
 537
 538 \layout Standard
 539
 540 For most users it is sufficient to skip to either section
 541 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 542
 543 \end_inset
 544
 545  or section
 546 \begin_inset LatexCommand \ref{sub:Windows-Install}
 547
 548 \end_inset
 549
 550 .
 551  More detailled instructions follow below.
 552 \layout Section
 553
 554 Configure Options
 555 \begin_inset LatexCommand \index{Options SDCC configuration}
 556
 557 \end_inset
 558
 559
 560 \layout Standard
 561
 562 The install paths, search paths and other options are defined when running
 563  'configure'.
 564  The defaults can be overridden by:
 565 \layout List
 566 \labelwidthstring 00.00.0000
 567
 568 -
 569 \begin_inset ERT
 570 status Collapsed
 571
 572 \layout Standard
 573
 574 \backslash
 575 /
 576 \end_inset
 577
 578 -prefix see table below
 579 \layout List
 580 \labelwidthstring 00.00.0000
 581
 582 -
 583 \begin_inset ERT
 584 status Collapsed
 585
 586 \layout Standard
 587
 588 \backslash
 589 /
 590 \end_inset
 591
 592 -exec_prefix see table below
 593 \layout List
 594 \labelwidthstring 00.00.0000
 595
 596 -
 597 \begin_inset ERT
 598 status Collapsed
 599
 600 \layout Standard
 601
 602 \backslash
 603 /
 604 \end_inset
 605
 606 -bindir see table below
 607 \layout List
 608 \labelwidthstring 00.00.0000
 609
 610 -
 611 \begin_inset ERT
 612 status Collapsed
 613
 614 \layout Standard
 615
 616 \backslash
 617 /
 618 \end_inset
 619
 620 -datadir see table below
 621 \layout List
 622 \labelwidthstring 00.00.0000
 623
 624 docdir environment variable, see table below
 625 \layout List
 626 \labelwidthstring 00.00.0000
 627
 628 include_dir_suffix environment variable, see table below
 629 \layout List
 630 \labelwidthstring 00.00.0000
 631
 632 lib_dir_suffix environment variable, see table below
 633 \layout List
 634 \labelwidthstring 00.00.0000
 635
 636 sdccconf_h_dir_separator environment variable, either / or
 637 \backslash
 638
 639 \backslash
 640  makes sense here.
 641  This character will only be used in sdccconf.h; don't forget it's a C-header,
 642  therefore a double-backslash is needed there.
 643 \layout List
 644 \labelwidthstring 00.00.0000
 645
 646 -
 647 \begin_inset ERT
 648 status Collapsed
 649
 650 \layout Standard
 651
 652 \backslash
 653 /
 654 \end_inset
 655
 656 -disable-mcs51-port Excludes the Intel mcs51 port
 657 \layout List
 658 \labelwidthstring 00.00.0000
 659
 660 -
 661 \begin_inset ERT
 662 status Collapsed
 663
 664 \layout Standard
 665
 666 \backslash
 667 /
 668 \end_inset
 669
 670 -disable-gbz80-port Excludes the Gameboy gbz80 port
 671 \layout List
 672 \labelwidthstring 00.00.0000
 673
 674 -
 675 \begin_inset ERT
 676 status Collapsed
 677
 678 \layout Standard
 679
 680 \backslash
 681 /
 682 \end_inset
 683
 684 -disable-z80-port Excludes the z80 port
 685 \layout List
 686 \labelwidthstring 00.00.0000
 687
 688 -
 689 \begin_inset ERT
 690 status Collapsed
 691
 692 \layout Standard
 693
 694 \backslash
 695 /
 696 \end_inset
 697
 698 -disable-avr-port Excludes the AVR port
 699 \layout List
 700 \labelwidthstring 00.00.0000
 701
 702 -
 703 \begin_inset ERT
 704 status Collapsed
 705
 706 \layout Standard
 707
 708 \backslash
 709 /
 710 \end_inset
 711
 712 -disable-ds390-port Excludes the DS390 port
 713 \layout List
 714 \labelwidthstring 00.00.0000
 715
 716 -
 717 \begin_inset ERT
 718 status Collapsed
 719
 720 \layout Standard
 721
 722 \backslash
 723 /
 724 \end_inset
 725
 726 -disable-hc08-port Excludes the HC08 port
 727 \layout List
 728 \labelwidthstring 00.00.0000
 729
 730 -
 731 \begin_inset ERT
 732 status Collapsed
 733
 734 \layout Standard
 735
 736 \backslash
 737 /
 738 \end_inset
 739
 740 -disable-pic-port Excludes the PIC port
 741 \layout List
 742 \labelwidthstring 00.00.0000
 743
 744 -
 745 \begin_inset ERT
 746 status Collapsed
 747
 748 \layout Standard
 749
 750 \backslash
 751 /
 752 \end_inset
 753
 754 -disable-xa51-port Excludes the XA51 port
 755 \layout List
 756 \labelwidthstring 00.00.0000
 757
 758 -
 759 \begin_inset ERT
 760 status Collapsed
 761
 762 \layout Standard
 763
 764 \backslash
 765 /
 766 \end_inset
 767
 768 -disable-ucsim Disables configuring and building of ucsim
 769 \layout List
 770 \labelwidthstring 00.00.0000
 771
 772 -
 773 \begin_inset ERT
 774 status Collapsed
 775
 776 \layout Standard
 777
 778 \backslash
 779 /
 780 \end_inset
 781
 782 -disable-device-lib-build Disables automatically building device libraries
 783 \layout List
 784 \labelwidthstring 00.00.0000
 785
 786 -
 787 \begin_inset ERT
 788 status Collapsed
 789
 790 \layout Standard
 791
 792 \backslash
 793 /
 794 \end_inset
 795
 796 -disable-packihx Disables building packihx
 797 \layout List
 798 \labelwidthstring 00.00.0000
 799
 800 -
 801 \begin_inset ERT
 802 status Collapsed
 803
 804 \layout Standard
 805
 806 \backslash
 807 /
 808 \end_inset
 809
 810 -enable-libgc Use the Bohem memory allocator.
 811  Lower runtime footprint.
 812 \layout Standard
 813
 814 Furthermore the environment variables CC, CFLAGS, ...
 815  the tools and their arguments can be influenced.
 816  Please see `configure -
 817 \begin_inset ERT
 818 status Collapsed
 819
 820 \layout Standard
 821
 822 \backslash
 823 /
 824 \end_inset
 825
 826 -help` and the man/info pages of `configure` for details.
 827 \newline
 828
 829 \newline
 830 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 831  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 832 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 833  At the moment it's not possible to change the default settings (it was
 834  simply never required).
 835 \newline
 836
 837 \newline
 838 These configure options are compiled into the binaries, and can only be
 839  changed by rerunning 'configure' and recompiling SDCC.
 840  The configure options are written in
 841 \emph on
 842 italics
 843 \emph default
 844  to distinguish them from run time environment variables (see section search
 845  paths).
 846 \newline
 847
 848 \newline
 849 The settings for
 850 \begin_inset Quotes sld
 851 \end_inset
 852
 853 Win32 builds
 854 \begin_inset Quotes srd
 855 \end_inset
 856
 857  are used by the SDCC team to build the official Win32 binaries.
 858  The SDCC team uses Mingw32 to build the official Windows binaries, because
 859  it's
 860 \layout Enumerate
 861
 862 open source,
 863 \layout Enumerate
 864
 865 a gcc compiler and last but not least
 866 \layout Enumerate
 867
 868 the binaries can be built by cross compiling on Sourceforge's compile farm.
 869 \layout Standard
 870
 871 See the examples, how to pass the Win32 settings to 'configure'.
 872  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 873  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 874  for Win32.
 875 \newline
 876
 877 \newline
 878 These defaults are:
 879 \newline
 880
 881 \layout Standard
 882 \align center
 883
 884 \begin_inset  Tabular
 885 <lyxtabular version="3" rows="8" columns="3">
 886 <features>
 887 <column alignment="block" valignment="top" leftline="true" width="0in">
 888 <column alignment="block" valignment="top" leftline="true" width="0in">
 889 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 890 <row topline="true" bottomline="true">
 891 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 892 \begin_inset Text
 893
 894 \layout Standard
 895
 896 Variable
 897 \end_inset
 898 </cell>
 899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 900 \begin_inset Text
 901
 902 \layout Standard
 903
 904 default
 905 \end_inset
 906 </cell>
 907 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 908 \begin_inset Text
 909
 910 \layout Standard
 911
 912 Win32 builds
 913 \end_inset
 914 </cell>
 915 </row>
 916 <row topline="true">
 917 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 918 \begin_inset Text
 919
 920 \layout Standard
 921
 922
 923 \emph on
 924 PREFIX
 925 \end_inset
 926 </cell>
 927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 928 \begin_inset Text
 929
 930 \layout Standard
 931
 932 /usr/local
 933 \end_inset
 934 </cell>
 935 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 936 \begin_inset Text
 937
 938 \layout Standard
 939
 940
 941 \backslash
 942 sdcc
 943 \end_inset
 944 </cell>
 945 </row>
 946 <row topline="true">
 947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 948 \begin_inset Text
 949
 950 \layout Standard
 951
 952
 953 \emph on
 954 EXEC_PREFIX
 955 \end_inset
 956 </cell>
 957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 958 \begin_inset Text
 959
 960 \layout Standard
 961
 962
 963 \emph on
 964 $PREFIX
 965 \end_inset
 966 </cell>
 967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 968 \begin_inset Text
 969
 970 \layout Standard
 971
 972
 973 \emph on
 974 $PREFIX
 975 \end_inset
 976 </cell>
 977 </row>
 978 <row topline="true">
 979 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 980 \begin_inset Text
 981
 982 \layout Standard
 983
 984
 985 \emph on
 986 BINDIR
 987 \end_inset
 988 </cell>
 989 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 990 \begin_inset Text
 991
 992 \layout Standard
 993
 994
 995 \emph on
 996 $EXECPREFIX
 997 \emph default
 998 /bin
 999 \end_inset
1000 </cell>
1001 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1002 \begin_inset Text
1003
1004 \layout Standard
1005
1006
1007 \emph on
1008 $EXECPREFIX
1009 \emph default
1010
1011 \backslash
1012 bin
1013 \end_inset
1014 </cell>
1015 </row>
1016 <row topline="true">
1017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1018 \begin_inset Text
1019
1020 \layout Standard
1021
1022
1023 \emph on
1024 DATADIR
1025 \end_inset
1026 </cell>
1027 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1028 \begin_inset Text
1029
1030 \layout Standard
1031
1032
1033 \emph on
1034 $PREFIX
1035 \emph default
1036 /share
1037 \end_inset
1038 </cell>
1039 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1040 \begin_inset Text
1041
1042 \layout Standard
1043
1044
1045 \emph on
1046 $PREFIX
1047 \end_inset
1048 </cell>
1049 </row>
1050 <row topline="true">
1051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1052 \begin_inset Text
1053
1054 \layout Standard
1055
1056
1057 \emph on
1058 DOCDIR
1059 \end_inset
1060 </cell>
1061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1062 \begin_inset Text
1063
1064 \layout Standard
1065
1066
1067 \emph on
1068 $DATADIR
1069 \emph default
1070 /sdcc/doc
1071 \end_inset
1072 </cell>
1073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1074 \begin_inset Text
1075
1076 \layout Standard
1077
1078
1079 \emph on
1080 $DATADIR
1081 \emph default
1082
1083 \backslash
1084 doc
1085 \end_inset
1086 </cell>
1087 </row>
1088 <row topline="true">
1089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1090 \begin_inset Text
1091
1092 \layout Standard
1093
1094
1095 \emph on
1096 INCLUDE_DIR_SUFFIX
1097 \end_inset
1098 </cell>
1099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1100 \begin_inset Text
1101
1102 \layout Standard
1103
1104 sdcc/include
1105 \end_inset
1106 </cell>
1107 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1108 \begin_inset Text
1109
1110 \layout Standard
1111
1112 include
1113 \end_inset
1114 </cell>
1115 </row>
1116 <row topline="true" bottomline="true">
1117 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1118 \begin_inset Text
1119
1120 \layout Standard
1121
1122
1123 \emph on
1124 LIB_DIR_SUFFIX
1125 \end_inset
1126 </cell>
1127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1128 \begin_inset Text
1129
1130 \layout Standard
1131
1132 sdcc/lib
1133 \end_inset
1134 </cell>
1135 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1136 \begin_inset Text
1137
1138 \layout Standard
1139
1140 lib
1141 \end_inset
1142 </cell>
1143 </row>
1144 </lyxtabular>
1145
1146 \end_inset
1147
1148
1149 \newline
1150
1151 \layout Standard
1152 \noindent
1153 'configure' also computes relative paths.
1154  This is needed for full relocatability of a binary package and to complete
1155  search paths (see section search paths below):
1156 \newline
1157
1158 \layout Standard
1159 \align center
1160
1161 \begin_inset  Tabular
1162 <lyxtabular version="3" rows="4" columns="3">
1163 <features>
1164 <column alignment="block" valignment="top" leftline="true" width="0in">
1165 <column alignment="block" valignment="top" leftline="true" width="0in">
1166 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1167 <row topline="true" bottomline="true">
1168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1169 \begin_inset Text
1170
1171 \layout Standard
1172
1173 Variable (computed)
1174 \end_inset
1175 </cell>
1176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1177 \begin_inset Text
1178
1179 \layout Standard
1180
1181 default
1182 \end_inset
1183 </cell>
1184 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1185 \begin_inset Text
1186
1187 \layout Standard
1188
1189 Win32 builds
1190 \end_inset
1191 </cell>
1192 </row>
1193 <row topline="true" bottomline="true">
1194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1195 \begin_inset Text
1196
1197 \layout Standard
1198
1199
1200 \emph on
1201 BIN2DATA_DIR
1202 \end_inset
1203 </cell>
1204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1205 \begin_inset Text
1206
1207 \layout Standard
1208
1209 ../share
1210 \end_inset
1211 </cell>
1212 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1213 \begin_inset Text
1214
1215 \layout Standard
1216
1217 ..
1218 \end_inset
1219 </cell>
1220 </row>
1221 <row bottomline="true">
1222 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1223 \begin_inset Text
1224
1225 \layout Standard
1226
1227
1228 \emph on
1229 PREFIX2BIN_DIR
1230 \end_inset
1231 </cell>
1232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1233 \begin_inset Text
1234
1235 \layout Standard
1236
1237 bin
1238 \end_inset
1239 </cell>
1240 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1241 \begin_inset Text
1242
1243 \layout Standard
1244
1245 bin
1246 \end_inset
1247 </cell>
1248 </row>
1249 <row bottomline="true">
1250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1251 \begin_inset Text
1252
1253 \layout Standard
1254
1255
1256 \emph on
1257 PREFIX2DATA_DIR
1258 \end_inset
1259 </cell>
1260 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1261 \begin_inset Text
1262
1263 \layout Standard
1264
1265 share/sdcc
1266 \end_inset
1267 </cell>
1268 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1269 \begin_inset Text
1270
1271 \layout Standard
1272
1273 \end_inset
1274 </cell>
1275 </row>
1276 </lyxtabular>
1277
1278 \end_inset
1279
1280
1281 \newline
1282
1283 \layout Standard
1284 \noindent
1285 Examples:
1286 \layout LyX-Code
1287
1288 ./configure
1289 \newline
1290 ./configure -
1291 \begin_inset ERT
1292 status Collapsed
1293
1294 \layout Standard
1295
1296 \backslash
1297 /
1298 \end_inset
1299
1300 -prefix=
1301 \begin_inset Quotes srd
1302 \end_inset
1303
1304 /usr/bin
1305 \begin_inset Quotes srd
1306 \end_inset
1307
1308  -
1309 \begin_inset ERT
1310 status Collapsed
1311
1312 \layout Standard
1313
1314 \backslash
1315 /
1316 \end_inset
1317
1318 -datadir=
1319 \begin_inset Quotes srd
1320 \end_inset
1321
1322 /usr/share
1323 \begin_inset Quotes srd
1324 \end_inset
1325
1326
1327 \newline
1328 ./configure -
1329 \begin_inset ERT
1330 status Collapsed
1331
1332 \layout Standard
1333
1334 \backslash
1335 /
1336 \end_inset
1337
1338 -disable-avr-port -
1339 \begin_inset ERT
1340 status Collapsed
1341
1342 \layout Standard
1343
1344 \backslash
1345 /
1346 \end_inset
1347
1348 -disable-xa51-port
1349 \layout Standard
1350
1351 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1352 32'):
1353 \layout LyX-Code
1354
1355 ./configure
1356 \backslash
1357
1358 \newline
1359 CC=
1360 \begin_inset Quotes srd
1361 \end_inset
1362
1363 i586-mingw32msvc-gcc
1364 \begin_inset Quotes srd
1365 \end_inset
1366
1367  CXX=
1368 \begin_inset Quotes srd
1369 \end_inset
1370
1371 i586-mingw32msvc-g++
1372 \begin_inset Quotes srd
1373 \end_inset
1374
1375
1376 \backslash
1377
1378 \newline
1379 RANLIB=
1380 \begin_inset Quotes srd
1381 \end_inset
1382
1383 i586-mingw32msvc-ranlib
1384 \begin_inset Quotes srd
1385 \end_inset
1386
1387
1388 \backslash
1389
1390 \newline
1391 STRIP=
1392 \begin_inset Quotes srd
1393 \end_inset
1394
1395 i586-mingw32msvc-strip
1396 \begin_inset Quotes srd
1397 \end_inset
1398
1399
1400 \backslash
1401
1402 \newline
1403 -
1404 \begin_inset ERT
1405 status Collapsed
1406
1407 \layout Standard
1408
1409 \backslash
1410 /
1411 \end_inset
1412
1413 -prefix=
1414 \begin_inset Quotes srd
1415 \end_inset
1416
1417 /sdcc
1418 \begin_inset Quotes srd
1419 \end_inset
1420
1421
1422 \backslash
1423
1424 \newline
1425 -
1426 \begin_inset ERT
1427 status Collapsed
1428
1429 \layout Standard
1430
1431 \backslash
1432 /
1433 \end_inset
1434
1435 -datadir=
1436 \begin_inset Quotes srd
1437 \end_inset
1438
1439 /sdcc
1440 \begin_inset Quotes srd
1441 \end_inset
1442
1443
1444 \backslash
1445
1446 \newline
1447 docdir=
1448 \begin_inset Quotes srd
1449 \end_inset
1450
1451 /sdcc/doc
1452 \begin_inset Quotes srd
1453 \end_inset
1454
1455
1456 \backslash
1457
1458 \newline
1459 include_dir_suffix=
1460 \begin_inset Quotes srd
1461 \end_inset
1462
1463 include
1464 \begin_inset Quotes srd
1465 \end_inset
1466
1467
1468 \backslash
1469
1470 \newline
1471 lib_dir_suffix=
1472 \begin_inset Quotes srd
1473 \end_inset
1474
1475 lib
1476 \begin_inset Quotes srd
1477 \end_inset
1478
1479
1480 \backslash
1481
1482 \newline
1483 sdccconf_h_dir_separator=
1484 \begin_inset Quotes srd
1485 \end_inset
1486
1487
1488 \backslash
1489
1490 \backslash
1491
1492 \backslash
1493
1494 \backslash
1495
1496 \begin_inset Quotes srd
1497 \end_inset
1498
1499
1500 \backslash
1501
1502 \newline
1503 -
1504 \begin_inset ERT
1505 status Collapsed
1506
1507 \layout Standard
1508
1509 \backslash
1510 /
1511 \end_inset
1512
1513 -disable-device-lib-build
1514 \backslash
1515
1516 \newline
1517 -
1518 \begin_inset ERT
1519 status Collapsed
1520
1521 \layout Standard
1522
1523 \backslash
1524 /
1525 \end_inset
1526
1527 -disable-ucsim
1528 \backslash
1529
1530 \newline
1531 -
1532 \begin_inset ERT
1533 status Collapsed
1534
1535 \layout Standard
1536
1537 \backslash
1538 /
1539 \end_inset
1540
1541 -host=i586-mingw32msvc -
1542 \begin_inset ERT
1543 status Collapsed
1544
1545 \layout Standard
1546
1547 \backslash
1548 /
1549 \end_inset
1550
1551 -build=unknown-unknown-linux-gnu
1552 \layout Standard
1553
1554 To
1555 \begin_inset Quotes sld
1556 \end_inset
1557
1558 cross
1559 \begin_inset Quotes srd
1560 \end_inset
1561
1562 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1563 ):
1564 \layout LyX-Code
1565
1566 ./configure -C
1567 \backslash
1568
1569 \newline
1570 CFLAGS=
1571 \begin_inset Quotes srd
1572 \end_inset
1573
1574 -mno-cygwin -O2
1575 \begin_inset Quotes srd
1576 \end_inset
1577
1578
1579 \backslash
1580
1581 \newline
1582 LDFLAGS=
1583 \begin_inset Quotes srd
1584 \end_inset
1585
1586 -mno-cygwin
1587 \begin_inset Quotes srd
1588 \end_inset
1589
1590
1591 \backslash
1592
1593 \newline
1594 -
1595 \begin_inset ERT
1596 status Collapsed
1597
1598 \layout Standard
1599
1600 \backslash
1601 /
1602 \end_inset
1603
1604 -prefix=
1605 \begin_inset Quotes srd
1606 \end_inset
1607
1608 /sdcc
1609 \begin_inset Quotes srd
1610 \end_inset
1611
1612
1613 \backslash
1614
1615 \newline
1616 -
1617 \begin_inset ERT
1618 status Collapsed
1619
1620 \layout Standard
1621
1622 \backslash
1623 /
1624 \end_inset
1625
1626 -datadir=
1627 \begin_inset Quotes srd
1628 \end_inset
1629
1630 /sdcc
1631 \begin_inset Quotes srd
1632 \end_inset
1633
1634
1635 \backslash
1636
1637 \newline
1638 docdir=
1639 \begin_inset Quotes srd
1640 \end_inset
1641
1642 /sdcc/doc
1643 \begin_inset Quotes srd
1644 \end_inset
1645
1646
1647 \backslash
1648
1649 \newline
1650 include_dir_suffix=
1651 \begin_inset Quotes srd
1652 \end_inset
1653
1654 include
1655 \begin_inset Quotes srd
1656 \end_inset
1657
1658
1659 \backslash
1660
1661 \newline
1662 lib_dir_suffix=
1663 \begin_inset Quotes srd
1664 \end_inset
1665
1666 lib
1667 \begin_inset Quotes srd
1668 \end_inset
1669
1670
1671 \backslash
1672
1673 \newline
1674 sdccconf_h_dir_separator=
1675 \begin_inset Quotes srd
1676 \end_inset
1677
1678
1679 \backslash
1680
1681 \backslash
1682
1683 \backslash
1684
1685 \backslash
1686
1687 \begin_inset Quotes srd
1688 \end_inset
1689
1690
1691 \backslash
1692
1693 \newline
1694 -
1695 \begin_inset ERT
1696 status Collapsed
1697
1698 \layout Standard
1699
1700 \backslash
1701 /
1702 \end_inset
1703
1704 -disable-ucsim
1705 \layout Standard
1706
1707 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1708  The option '-
1709 \begin_inset ERT
1710 status Collapsed
1711
1712 \layout Standard
1713
1714 \backslash
1715 /
1716 \end_inset
1717
1718 -C' turns on caching, which gives a little bit extra speed.
1719  However if options are changed, it can be necessary to delete the config.cache
1720  file.
1721 \layout Section
1722
1723 Install paths
1724 \begin_inset LatexCommand \label{sub:Install-paths}
1725
1726 \end_inset
1727
1728
1729 \begin_inset LatexCommand \index{Install paths}
1730
1731 \end_inset
1732
1733
1734 \layout Standard
1735 \added_space_top medskip \align center
1736
1737 \begin_inset  Tabular
1738 <lyxtabular version="3" rows="5" columns="4">
1739 <features>
1740 <column alignment="center" valignment="top" leftline="true" width="0">
1741 <column alignment="center" valignment="top" leftline="true" width="0">
1742 <column alignment="center" valignment="top" leftline="true" width="0">
1743 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1744 <row topline="true" bottomline="true">
1745 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1746 \begin_inset Text
1747
1748 \layout Standard
1749
1750
1751 \series bold
1752 Description
1753 \end_inset
1754 </cell>
1755 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1756 \begin_inset Text
1757
1758 \layout Standard
1759
1760
1761 \series bold
1762 Path
1763 \end_inset
1764 </cell>
1765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1766 \begin_inset Text
1767
1768 \layout Standard
1769
1770
1771 \series bold
1772 Default
1773 \end_inset
1774 </cell>
1775 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1776 \begin_inset Text
1777
1778 \layout Standard
1779
1780
1781 \series bold
1782 Win32 builds
1783 \end_inset
1784 </cell>
1785 </row>
1786 <row topline="true">
1787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1788 \begin_inset Text
1789
1790 \layout Standard
1791
1792 Binary files*
1793 \end_inset
1794 </cell>
1795 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1796 \begin_inset Text
1797
1798 \layout Standard
1799
1800
1801 \emph on
1802 $EXEC_PREFIX
1803 \end_inset
1804 </cell>
1805 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1806 \begin_inset Text
1807
1808 \layout Standard
1809
1810 /usr/local/bin
1811 \end_inset
1812 </cell>
1813 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1814 \begin_inset Text
1815
1816 \layout Standard
1817
1818
1819 \backslash
1820 sdcc
1821 \backslash
1822 bin
1823 \end_inset
1824 </cell>
1825 </row>
1826 <row topline="true">
1827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1828 \begin_inset Text
1829
1830 \layout Standard
1831
1832 Include files
1833 \end_inset
1834 </cell>
1835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1836 \begin_inset Text
1837
1838 \layout Standard
1839
1840
1841 \emph on
1842 $DATADIR/ $INCLUDE_DIR_SUFFIX
1843 \end_inset
1844 </cell>
1845 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1846 \begin_inset Text
1847
1848 \layout Standard
1849
1850 /usr/local/share/sdcc/include
1851 \end_inset
1852 </cell>
1853 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1854 \begin_inset Text
1855
1856 \layout Standard
1857
1858
1859 \backslash
1860 sdcc
1861 \backslash
1862 include
1863 \end_inset
1864 </cell>
1865 </row>
1866 <row topline="true">
1867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1868 \begin_inset Text
1869
1870 \layout Standard
1871
1872 Library file**
1873 \end_inset
1874 </cell>
1875 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1876 \begin_inset Text
1877
1878 \layout Standard
1879
1880
1881 \emph on
1882 $DATADIR/$LIB_DIR_SUFFIX
1883 \end_inset
1884 </cell>
1885 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1886 \begin_inset Text
1887
1888 \layout Standard
1889
1890 /usr/local/share/sdcc/lib
1891 \end_inset
1892 </cell>
1893 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1894 \begin_inset Text
1895
1896 \layout Standard
1897
1898
1899 \backslash
1900 sdcc
1901 \backslash
1902 lib
1903 \end_inset
1904 </cell>
1905 </row>
1906 <row topline="true" bottomline="true">
1907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1908 \begin_inset Text
1909
1910 \layout Standard
1911
1912 Documentation
1913 \end_inset
1914 </cell>
1915 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1916 \begin_inset Text
1917
1918 \layout Standard
1919
1920
1921 \emph on
1922 $DOCDIR
1923 \end_inset
1924 </cell>
1925 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1926 \begin_inset Text
1927
1928 \layout Standard
1929
1930 /usr/local/share/sdcc/doc
1931 \end_inset
1932 </cell>
1933 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1934 \begin_inset Text
1935
1936 \layout Standard
1937
1938
1939 \backslash
1940 sdcc
1941 \backslash
1942 doc
1943 \end_inset
1944 </cell>
1945 </row>
1946 </lyxtabular>
1947
1948 \end_inset
1949
1950
1951 \layout Verse
1952
1953
1954 \size footnotesize
1955 *compiler, preprocessor, assembler, and linker
1956 \newline
1957 **the
1958 \shape italic
1959 model
1960 \shape default
1961  is auto-appended by the compiler, e.g.
1962  small, large, z80, ds390 etc
1963 \layout Standard
1964 \noindent
1965 The install paths can still be changed during `make install` with e.g.:
1966 \layout LyX-Code
1967
1968 make install prefix=$(HOME)/local/sdcc
1969 \layout Standard
1970
1971 Of course this doesn't change the search paths compiled into the binaries.
1972 \newline
1973
1974 \newline
1975 Moreover the install path can be changed by defining DESTDIR
1976 \begin_inset LatexCommand \index{DESTDIR}
1977
1978 \end_inset
1979
1980 :
1981 \layout LyX-Code
1982
1983 make install DESTDIR=$(HOME)/sdcc.rpm/
1984 \layout Standard
1985
1986 Please note that DESTDIR must have a trailing slash!
1987 \layout Section
1988
1989 Search Paths
1990 \begin_inset LatexCommand \label{sub:Search-Paths}
1991
1992 \end_inset
1993
1994
1995 \begin_inset LatexCommand \index{Search path}
1996
1997 \end_inset
1998
1999
2000 \layout Standard
2001
2002 Some search paths or parts of them are determined by configure variables
2003  (in
2004 \emph on
2005 italics
2006 \emph default
2007 , see section above).
2008  Further search paths are determined by environment variables during runtime.
2009
2010 \newline
2011 The paths searched when running the compiler are as follows (the first catch
2012  wins):
2013 \newline
2014
2015 \newline
2016 1.
2017  Binary files (preprocessor, assembler and linker)
2018 \newline
2019
2020 \layout Standard
2021 \align center
2022
2023 \begin_inset  Tabular
2024 <lyxtabular version="3" rows="4" columns="3">
2025 <features>
2026 <column alignment="block" valignment="top" leftline="true" width="0in">
2027 <column alignment="block" valignment="top" leftline="true" width="0in">
2028 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2029 <row topline="true" bottomline="true">
2030 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2031 \begin_inset Text
2032
2033 \layout Standard
2034
2035 Search path
2036 \end_inset
2037 </cell>
2038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2039 \begin_inset Text
2040
2041 \layout Standard
2042
2043 default
2044 \end_inset
2045 </cell>
2046 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2047 \begin_inset Text
2048
2049 \layout Standard
2050
2051 Win32 builds
2052 \end_inset
2053 </cell>
2054 </row>
2055 <row topline="true">
2056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2057 \begin_inset Text
2058
2059 \layout Standard
2060
2061 $SDCC_HOME/
2062 \emph on
2063 $PPREFIX2BIN_DIR
2064 \end_inset
2065 </cell>
2066 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2067 \begin_inset Text
2068
2069 \layout Standard
2070
2071 $SDCC_HOME/bin
2072 \end_inset
2073 </cell>
2074 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2075 \begin_inset Text
2076
2077 \layout Standard
2078
2079 $SDCC_HOME
2080 \backslash
2081 bin
2082 \end_inset
2083 </cell>
2084 </row>
2085 <row topline="true">
2086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2087 \begin_inset Text
2088
2089 \layout Standard
2090
2091 Path of argv[0] (if available)
2092 \end_inset
2093 </cell>
2094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2095 \begin_inset Text
2096
2097 \layout Standard
2098
2099 Path of argv[0]
2100 \end_inset
2101 </cell>
2102 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2103 \begin_inset Text
2104
2105 \layout Standard
2106
2107 Path of argv[0]
2108 \end_inset
2109 </cell>
2110 </row>
2111 <row topline="true" bottomline="true">
2112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2113 \begin_inset Text
2114
2115 \layout Standard
2116
2117 $PATH
2118 \end_inset
2119 </cell>
2120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2121 \begin_inset Text
2122
2123 \layout Standard
2124
2125 $PATH
2126 \end_inset
2127 </cell>
2128 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2129 \begin_inset Text
2130
2131 \layout Standard
2132
2133 $PATH
2134 \end_inset
2135 </cell>
2136 </row>
2137 </lyxtabular>
2138
2139 \end_inset
2140
2141
2142 \newline
2143
2144 \layout Standard
2145 \noindent
2146 2.
2147  Include files
2148 \newline
2149
2150 \layout Standard
2151 \align center
2152
2153 \begin_inset  Tabular
2154 <lyxtabular version="3" rows="6" columns="3">
2155 <features>
2156 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2157 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2158 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2159 <row topline="true" bottomline="true">
2160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2161 \begin_inset Text
2162
2163 \layout Standard
2164
2165 Search path
2166 \end_inset
2167 </cell>
2168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2169 \begin_inset Text
2170
2171 \layout Standard
2172
2173 default
2174 \end_inset
2175 </cell>
2176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2177 \begin_inset Text
2178
2179 \layout Standard
2180
2181 Win32 builds
2182 \end_inset
2183 </cell>
2184 </row>
2185 <row topline="true">
2186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2187 \begin_inset Text
2188
2189 \layout Standard
2190
2191 -
2192 \begin_inset ERT
2193 status Collapsed
2194
2195 \layout Standard
2196
2197 \backslash
2198 /
2199 \end_inset
2200
2201 -I dir
2202 \end_inset
2203 </cell>
2204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2205 \begin_inset Text
2206
2207 \layout Standard
2208
2209 -
2210 \begin_inset ERT
2211 status Collapsed
2212
2213 \layout Standard
2214
2215 \backslash
2216 /
2217 \end_inset
2218
2219 -I dir
2220 \end_inset
2221 </cell>
2222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2223 \begin_inset Text
2224
2225 \layout Standard
2226
2227 -
2228 \begin_inset ERT
2229 status Collapsed
2230
2231 \layout Standard
2232
2233 \backslash
2234 /
2235 \end_inset
2236
2237 -I dir
2238 \end_inset
2239 </cell>
2240 </row>
2241 <row topline="true">
2242 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2243 \begin_inset Text
2244
2245 \layout Standard
2246
2247 $SDCC_INCLUDE
2248 \end_inset
2249 </cell>
2250 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2251 \begin_inset Text
2252
2253 \layout Standard
2254
2255 $SDCC_INCLUDE
2256 \end_inset
2257 </cell>
2258 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2259 \begin_inset Text
2260
2261 \layout Standard
2262
2263 $SDCC_INCLUDE
2264 \end_inset
2265 </cell>
2266 </row>
2267 <row topline="true">
2268 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2269 \begin_inset Text
2270
2271 \layout Standard
2272
2273 $SDCC_HOME/
2274 \newline
2275
2276 \emph on
2277 $PREFIX2DATA_DIR/
2278 \newline
2279 $INCLUDE_DIR_SUFFIX
2280 \end_inset
2281 </cell>
2282 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2283 \begin_inset Text
2284
2285 \layout Standard
2286
2287 $SDCC_ HOME/
2288 \newline
2289 share/sdcc/
2290 \newline
2291 include
2292 \end_inset
2293 </cell>
2294 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2295 \begin_inset Text
2296
2297 \layout Standard
2298
2299 $SDCC_HOME
2300 \backslash
2301 include
2302 \end_inset
2303 </cell>
2304 </row>
2305 <row topline="true">
2306 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2307 \begin_inset Text
2308
2309 \layout Standard
2310
2311 path(argv[0])/
2312 \newline
2313
2314 \emph on
2315 $BIN2DATADIR/
2316 \emph default
2317
2318 \newline
2319
2320 \emph on
2321 $INCLUDE_DIR_SUFFIX
2322 \end_inset
2323 </cell>
2324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2325 \begin_inset Text
2326
2327 \layout Standard
2328
2329 path(argv[0])/
2330 \newline
2331 ../sdcc/include
2332 \newline
2333 \SpecialChar ~
2334 \SpecialChar ~
2335 \SpecialChar ~
2336 \SpecialChar ~
2337 \SpecialChar ~
2338 \SpecialChar ~
2339 \SpecialChar ~
2340 \SpecialChar ~
2341 \SpecialChar ~
2342 \SpecialChar ~
2343 \SpecialChar ~
2344 \SpecialChar ~
2345 \SpecialChar ~
2346 \SpecialChar ~
2347 \SpecialChar ~
2348 \SpecialChar ~
2349 \SpecialChar ~
2350 \SpecialChar ~
2351 \SpecialChar ~
2352 \SpecialChar ~
2353 \SpecialChar ~
2354 \SpecialChar ~
2355 \SpecialChar ~
2356 \SpecialChar ~
2357 \SpecialChar ~
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
2372 \end_inset
2373 </cell>
2374 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2375 \begin_inset Text
2376
2377 \layout Standard
2378
2379 path(argv[0])
2380 \backslash
2381 ..
2382 \backslash
2383 include
2384 \end_inset
2385 </cell>
2386 </row>
2387 <row topline="true" bottomline="true">
2388 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2389 \begin_inset Text
2390
2391 \layout Standard
2392
2393
2394 \emph on
2395 $DATADIR/
2396 \emph default
2397
2398 \newline
2399
2400 \emph on
2401 $INCLUDE_DIR_SUFFIX
2402 \end_inset
2403 </cell>
2404 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2405 \begin_inset Text
2406
2407 \layout Standard
2408
2409 /usr/local/share/sdcc/
2410 \newline
2411 include
2412 \end_inset
2413 </cell>
2414 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2415 \begin_inset Text
2416
2417 \layout Standard
2418
2419 (not on Win32)
2420 \end_inset
2421 </cell>
2422 </row>
2423 </lyxtabular>
2424
2425 \end_inset
2426
2427
2428 \newline
2429
2430 \layout Standard
2431 \noindent
2432 The option -
2433 \begin_inset ERT
2434 status Collapsed
2435
2436 \layout Standard
2437
2438 \backslash
2439 /
2440 \end_inset
2441
2442 -nostdinc disables the last two search paths.
2443 \newline
2444
2445 \newline
2446 3.
2447  Library files
2448 \newline
2449
2450 \layout Standard
2451
2452 With the exception of
2453 \begin_inset Quotes sld
2454 \end_inset
2455
2456 -
2457 \begin_inset ERT
2458 status Collapsed
2459
2460 \layout Standard
2461
2462 \backslash
2463 /
2464 \end_inset
2465
2466 -L dir
2467 \begin_inset Quotes srd
2468 \end_inset
2469
2470  the
2471 \shape italic
2472 model
2473 \shape default
2474  is auto-appended by the compiler (e.g.
2475  small, large, z80, ds390 etc.).
2476
2477 \newline
2478
2479 \layout Standard
2480 \align center
2481
2482 \begin_inset  Tabular
2483 <lyxtabular version="3" rows="6" columns="3">
2484 <features>
2485 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2486 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2487 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2488 <row topline="true" bottomline="true">
2489 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2490 \begin_inset Text
2491
2492 \layout Standard
2493
2494 Search path
2495 \end_inset
2496 </cell>
2497 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2498 \begin_inset Text
2499
2500 \layout Standard
2501
2502 default
2503 \end_inset
2504 </cell>
2505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2506 \begin_inset Text
2507
2508 \layout Standard
2509
2510 Win32 builds
2511 \end_inset
2512 </cell>
2513 </row>
2514 <row topline="true">
2515 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2516 \begin_inset Text
2517
2518 \layout Standard
2519
2520 -
2521 \begin_inset ERT
2522 status Collapsed
2523
2524 \layout Standard
2525
2526 \backslash
2527 /
2528 \end_inset
2529
2530 -L dir
2531 \end_inset
2532 </cell>
2533 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2534 \begin_inset Text
2535
2536 \layout Standard
2537
2538 -
2539 \begin_inset ERT
2540 status Collapsed
2541
2542 \layout Standard
2543
2544 \backslash
2545 /
2546 \end_inset
2547
2548 -L dir
2549 \end_inset
2550 </cell>
2551 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2552 \begin_inset Text
2553
2554 \layout Standard
2555
2556 -
2557 \begin_inset ERT
2558 status Collapsed
2559
2560 \layout Standard
2561
2562 \backslash
2563 /
2564 \end_inset
2565
2566 -L dir
2567 \end_inset
2568 </cell>
2569 </row>
2570 <row topline="true">
2571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2572 \begin_inset Text
2573
2574 \layout Standard
2575
2576 $SDCC_LIB/
2577 \newline
2578
2579 \emph on
2580 <model>
2581 \end_inset
2582 </cell>
2583 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2584 \begin_inset Text
2585
2586 \layout Standard
2587
2588 $SDCC_LIB/
2589 \newline
2590
2591 \emph on
2592 <model>
2593 \end_inset
2594 </cell>
2595 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2596 \begin_inset Text
2597
2598 \layout Standard
2599
2600 $SDCC_LIB
2601 \backslash
2602
2603 \newline
2604
2605 \emph on
2606 <model>
2607 \end_inset
2608 </cell>
2609 </row>
2610 <row topline="true">
2611 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2612 \begin_inset Text
2613
2614 \layout Standard
2615
2616 $SDCC_HOME/
2617 \newline
2618
2619 \emph on
2620 $PREFIX2DATA_DIR/
2621 \newline
2622 $LIB_DIR_SUFFIX/<model>
2623 \end_inset
2624 </cell>
2625 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2626 \begin_inset Text
2627
2628 \layout Standard
2629
2630 $SDCC_HOME/
2631 \newline
2632 share/sdcc/
2633 \newline
2634 lib/
2635 \emph on
2636 <model>
2637 \end_inset
2638 </cell>
2639 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2640 \begin_inset Text
2641
2642 \layout Standard
2643
2644 $SDCC_HOME
2645 \backslash
2646 lib
2647 \backslash
2648
2649 \emph on
2650
2651 \newline
2652 <model>
2653 \end_inset
2654 </cell>
2655 </row>
2656 <row topline="true">
2657 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2658 \begin_inset Text
2659
2660 \layout Standard
2661
2662 path(argv[0])/
2663 \newline
2664
2665 \emph on
2666 $BIN2DATADIR/
2667 \emph default
2668
2669 \newline
2670
2671 \emph on
2672 $LIB_DIR_SUFFIX/<model>
2673 \end_inset
2674 </cell>
2675 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2676 \begin_inset Text
2677
2678 \layout Standard
2679
2680 path(argv[0])/
2681 \newline
2682 ../sdcc/lib/
2683 \emph on
2684 <model>
2685 \newline
2686 \SpecialChar ~
2687 \SpecialChar ~
2688 \SpecialChar ~
2689 \SpecialChar ~
2690 \SpecialChar ~
2691 \SpecialChar ~
2692 \SpecialChar ~
2693 \SpecialChar ~
2694 \SpecialChar ~
2695 \SpecialChar ~
2696 \SpecialChar ~
2697 \SpecialChar ~
2698 \SpecialChar ~
2699 \SpecialChar ~
2700 \SpecialChar ~
2701 \SpecialChar ~
2702 \SpecialChar ~
2703 \SpecialChar ~
2704 \SpecialChar ~
2705 \SpecialChar ~
2706 \SpecialChar ~
2707 \SpecialChar ~
2708 \SpecialChar ~
2709 \SpecialChar ~
2710 \SpecialChar ~
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
2726 \end_inset
2727 </cell>
2728 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2729 \begin_inset Text
2730
2731 \layout Standard
2732
2733 path(argv[0])
2734 \backslash
2735
2736 \newline
2737 ..
2738 \backslash
2739 lib
2740 \backslash
2741
2742 \emph on
2743 <model>
2744 \newline
2745 \SpecialChar ~
2746 \SpecialChar ~
2747 \SpecialChar ~
2748 \SpecialChar ~
2749 \SpecialChar ~
2750 \SpecialChar ~
2751 \SpecialChar ~
2752 \SpecialChar ~
2753 \SpecialChar ~
2754 \SpecialChar ~
2755 \SpecialChar ~
2756 \SpecialChar ~
2757 \SpecialChar ~
2758 \SpecialChar ~
2759 \SpecialChar ~
2760 \SpecialChar ~
2761 \SpecialChar ~
2762 \SpecialChar ~
2763 \SpecialChar ~
2764 \SpecialChar ~
2765 \SpecialChar ~
2766 \SpecialChar ~
2767 \SpecialChar ~
2768 \SpecialChar ~
2769 \SpecialChar ~
2770 \SpecialChar ~
2771 \SpecialChar ~
2772 \SpecialChar ~
2773 \SpecialChar ~
2774 \SpecialChar ~
2775 \SpecialChar ~
2776 \SpecialChar ~
2777 \SpecialChar ~
2778 \SpecialChar ~
2779 \SpecialChar ~
2780
2781 \end_inset
2782 </cell>
2783 </row>
2784 <row topline="true" bottomline="true">
2785 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2786 \begin_inset Text
2787
2788 \layout Standard
2789
2790
2791 \emph on
2792 $DATADIR/
2793 \newline
2794 $LIB_DIR_SUFFIX/<model>
2795 \end_inset
2796 </cell>
2797 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2798 \begin_inset Text
2799
2800 \layout Standard
2801
2802 /usr/local/share/sdcc/
2803 \newline
2804 lib/
2805 \emph on
2806 <model>
2807 \end_inset
2808 </cell>
2809 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2810 \begin_inset Text
2811
2812 \layout Standard
2813
2814 (not on Win32)
2815 \end_inset
2816 </cell>
2817 </row>
2818 </lyxtabular>
2819
2820 \end_inset
2821
2822
2823 \newline
2824
2825 \layout Comment
2826
2827 Don't delete any of the stray spaces in the table above without checking
2828  the HTML output (last line)!
2829 \layout Standard
2830
2831 \SpecialChar ~
2832
2833 \newline
2834 The option -
2835 \begin_inset ERT
2836 status Collapsed
2837
2838 \layout Standard
2839
2840 \backslash
2841 /
2842 \end_inset
2843
2844 -nostdlib disables the last two search paths.
2845 \layout Section
2846
2847 Building SDCC
2848 \begin_inset LatexCommand \index{Building SDCC}
2849
2850 \end_inset
2851
2852
2853 \layout Subsection
2854
2855 Building SDCC on Linux
2856 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2857
2858 \end_inset
2859
2860
2861 \layout Enumerate
2862
2863
2864 \series medium
2865 Download the source package
2866 \series default
2867  either from the SDCC CVS repository or from the nightly snapshots
2868 \series medium
2869 , it will be named something like sdcc
2870 \series default
2871 .src
2872 \series medium
2873 .t
2874 \series default
2875 ar.
2876 \series medium
2877 gz
2878 \series default
2879
2880 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2881
2882 \end_inset
2883
2884 .
2885 \layout Enumerate
2886
2887
2888 \series medium
2889 Bring up a command line terminal, such as xterm.
2890 \layout Enumerate
2891
2892
2893 \series medium
2894 Unpack the file using a command like:
2895 \family sans
2896 \series bold
2897 "tar -xvzf sdcc.src.tar.gz
2898 \family default
2899 \series default
2900 "
2901 \series medium
2902 , this will create a sub-directory called sdcc with all of the sources.
2903 \layout Enumerate
2904
2905 Change directory into the main SDCC directory, for example type:
2906 \family sans
2907 \series bold
2908 "cd sdcc
2909 \series default
2910 ".
2911 \layout Enumerate
2912
2913
2914 \series medium
2915 Type
2916 \family sans
2917 \series bold
2918 "./configure
2919 \family default
2920 \series default
2921 ".
2922  This configures the package for compilation on your system.
2923 \layout Enumerate
2924
2925
2926 \series medium
2927 Type
2928 \family sans
2929 \series bold
2930 "make
2931 \family default
2932 \series default
2933 "
2934 \series medium
2935 .
2936
2937 \series default
2938  All of the source packages will compile, this can take a while.
2939 \layout Enumerate
2940
2941
2942 \series medium
2943 Type
2944 \family sans
2945 \series bold
2946 "make install"
2947 \family default
2948 \series default
2949  as root
2950 \series medium
2951 .
2952
2953 \series default
2954  This copies the binary executables, the include files, the libraries and
2955  the documentation to the install directories.
2956  Proceed with section
2957 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
2958
2959 \end_inset
2960
2961 .
2962 \layout Subsection
2963
2964 Building SDCC on OSX 2.x
2965 \layout Standard
2966
2967 Follow the instruction for Linux.
2968 \newline
2969
2970 \newline
2971 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
2972 )) fails to compile SDCC.
2973  Fortunately there's also gcc 2.9.x installed, which works fine.
2974  This compiler can be selected by running 'configure' with:
2975 \layout LyX-Code
2976
2977 ./configure CC=gcc2 CXX=g++2
2978 \layout Subsection
2979
2980 Cross compiling SDCC on Linux for Windows
2981 \layout Standard
2982
2983 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
2984  See section 'Configure Options'.
2985 \layout Subsection
2986
2987 Building SDCC on Windows
2988 \layout Standard
2989
2990 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
2991  built on Windows.
2992  They use Unix-sockets, which are not available on Win32.
2993 \layout Subsection
2994
2995 Building SDCC using Cygwin and Mingw32
2996 \layout Standard
2997
2998 For building and installing a Cygwin executable follow the instructions
2999  for Linux.
3000 \newline
3001
3002 \newline
3003 On Cygwin a
3004 \begin_inset Quotes sld
3005 \end_inset
3006
3007 native
3008 \begin_inset Quotes srd
3009 \end_inset
3010
3011  Win32-binary can be built, which will not need the Cygwin-DLL.
3012  For the necessary 'configure' options see section 'configure options' or
3013  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3014 \newline
3015
3016 \newline
3017 In order to install Cygwin on Windows download setup.exe from
3018 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3019
3020 \end_inset
3021
3022 .
3023  Run it, set the
3024 \begin_inset Quotes sld
3025 \end_inset
3026
3027 default text file type
3028 \begin_inset Quotes srd
3029 \end_inset
3030
3031  to
3032 \begin_inset Quotes sld
3033 \end_inset
3034
3035 unix
3036 \begin_inset Quotes srd
3037 \end_inset
3038
3039  and download/install at least the following packages.
3040  Some packages are selected by default, others will be automatically selected
3041  because of dependencies with the manually selected packages.
3042  Never deselect these packages!
3043 \layout Itemize
3044
3045 flex
3046 \layout Itemize
3047
3048 bison
3049 \layout Itemize
3050
3051 gcc ; version 3.x is fine, no need to use the old 2.9x
3052 \layout Itemize
3053
3054 binutils ; selected with gcc
3055 \layout Itemize
3056
3057 make
3058 \layout Itemize
3059
3060 rxvt ; a nice console, which makes life much easier under windoze (see below)
3061 \layout Itemize
3062
3063 man ; not really needed for building SDCC, but you'll miss it sooner or
3064  later
3065 \layout Itemize
3066
3067 less ; not really needed for building SDCC, but you'll miss it sooner or
3068  later
3069 \layout Itemize
3070
3071 cvs ; only if you use CVS access
3072 \layout Standard
3073
3074 If you want to develop something you'll need:
3075 \layout Itemize
3076
3077 python ; for the regression tests
3078 \layout Itemize
3079
3080 gdb ; the gnu debugger, together with the nice GUI
3081 \begin_inset Quotes sld
3082 \end_inset
3083
3084 insight
3085 \begin_inset Quotes srd
3086 \end_inset
3087
3088
3089 \layout Itemize
3090
3091 openssh ; to access the CF or commit changes
3092 \layout Itemize
3093
3094 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3095  use autoconf-stable!
3096 \layout Standard
3097
3098 rxvt is a nice console with history.
3099  Replace in your cygwin.bat the line
3100 \layout LyX-Code
3101
3102 bash -
3103 \begin_inset ERT
3104 status Collapsed
3105
3106 \layout Standard
3107
3108 \backslash
3109 /
3110 \end_inset
3111
3112 -login -i
3113 \layout Standard
3114
3115 with (one line):
3116 \layout LyX-Code
3117
3118 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3119 \layout LyX-Code
3120
3121      -bg black -fg white -geometry 100x65 -e bash -
3122 \begin_inset ERT
3123 status Collapsed
3124
3125 \layout Standard
3126
3127 \backslash
3128 /
3129 \end_inset
3130
3131 -login
3132 \layout Standard
3133
3134 Text selected with the mouse is automatically copied to the clipboard, pasting
3135  works with shift-insert.
3136 \newline
3137
3138 \newline
3139 The other good tip is to make sure you have no //c/-style paths anywhere,
3140  use /cygdrive/c/ instead.
3141  Using // invokes a network lookup which is very slow.
3142  If you think
3143 \begin_inset Quotes sld
3144 \end_inset
3145
3146 cygdrive
3147 \begin_inset Quotes srd
3148 \end_inset
3149
3150  is too long, you can change it with e.g.
3151 \layout LyX-Code
3152
3153 mount -s -u -c /mnt
3154 \layout Standard
3155
3156 SDCC sources use the unix line ending LF.
3157  Life is much easier, if you store the source tree on a drive which is mounted
3158  in binary mode.
3159  And use an editor which can handle LF-only line endings.
3160  Make sure not to commit files with windows line endings.
3161  The tabulator spacing
3162 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3163
3164 \end_inset
3165
3166  used in the project is 8.
3167  Although a tabulator spacing of 8 is a sensible choice for programmers
3168  (it's a power of 2 and allows to display 8/16 bit signed variables without
3169  loosing columns) the plan is to move towards using only spaces in the source.
3170 \layout Subsection
3171
3172 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3173 \layout Standard
3174
3175
3176 \series medium
3177 Download the source package
3178 \series default
3179  either from the SDCC CVS repository or from the
3180 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3181
3182 \end_inset
3183
3184
3185 \series medium
3186 , it will be named something like sdcc
3187 \series default
3188 .src
3189 \series medium
3190 .tgz.
3191
3192 \series default
3193  SDCC is distributed with all the projects, workspaces, and files you need
3194  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3195  doesn't build under MSVC).
3196  The workspace name is 'sdcc.dsw'.
3197  Please note that as it is now, all the executables are created in a folder
3198  called sdcc
3199 \backslash
3200 bin_vc.
3201  Once built you need to copy the executables from sdcc
3202 \backslash
3203 bin_vc to sdcc
3204 \backslash
3205 bin before running SDCC.
3206
3207 \newline
3208
3209 \newline
3210 WARNING: Visual studio is very picky with line terminations; it expects
3211  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3212  If you are getting a message such as "This makefile was not generated by
3213  Developer Studio etc.
3214  etc.
3215 \begin_inset Quotes srd
3216 \end_inset
3217
3218  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3219  need to convert the Unix style line endings to DOS style line endings.
3220  To do so you can use the
3221 \begin_inset Quotes sld
3222 \end_inset
3223
3224 unix2dos
3225 \begin_inset Quotes srd
3226 \end_inset
3227
3228  utility freely available on the internet.
3229  Doug Hawkins reported in the sdcc-user list that this works:
3230 \newline
3231
3232 \newline
3233 C:
3234 \backslash
3235 Programming
3236 \backslash
3237 SDCC> unix2dos sdcc.dsw
3238 \newline
3239 C:
3240 \backslash
3241 Programming
3242 \backslash
3243 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3244 \newline
3245
3246 \newline
3247 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3248  flex.exe, and gawk.exe.
3249  One good place to get them is
3250 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3251
3252 \end_inset
3253
3254
3255 \newline
3256
3257 \newline
3258 Download the file UnxUtils
3259 \begin_inset LatexCommand \index{UnxUtils}
3260
3261 \end_inset
3262
3263 .zip.
3264  Now you have to install the utilities and setup MSVC so it can locate the
3265  required programs.
3266  Here there are two alternatives (choose one!):
3267 \layout Enumerate
3268
3269 The easy way:
3270 \newline
3271
3272 \newline
3273 a) Extract UnxUtils.zip to your C:
3274 \backslash
3275  hard disk PRESERVING the original paths, otherwise bison won't work.
3276  (If you are using WinZip make certain that 'Use folder names' is selected)
3277 \newline
3278
3279 \newline
3280 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3281  in 'Show directories for:' select 'Executable files', and in the directories
3282  window add a new path: 'C:
3283 \backslash
3284 user
3285 \backslash
3286 local
3287 \backslash
3288 wbin', click ok.
3289 \newline
3290
3291 \newline
3292 (As a side effect, you get a bunch of Unix utilities that could be useful,
3293  such as diff and patch.)
3294 \layout Enumerate
3295
3296 A more compact way:
3297 \newline
3298
3299 \newline
3300 This one avoids extracting a bunch of files you may not use, but requires
3301  some extra work:
3302 \newline
3303
3304 \newline
3305 a) Create a directory were to put the tools needed, or use a directory already
3306  present.
3307  Say for example 'C:
3308 \backslash
3309 util'.
3310 \newline
3311
3312 \newline
3313 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3314  to such directory WITHOUT preserving the original paths.
3315  (If you are using WinZip make certain that 'Use folder names' is not selected)
3316 \newline
3317
3318 \newline
3319 c) Rename bison.exe to '_bison.exe'.
3320 \newline
3321
3322 \newline
3323 d) Create a batch file 'bison.bat' in 'C:
3324 \backslash
3325 util
3326 \backslash
3327 ' and add these lines:
3328 \newline
3329 \SpecialChar ~
3330 \SpecialChar ~
3331 set BISON_SIMPLE=C:
3332 \backslash
3333 util
3334 \backslash
3335 bison.simple
3336 \newline
3337 \SpecialChar ~
3338 \SpecialChar ~
3339 set BISON_HAIRY=C:
3340 \backslash
3341 util
3342 \backslash
3343 bison.hairy
3344 \newline
3345 \SpecialChar ~
3346 \SpecialChar ~
3347 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3348 \newline
3349
3350 \newline
3351 Steps 'c' and 'd' are needed because bison requires by default that the
3352  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3353  '/usr/local/share/' I think.
3354  So it is necessary to tell bison where those files are located if they
3355  are not in such directory.
3356  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3357 \newline
3358
3359 \newline
3360 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3361  in 'Show directories for:' select 'Executable files', and in the directories
3362  window add a new path: 'c:
3363 \backslash
3364 util', click ok.
3365  Note that you can use any other path instead of 'c:
3366 \backslash
3367 util', even the path where the Visual C++ tools are, probably: 'C:
3368 \backslash
3369 Program Files
3370 \backslash
3371 Microsoft Visual Studio
3372 \backslash
3373 Common
3374 \backslash
3375 Tools'.
3376  So you don't have to execute step 'e' :)
3377 \layout Standard
3378
3379 That is it.
3380  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3381  the executables from sdcc
3382 \backslash
3383 bin_vc to sdcc
3384 \backslash
3385 bin, and you can compile using SDCC.
3386 \layout Subsection
3387
3388 Building SDCC Using Borland
3389 \layout Enumerate
3390
3391 From the sdcc directory, run the command "make -f Makefile.bcc".
3392  This should regenerate all the .exe files in the bin directory except for
3393  sdcdb.exe (which currently doesn't build under Borland C++).
3394 \layout Enumerate
3395
3396 If you modify any source files and need to rebuild, be aware that the dependenci
3397 es may not be correctly calculated.
3398  The safest option is to delete all .obj files and run the build again.
3399  From a Cygwin BASH prompt, this can easily be done with the command (be
3400  sure you are in the sdcc directory):
3401 \newline
3402
3403 \newline
3404
3405 \family sans
3406 \series bold
3407 find .
3408
3409 \backslash
3410 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3411 \backslash
3412 ) -print -exec rm {}
3413 \backslash
3414 ;
3415 \family default
3416 \series default
3417
3418 \newline
3419
3420 \newline
3421 or on Windows NT/2000/XP from the command prompt with the command:
3422 \newline
3423
3424 \family sans
3425 \series bold
3426
3427 \newline
3428 del /s *.obj *.lib *.rul
3429 \family default
3430 \series default
3431  from the sdcc directory.
3432 \layout Subsection
3433
3434 Windows Install Using a Binary Package
3435 \begin_inset LatexCommand \label{sub:Windows-Install}
3436
3437 \end_inset
3438
3439
3440 \layout Enumerate
3441
3442 Download the binary package from
3443 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3444
3445 \end_inset
3446
3447  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3448  This should unpack to a group of sub-directories.
3449  An example directory structure after unpacking the mingw32 package is:
3450  c:
3451 \backslash
3452 sdcc
3453 \backslash
3454 bin for the executables, c:
3455 \backslash
3456 sdcc
3457 \backslash
3458 include and c:
3459 \backslash
3460 sdcc
3461 \backslash
3462 lib for the include and libraries.
3463 \layout Enumerate
3464
3465 Adjust your environment variable PATH to include the location of the bin
3466  directory or start sdcc using the full path.
3467 \layout Section
3468
3469 Building the Documentation
3470 \layout Standard
3471
3472 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3473  as changing into the doc directory and typing
3474 \family sans
3475 \series bold
3476
3477 \begin_inset Quotes srd
3478 \end_inset
3479
3480 make
3481 \begin_inset Quotes srd
3482 \end_inset
3483
3484
3485 \family default
3486 \series default
3487  there.
3488  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3489 x).
3490  Using LyX
3491 \begin_inset LatexCommand \url{www.lyx.org}
3492
3493 \end_inset
3494
3495  as editor this is straightforward.
3496  Prebuilt documentation in html and pdf format is available from
3497 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3498
3499 \end_inset
3500
3501 .
3502 \layout Section
3503
3504 Reading the Documentation
3505 \layout Standard
3506
3507 Currently reading the document in pdf format is recommended, as for unknown
3508  reason the hyperlinks are working there whereas in the html version they
3509  are not
3510 \begin_inset Foot
3511 collapsed false
3512
3513 \layout Standard
3514
3515 If you should know why please drop us a note
3516 \end_inset
3517
3518 .
3519  You'll find the pdf version at
3520 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
3521
3522 \end_inset
3523
3524 .
3525 \newline
3526 This documentation is in some aspects different from a commercial documentation:
3527
3528 \layout Itemize
3529
3530 It tries to document SDCC for several processor architectures in one document
3531  (commercially these probably would be separate documents/products).
3532  This document
3533 \begin_inset LatexCommand \index{Status of documentation}
3534
3535 \end_inset
3536
3537  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3538 on about f.e.
3539  Z80, PIC14, PIC16 and HC08.
3540 \layout Itemize
3541
3542 There are many references pointing away from this documentation.
3543  Don't let this distract you.
3544  If there f.e.
3545  was a reference like
3546 \begin_inset LatexCommand \url{www.opencores.org}
3547
3548 \end_inset
3549
3550  together with a statement
3551 \begin_inset Quotes sld
3552 \end_inset
3553
3554 some processors which are targetted by SDCC can be implemented in a
3555 \emph on
3556 f
3557 \emph default
3558 ield
3559 \emph on
3560 p
3561 \emph default
3562 rogrammable
3563 \emph on
3564 g
3565 \emph default
3566 ate
3567 \emph on
3568 a
3569 \emph default
3570 rray
3571 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3572
3573 \end_inset
3574
3575
3576 \begin_inset Quotes srd
3577 \end_inset
3578
3579  we expect you to have a quick look there and come back.
3580  If you read this you are on the right track.
3581 \layout Itemize
3582
3583 Some sections attribute more space to problems, restrictions and warnings
3584  than to the solution.
3585 \layout Itemize
3586
3587 The installation section and the section about the debugger is intimidating.
3588 \layout Itemize
3589
3590 There are still lots of typos and there are more different writing styles
3591  than pictures.
3592 \layout Section
3593
3594 Testing the SDCC Compiler
3595 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3596
3597 \end_inset
3598
3599
3600 \layout Standard
3601
3602 The first thing you should do after installing your SDCC compiler is to
3603  see if it runs.
3604  Type
3605 \family sans
3606 \series bold
3607 "sdcc -
3608 \begin_inset ERT
3609 status Collapsed
3610
3611 \layout Standard
3612
3613 \backslash
3614 /
3615 \end_inset
3616
3617 -version"
3618 \begin_inset LatexCommand \index{version}
3619
3620 \end_inset
3621
3622
3623 \family default
3624 \series default
3625  at the prompt, and the program should run and tell you the version.
3626  If it doesn't run, or gives a message about not finding sdcc program, then
3627  you need to check over your installation.
3628  Make sure that the sdcc bin directory is in your executable search path
3629  defined by the PATH environment setting (
3630 \series medium
3631 see
3632 \series default
3633 section
3634 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3635
3636 \end_inset
3637
3638 \SpecialChar ~
3639
3640 \series medium
3641 Install trouble-shooting for suggestions
3642 \series default
3643 ).
3644  Make sure that the sdcc program is in the bin folder, if not perhaps something
3645  did not install correctly.
3646 \newline
3647
3648 \newline
3649
3650 \series medium
3651 SDCC
3652 \series default
3653 is commonly installed as described in section
3654 \begin_inset Quotes sld
3655 \end_inset
3656
3657 Install and search paths
3658 \begin_inset Quotes srd
3659 \end_inset
3660
3661 .
3662 \newline
3663
3664 \newline
3665
3666 \series medium
3667 Make sure the compiler works on a very simple example.
3668  Type in the following test.c program using your favorite
3669 \series default
3670 ASCII
3671 \series medium
3672 editor:
3673 \layout Verse
3674
3675
3676 \family typewriter
3677 char test;
3678 \newline
3679
3680 \newline
3681 void main(void) {
3682 \newline
3683 \SpecialChar ~
3684 \SpecialChar ~
3685 \SpecialChar ~
3686 \SpecialChar ~
3687 test=0;
3688 \newline
3689 }
3690 \layout Standard
3691
3692
3693 \series medium
3694 Compile this using the following command:
3695 \family sans
3696 \series bold
3697 "sdcc -c test.c".
3698
3699 \family default
3700 \series default
3701
3702 \series medium
3703 If all goes well, the compiler will generate a test.asm and test.rel file.
3704  Congratulations, you've just compiled your first program with SDCC.
3705  We used the -c option to tell SDCC not to link the generated code, just
3706  to keep things simple for this step.
3707 \series default
3708
3709 \newline
3710
3711 \newline
3712
3713 \series medium
3714 The next step is to try it with the linker.
3715  Type in
3716 \family sans
3717 \series bold
3718 "sdcc test.c
3719 \family default
3720 \series default
3721 "
3722 \series medium
3723 .
3724  If all goes well the compiler will link with the libraries and produce
3725  a test.ihx output file.
3726  If this step fails
3727 \series default
3728
3729 \series medium
3730 (no test.ihx, and the linker generates warnings), then the problem is most
3731  likely that
3732 \series default
3733 SDCC
3734 \series medium
3735  cannot find the
3736 \series default
3737 /
3738 \series medium
3739 usr/local/share/sdcc/lib directory
3740 \series default
3741
3742 \series medium
3743 (see
3744 \series default
3745 section
3746 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3747
3748 \end_inset
3749
3750 \SpecialChar ~
3751
3752 \series medium
3753 Install trouble-shooting for suggestions).
3754 \series default
3755
3756 \newline
3757
3758 \newline
3759
3760 \series medium
3761 The final test is to ensure
3762 \series default
3763 SDCC
3764 \series medium
3765  can use the
3766 \series default
3767 standard
3768 \series medium
3769  header files and libraries.
3770  Edit test.c and change it to the following:
3771 \layout Verse
3772
3773
3774 \family typewriter
3775 #include <string.h>
3776 \newline
3777
3778 \newline
3779 char str1[10];
3780 \newline
3781
3782 \newline
3783 void main(void) {
3784 \newline
3785 \SpecialChar ~
3786 \SpecialChar ~
3787 strcpy(str1, "testing");
3788 \newline
3789 }
3790 \layout Standard
3791
3792
3793 \series medium
3794 Compile this by typing
3795 \family sans
3796 \series bold
3797 "sdcc test.c"
3798 \family default
3799 \series medium
3800 .
3801  This should generate a test.ihx output file, and it should give no warnings
3802  such as not finding the string.h file.
3803  If it cannot find the string.h file, then the problem is that
3804 \series default
3805 SDCC
3806 \series medium
3807  cannot find the /usr/local/share/sdcc/include directory
3808 \series default
3809
3810 \series medium
3811 (see the
3812 \series default
3813 section
3814 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3815
3816 \end_inset
3817
3818 \SpecialChar ~
3819
3820 \series medium
3821 Install trouble-shooting section for suggestions).
3822
3823 \series default
3824  Use option
3825 \series bold
3826 -
3827 \begin_inset ERT
3828 status Collapsed
3829
3830 \layout Standard
3831
3832 \backslash
3833 /
3834 \end_inset
3835
3836 -print-search-dirs
3837 \series default
3838
3839 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3840
3841 \end_inset
3842
3843  to find exactly where SDCC is looking for the include and lib files.
3844 \layout Section
3845
3846 Install Trouble-shooting
3847 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3848
3849 \end_inset
3850
3851
3852 \begin_inset LatexCommand \index{Install trouble-shooting}
3853
3854 \end_inset
3855
3856
3857 \layout Subsection
3858
3859 If SDCC does not build correctly
3860 \layout Standard
3861
3862 A thing to try is starting from scratch by unpacking the .tgz source package
3863  again in an empty directory.
3864  Configure it like:
3865 \newline
3866
3867 \newline
3868
3869 \family sans
3870 \series bold
3871 ./configure 2>&1 | tee configure.log
3872 \family default
3873 \series default
3874
3875 \newline
3876
3877 \newline
3878 and build it like:
3879 \newline
3880
3881 \newline
3882
3883 \family sans
3884 \series bold
3885 make 2>&1 | tee make.log
3886 \family default
3887 \series default
3888
3889 \newline
3890
3891 \newline
3892 If anything goes wrong, you can review the log files to locate the problem.
3893  Or a relevant part of this can be attached to an email that could be helpful
3894  when requesting help from the mailing list.
3895 \layout Subsection
3896
3897 What the
3898 \begin_inset Quotes sld
3899 \end_inset
3900
3901 ./configure
3902 \begin_inset Quotes srd
3903 \end_inset
3904
3905  does
3906 \layout Standard
3907
3908 The
3909 \begin_inset Quotes sld
3910 \end_inset
3911
3912 ./configure
3913 \begin_inset Quotes srd
3914 \end_inset
3915
3916  command is a script that analyzes your system and performs some configuration
3917  to ensure the source package compiles on your system.
3918  It will take a few minutes to run, and will compile a few tests to determine
3919  what compiler features are installed.
3920 \layout Subsection
3921
3922 What the
3923 \begin_inset Quotes sld
3924 \end_inset
3925
3926 make
3927 \begin_inset Quotes srd
3928 \end_inset
3929
3930  does
3931 \layout Standard
3932
3933 This runs the GNU make tool, which automatically compiles all the source
3934  packages into the final installed binary executables.
3935 \layout Subsection
3936
3937 What the
3938 \begin_inset Quotes sld
3939 \end_inset
3940
3941 make install
3942 \begin_inset Quotes erd
3943 \end_inset
3944
3945  command does.
3946 \layout Standard
3947
3948 This will install the compiler, other executables libraries and include
3949  files into the appropriate directories.
3950  See sections
3951 \begin_inset LatexCommand \ref{sub:Install-paths}
3952
3953 \end_inset
3954
3955 ,\SpecialChar ~
3956
3957 \begin_inset LatexCommand \ref{sub:Search-Paths}
3958
3959 \end_inset
3960
3961 \SpecialChar ~
3962 about install and search paths.
3963 \newline
3964 On most systems you will need super-user privileges to do this.
3965 \layout Section
3966
3967 Components of SDCC
3968 \layout Standard
3969
3970 SDCC is not just a compiler, but a collection of tools by various developers.
3971  These include linkers, assemblers, simulators and other components.
3972  Here is a summary of some of the components.
3973  Note that the included simulator and assembler have separate documentation
3974  which you can find in the source package in their respective directories.
3975  As SDCC grows to include support for other processors, other packages from
3976  various developers are included and may have their own sets of documentation.
3977 \newline
3978
3979 \newline
3980 You might want to look at the files which are installed in <installdir>.
3981  At the time of this writing, we find the following programs for gcc-builds:
3982 \newline
3983
3984 \newline
3985 In <installdir>/bin:
3986 \layout Itemize
3987
3988 sdcc - The compiler.
3989 \layout Itemize
3990
3991 sdcpp - The C preprocessor.
3992 \layout Itemize
3993
3994 asx8051 - The assembler for 8051 type processors.
3995 \layout Itemize
3996
3997 as-z80
3998 \series bold
3999 ,
4000 \series default
4001 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4002 \layout Itemize
4003
4004 aslink -The linker for 8051 type processors.
4005 \layout Itemize
4006
4007 link-z80
4008 \series bold
4009 ,
4010 \series default
4011 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4012 \layout Itemize
4013
4014 s51 - The ucSim 8051 simulator.
4015 \layout Itemize
4016
4017 sdcdb - The source debugger.
4018 \layout Itemize
4019
4020 packihx - A tool to pack (compress) Intel hex files.
4021 \layout Standard
4022
4023 In <installdir>/share/sdcc/include
4024 \layout Itemize
4025
4026 the include files
4027 \layout Standard
4028
4029 In <installdir>/share/sdcc/lib
4030 \layout Itemize
4031
4032 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4033  relocatables.
4034 \layout Standard
4035
4036 In <installdir>/share/sdcc/doc
4037 \layout Itemize
4038
4039 the documentation
4040 \layout Standard
4041
4042 As development for other processors proceeds, this list will expand to include
4043  executables to support processors like AVR, PIC, etc.
4044 \layout Subsection
4045
4046 sdcc - The Compiler
4047 \layout Standard
4048
4049 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4050  the assembler and linkage editor.
4051 \layout Subsection
4052
4053 sdcpp - The C-Preprocessor
4054 \layout Standard
4055
4056 The preprocessor
4057 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4058
4059 \end_inset
4060
4061  is a modified version of the GNU preprocessor.
4062  The C preprocessor is used to pull in #include sources, process #ifdef
4063  statements, #defines and so on.
4064 \layout Subsection
4065
4066 as
4067 \emph on
4068 xxxx
4069 \emph default
4070 , aslink, link-
4071 \emph on
4072 xxx
4073 \emph default
4074  - The Assemblers and Linkage Editors
4075 \layout Standard
4076
4077 This is retargettable assembler & linkage editor, it was developed by Alan
4078  Baldwin.
4079  John Hartman created the version for 8051, and I (Sandeep) have made some
4080  enhancements and bug fixes for it to work properly with SDCC.
4081 \layout Subsection
4082
4083 s51 - The Simulator
4084 \layout Standard
4085
4086 S51
4087 \begin_inset LatexCommand \index{s51}
4088
4089 \end_inset
4090
4091  is a freeware, opensource simulator developed by Daniel Drotos (
4092 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
4093
4094 \end_inset
4095
4096 ).
4097  The simulator is built as part of the build process.
4098  For more information visit Daniel's web site at:
4099 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4100
4101 \end_inset
4102
4103 .
4104  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4105  XA51 family.
4106 \layout Subsection
4107
4108 sdcdb - Source Level Debugger
4109 \layout Standard
4110
4111 Sdcdb
4112 \begin_inset LatexCommand \index{sdcdb (debugger)}
4113
4114 \end_inset
4115
4116  is the companion source level debugger.
4117  More about sdcdb in section
4118 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4119
4120 \end_inset
4121
4122 .
4123  The current version of the debugger uses Daniel's Simulator S51
4124 \begin_inset LatexCommand \index{s51}
4125
4126 \end_inset
4127
4128 , but can be easily changed to use other simulators.
4129
4130 \layout Chapter
4131
4132 Using SDCC
4133 \layout Section
4134
4135 Compiling
4136 \layout Subsection
4137
4138 Single Source File Projects
4139 \layout Standard
4140
4141 For single source file 8051 projects the process is very simple.
4142  Compile your programs with the following command
4143 \family sans
4144 \series bold
4145 "sdcc sourcefile.c".
4146
4147 \family default
4148 \series default
4149  This will compile, assemble and link your source file.
4150  Output files are as follows:
4151 \layout Itemize
4152
4153 sourcefile.asm
4154 \begin_inset LatexCommand \index{<file>.asm}
4155
4156 \end_inset
4157
4158  - Assembler source
4159 \begin_inset LatexCommand \index{Assembler source}
4160
4161 \end_inset
4162
4163  file created by the compiler
4164 \layout Itemize
4165
4166 sourcefile.lst
4167 \begin_inset LatexCommand \index{<file>.lst}
4168
4169 \end_inset
4170
4171  - Assembler listing
4172 \begin_inset LatexCommand \index{Assembler listing}
4173
4174 \end_inset
4175
4176  file created by the Assembler
4177 \layout Itemize
4178
4179 sourcefile.rst
4180 \begin_inset LatexCommand \index{<file>.rst}
4181
4182 \end_inset
4183
4184  - Assembler listing
4185 \begin_inset LatexCommand \index{Assembler listing}
4186
4187 \end_inset
4188
4189  file updated with linkedit information, created by linkage editor
4190 \layout Itemize
4191
4192 sourcefile.sym
4193 \begin_inset LatexCommand \index{<file>.sym}
4194
4195 \end_inset
4196
4197  - symbol listing
4198 \begin_inset LatexCommand \index{Symbol listing}
4199
4200 \end_inset
4201
4202  for the sourcefile, created by the assembler
4203 \layout Itemize
4204
4205 sourcefile.rel
4206 \begin_inset LatexCommand \index{<file>.rel}
4207
4208 \end_inset
4209
4210  or sourcefile.o
4211 \begin_inset LatexCommand \index{<file>.o}
4212
4213 \end_inset
4214
4215  - Object file
4216 \begin_inset LatexCommand \index{Object file}
4217
4218 \end_inset
4219
4220  created by the assembler, input to Linkage editor
4221 \layout Itemize
4222
4223 sourcefile.map
4224 \begin_inset LatexCommand \index{<file>.map}
4225
4226 \end_inset
4227
4228  - The memory map
4229 \begin_inset LatexCommand \index{Memory map}
4230
4231 \end_inset
4232
4233  for the load module, created by the Linker
4234 \layout Itemize
4235
4236 sourcefile.mem
4237 \begin_inset LatexCommand \index{<file>.mem}
4238
4239 \end_inset
4240
4241  - A file with a summary of the memory usage
4242 \layout Itemize
4243
4244 sourcefile.ihx
4245 \begin_inset LatexCommand \index{<file>.ihx}
4246
4247 \end_inset
4248
4249  - The load module in Intel hex format
4250 \begin_inset LatexCommand \index{Intel hex format}
4251
4252 \end_inset
4253
4254  (you can select the Motorola S19 format
4255 \begin_inset LatexCommand \index{Motorola S19 format}
4256
4257 \end_inset
4258
4259  with -
4260 \begin_inset ERT
4261 status Collapsed
4262
4263 \layout Standard
4264
4265 \backslash
4266 /
4267 \end_inset
4268
4269 -out-fmt-s19
4270 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4271
4272 \end_inset
4273
4274 .
4275  If you need another format you might want to use
4276 \family sans
4277 \shape italic
4278 objdump
4279 \family default
4280 \shape default
4281
4282 \begin_inset LatexCommand \index{objdump (tool)}
4283
4284 \end_inset
4285
4286  or
4287 \family sans
4288 \shape italic
4289  srecord
4290 \family default
4291 \shape default
4292
4293 \begin_inset LatexCommand \index{srecord (tool)}
4294
4295 \end_inset
4296
4297 ).
4298  Both formats are documented in the documentation of srecord
4299 \begin_inset LatexCommand \index{srecord (tool)}
4300
4301 \end_inset
4302
4303
4304 \layout Itemize
4305
4306 sourcefile.adb
4307 \begin_inset LatexCommand \index{<file>.adb}
4308
4309 \end_inset
4310
4311  - An intermediate file containing debug information needed to create the
4312  .cdb file (with -
4313 \begin_inset ERT
4314 status Open
4315
4316 \layout Standard
4317
4318 \backslash
4319 /
4320 \end_inset
4321
4322 -debug
4323 \begin_inset LatexCommand \index{-\/-debug}
4324
4325 \end_inset
4326
4327 )
4328 \layout Itemize
4329
4330 sourcefile.cdb
4331 \begin_inset LatexCommand \index{<file>.cdb}
4332
4333 \end_inset
4334
4335  - An optional file (with -
4336 \begin_inset ERT
4337 status Collapsed
4338
4339 \layout Standard
4340
4341 \backslash
4342 /
4343 \end_inset
4344
4345 -debug) containing debug information.
4346  The format is documented in cdbfileformat.pdf.
4347 \layout Itemize
4348
4349 sourcefile.
4350  - (no extension)
4351 \begin_inset LatexCommand \index{<file> (no extension)}
4352
4353 \end_inset
4354
4355  An optional AOMF or AOMF51
4356 \begin_inset LatexCommand \index{AOMF, AOMF51}
4357
4358 \end_inset
4359
4360  file containing debug information (generated with option -
4361 \begin_inset ERT
4362 status Collapsed
4363
4364 \layout Standard
4365
4366 \backslash
4367 /
4368 \end_inset
4369
4370 -debug).
4371  The (Intel)
4372 \emph on
4373  a
4374 \emph default
4375 bsolute
4376 \emph on
4377 o
4378 \emph default
4379 bject
4380 \emph on
4381 m
4382 \emph default
4383 odule
4384 \emph on
4385 f
4386 \emph default
4387 ormat is commonly used by third party tools (debuggers
4388 \begin_inset LatexCommand \index{Debugger}
4389
4390 \end_inset
4391
4392 , simulators, emulators)
4393 \layout Itemize
4394
4395 sourcefile.dump*
4396 \begin_inset LatexCommand \index{<file>.dump*}
4397
4398 \end_inset
4399
4400  - Dump file to debug the compiler it self (generated with option -
4401 \begin_inset ERT
4402 status Collapsed
4403
4404 \layout Standard
4405
4406 \backslash
4407 /
4408 \end_inset
4409
4410 -dumpall) (see section
4411 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4412
4413 \end_inset
4414
4415 \SpecialChar ~
4416  and section
4417 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4418
4419 \end_inset
4420
4421 \SpecialChar ~
4422
4423 \begin_inset Quotes sld
4424 \end_inset
4425
4426 Anatomy of the compiler
4427 \begin_inset Quotes srd
4428 \end_inset
4429
4430 ).
4431 \layout Subsection
4432
4433 Projects with Multiple Source Files
4434 \layout Standard
4435
4436 SDCC can compile only ONE file at a time.
4437  Let us for example assume that you have a project containing the following
4438  files:
4439 \newline
4440
4441 \newline
4442 foo1.c (contains some functions)
4443 \newline
4444 foo2.c (contains some more functions)
4445 \newline
4446 foomain.c (contains more functions and the function main)
4447 \newline
4448
4449 \size footnotesize
4450
4451 \newline
4452
4453 \size default
4454 The first two files will need to be compiled separately with the commands:
4455 \size footnotesize
4456
4457 \size default
4458
4459 \newline
4460
4461 \newline
4462
4463 \family sans
4464 \series bold
4465 sdcc\SpecialChar ~
4466 -c\SpecialChar ~
4467 foo1.c
4468 \family default
4469 \series default
4470 \size footnotesize
4471
4472 \newline
4473
4474 \family sans
4475 \series bold
4476 \size default
4477 sdcc\SpecialChar ~
4478 -c\SpecialChar ~
4479 foo2.c
4480 \family default
4481 \series default
4482
4483 \newline
4484
4485 \newline
4486 Then compile the source file containing the
4487 \emph on
4488 main()
4489 \emph default
4490  function and link
4491 \begin_inset LatexCommand \index{Linker}
4492
4493 \end_inset
4494
4495  the files together with the following command:
4496 \newline
4497
4498 \newline
4499
4500 \family sans
4501 \series bold
4502 sdcc\SpecialChar ~
4503 foomain.c\SpecialChar ~
4504 foo1.rel\SpecialChar ~
4505 foo2.rel
4506 \family default
4507 \series default
4508
4509 \begin_inset LatexCommand \index{<file>.rel}
4510
4511 \end_inset
4512
4513
4514 \newline
4515
4516 \newline
4517 Alternatively,
4518 \emph on
4519 foomain.c
4520 \emph default
4521 can be separately compiled as well:
4522 \family sans
4523 \series bold
4524
4525 \newline
4526
4527 \newline
4528 sdcc\SpecialChar ~
4529 -c\SpecialChar ~
4530 foomain.c
4531 \newline
4532 sdcc foomain.rel foo1.rel foo2.rel
4533 \newline
4534
4535 \newline
4536
4537 \family default
4538 \series default
4539 The file containing the
4540 \emph on
4541 main()
4542 \emph default
4543  function
4544 \emph on
4545
4546 \emph default
4547 \noun on
4548 must
4549 \noun default
4550  be the
4551 \noun on
4552 first
4553 \noun default
4554  file specified in the command line, since the linkage editor processes
4555  file in the order they are presented to it.
4556  The linker is invoked from SDCC using a script file with extension .lnk
4557 \begin_inset LatexCommand \index{<file>.lnk}
4558
4559 \end_inset
4560
4561 .
4562  You can view this file to troubleshoot linking problems such as those arising
4563  from missing libraries.
4564 \layout Subsection
4565
4566 Projects with Additional Libraries
4567 \begin_inset LatexCommand \index{Libraries}
4568
4569 \end_inset
4570
4571
4572 \layout Standard
4573
4574 Some reusable routines may be compiled into a library, see the documentation
4575  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4576  for how to create a
4577 \emph on
4578 .lib
4579 \begin_inset LatexCommand \index{<file>.lib}
4580
4581 \end_inset
4582
4583
4584 \emph default
4585  library file.
4586  Libraries created in this manner can be included in the command line.
4587  Make sure you include the -L <library-path> option to tell the linker where
4588  to look for these files if they are not in the current directory.
4589  Here is an example, assuming you have the source file
4590 \emph on
4591 foomain.c
4592 \emph default
4593  and a library
4594 \emph on
4595  foolib.lib
4596 \emph default
4597  in the directory
4598 \emph on
4599 mylib
4600 \emph default
4601  (if that is not the same as your current project):
4602 \newline
4603
4604 \newline
4605
4606 \family sans
4607 \series bold
4608 sdcc foomain.c foolib.lib -L mylib
4609 \newline
4610
4611 \newline
4612
4613 \family default
4614 \series default
4615 Note here that
4616 \emph on
4617  mylib
4618 \emph default
4619  must be an absolute path name.
4620 \newline
4621
4622 \newline
4623 The most efficient way to use libraries is to keep separate modules in separate
4624  source files.
4625  The lib file now should name all the modules.rel
4626 \begin_inset LatexCommand \index{<file>.rel}
4627
4628 \end_inset
4629
4630  files.
4631  For an example see the standard library file
4632 \emph on
4633 libsdcc.lib
4634 \emph default
4635  in the directory <installdir>/share/lib/small.
4636 \layout Subsection
4637
4638 Using sdcclib to Create and Manage Libraries
4639 \begin_inset LatexCommand \index{sdcclib}
4640
4641 \end_inset
4642
4643
4644 \layout Standard
4645
4646 Alternatively, instead of having a .rel file for each entry on the library
4647  file as described in the preceding section, sdcclib can be used to embed
4648  all the modules belonging to such library in the library file itself.
4649  This results in a larger library file, but it greatly reduces the number
4650  of disk files accessed by the linker.
4651   Additionally, the packed library file contains an index of all include
4652  modules and symbols that significantly speeds up the linking process.
4653  To display a list of options supported by sdcclib type:
4654 \newline
4655
4656 \layout Standard
4657
4658
4659 \family sans
4660 \series bold
4661 sdcclib -?
4662 \begin_inset LatexCommand \index{sdcclib}
4663
4664 \end_inset
4665
4666
4667 \newline
4668
4669 \newline
4670
4671 \family default
4672 \series default
4673 To create a new library file, start by compiling all the required modules.
4674  For example:
4675 \newline
4676
4677 \layout Standard
4678
4679
4680 \family sans
4681 \series bold
4682 sdcc -c _divsint.c
4683 \layout Standard
4684
4685
4686 \family sans
4687 \series bold
4688 sdcc -c _divuint.c
4689 \layout Standard
4690
4691
4692 \family sans
4693 \series bold
4694 sdcc -c _modsint.c
4695 \layout Standard
4696
4697
4698 \family sans
4699 \series bold
4700 sdcc -c _moduint.c
4701 \layout Standard
4702
4703
4704 \family sans
4705 \series bold
4706 sdcc -c _mulint.c
4707 \newline
4708
4709 \layout Standard
4710
4711 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4712  and _mulint.rel.
4713  The next step is to add the .rel files to the library file:
4714 \newline
4715
4716 \layout Standard
4717
4718
4719 \family sans
4720 \series bold
4721 sdcclib libint.lib _divsint.rel
4722 \family default
4723
4724 \begin_inset LatexCommand \index{sdcclib}
4725
4726 \end_inset
4727
4728
4729 \layout Standard
4730
4731
4732 \family sans
4733 \series bold
4734 sdcclib libint.lib _divuint.rel
4735 \layout Standard
4736
4737
4738 \family sans
4739 \series bold
4740 sdcclib libint.lib _modsint.rel
4741 \layout Standard
4742
4743
4744 \family sans
4745 \series bold
4746 sdcclib libint.lib _moduint.rel
4747 \layout Standard
4748
4749
4750 \family sans
4751 \series bold
4752 sdcclib libint.lib _mulint.rel
4753 \series default
4754
4755 \newline
4756
4757 \layout Standard
4758
4759 If the file already exists in the library, it will be replaced.
4760  To see what modules and symbols are included in the library, options -s
4761  and -m are available.
4762  For example:
4763 \newline
4764
4765 \newline
4766
4767 \family sans
4768 \series bold
4769 sdcclib -s libint.lib
4770 \family default
4771
4772 \begin_inset LatexCommand \index{sdcclib}
4773
4774 \end_inset
4775
4776
4777 \newline
4778
4779 \family typewriter
4780 \series default
4781 _divsint.rel:
4782 \layout Standard
4783
4784
4785 \family typewriter
4786 __divsint_a_1_1
4787 \layout Standard
4788
4789
4790 \family typewriter
4791 __divsint_PARM_2
4792 \layout Standard
4793
4794
4795 \family typewriter
4796 __divsint
4797 \newline
4798 _divuint.rel:
4799 \layout Standard
4800
4801
4802 \family typewriter
4803 __divuint_a_1_1
4804 \layout Standard
4805
4806
4807 \family typewriter
4808 __divuint_PARM_2
4809 \layout Standard
4810
4811
4812 \family typewriter
4813 __divuint_reste_1_1
4814 \layout Standard
4815
4816
4817 \family typewriter
4818 __divuint_count_1_1
4819 \layout Standard
4820
4821
4822 \family typewriter
4823 __divuint
4824 \newline
4825 _modsint.rel:
4826 \layout Standard
4827
4828
4829 \family typewriter
4830 __modsint_a_1_1
4831 \layout Standard
4832
4833
4834 \family typewriter
4835 __modsint_PARM_2
4836 \layout Standard
4837
4838
4839 \family typewriter
4840 __modsint
4841 \newline
4842 _moduint.rel:
4843 \layout Standard
4844
4845
4846 \family typewriter
4847 __moduint_a_1_1
4848 \layout Standard
4849
4850
4851 \family typewriter
4852 __moduint_PARM_2
4853 \layout Standard
4854
4855
4856 \family typewriter
4857 __moduint_count_1_1
4858 \layout Standard
4859
4860
4861 \family typewriter
4862 __moduint
4863 \newline
4864 _mulint.rel:
4865 \layout Standard
4866
4867
4868 \family typewriter
4869 __mulint_PARM_2
4870 \layout Standard
4871
4872
4873 \family typewriter
4874 __mulint
4875 \family default
4876 \series bold
4877
4878 \newline
4879
4880 \layout Standard
4881
4882 If the source files are compiled using -
4883 \begin_inset ERT
4884 status Open
4885
4886 \layout Standard
4887
4888 \backslash
4889 /
4890 \end_inset
4891
4892 -debug
4893 \begin_inset LatexCommand \index{-\/-debug}
4894
4895 \end_inset
4896
4897 , the corresponding debug information file .adb will be include in the library
4898  file as well.
4899  The library files created with sdcclib are plain text files, so they can
4900  be viewed with a text editor.
4901  It is not recomended to modify a library file created with sdcclib using
4902  a text editor, as there are file indexes numbers located accross the file
4903  used by the linker to quickly locate the required module to link.
4904  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
4905  it can be safely deleted, since all the information required for linking
4906  is embedded in the library file itself.
4907  Library files created using sdcclib are used as described in the preceding
4908  sections.
4909 \layout Section
4910
4911 Command Line Options
4912 \begin_inset LatexCommand \index{Command Line Options}
4913
4914 \end_inset
4915
4916
4917 \layout Subsection
4918
4919 Processor Selection Options
4920 \begin_inset LatexCommand \index{Options processor selection}
4921
4922 \end_inset
4923
4924
4925 \begin_inset LatexCommand \index{Processor selection options}
4926
4927 \end_inset
4928
4929
4930 \layout List
4931 \labelwidthstring 00.00.0000
4932
4933
4934 \series bold
4935 -mmcs51
4936 \begin_inset LatexCommand \index{-mmcs51}
4937
4938 \end_inset
4939
4940
4941 \series default
4942  Generate code for the Intel MCS51
4943 \begin_inset LatexCommand \index{MCS51}
4944
4945 \end_inset
4946
4947  family of processors.
4948  This is the default processor target.
4949 \layout List
4950 \labelwidthstring 00.00.0000
4951
4952
4953 \series bold
4954 -mds390
4955 \begin_inset LatexCommand \index{-mds390}
4956
4957 \end_inset
4958
4959
4960 \series default
4961  Generate code for the Dallas DS80C390
4962 \begin_inset LatexCommand \index{DS80C390}
4963
4964 \end_inset
4965
4966  processor.
4967 \layout List
4968 \labelwidthstring 00.00.0000
4969
4970
4971 \series bold
4972 -mds400
4973 \begin_inset LatexCommand \index{-mds400}
4974
4975 \end_inset
4976
4977
4978 \series default
4979  Generate code for the Dallas DS80C400
4980 \begin_inset LatexCommand \index{DS80C400}
4981
4982 \end_inset
4983
4984  processor.
4985 \layout List
4986 \labelwidthstring 00.00.0000
4987
4988
4989 \series bold
4990 -mhc08
4991 \begin_inset LatexCommand \index{-mhc08}
4992
4993 \end_inset
4994
4995
4996 \series default
4997  Generate code for the Motorola HC08
4998 \begin_inset LatexCommand \index{HC08}
4999
5000 \end_inset
5001
5002  family of processors (added Oct 2003).
5003 \layout List
5004 \labelwidthstring 00.00.0000
5005
5006
5007 \series bold
5008 -mz80
5009 \begin_inset LatexCommand \index{-mz80}
5010
5011 \end_inset
5012
5013
5014 \series default
5015  Generate code for the Zilog Z80
5016 \begin_inset LatexCommand \index{Z80}
5017
5018 \end_inset
5019
5020  family of processors.
5021 \layout List
5022 \labelwidthstring 00.00.0000
5023
5024
5025 \series bold
5026 -mgbz80
5027 \begin_inset LatexCommand \index{-mgbz80}
5028
5029 \end_inset
5030
5031
5032 \series default
5033  Generate code for the GameBoy Z80
5034 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5035
5036 \end_inset
5037
5038  processor (Not actively maintained).
5039 \layout List
5040 \labelwidthstring 00.00.0000
5041
5042
5043 \series bold
5044 -mavr
5045 \begin_inset LatexCommand \index{-mavr}
5046
5047 \end_inset
5048
5049
5050 \series default
5051  Generate code for the Atmel AVR
5052 \begin_inset LatexCommand \index{AVR}
5053
5054 \end_inset
5055
5056  processor (In development, not complete).
5057  AVR users should probably have a look at avr-gcc
5058 \begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
5059
5060 \end_inset
5061
5062  or winavr
5063 \begin_inset LatexCommand \url{http://winavr.sourceforge.net}
5064
5065 \end_inset
5066
5067 .
5068 \layout Comment
5069
5070 I think it is fair to direct users there for now.
5071  Open source is also about avoiding unnecessary work .
5072  But I didn't find the 'official' link.
5073 \layout List
5074 \labelwidthstring 00.00.0000
5075
5076
5077 \series bold
5078 -mpic14
5079 \begin_inset LatexCommand \index{-mpic14}
5080
5081 \end_inset
5082
5083
5084 \series default
5085  Generate code for the Microchip PIC 14
5086 \begin_inset LatexCommand \index{PIC14}
5087
5088 \end_inset
5089
5090 -bit processors (p16f84 and variants.
5091  In development, not complete).
5092 \layout Comment
5093
5094 p16f627 p16f628 p16f84 p16f873 p16f877?
5095 \layout List
5096 \labelwidthstring 00.00.0000
5097
5098
5099 \series bold
5100 -mpic16
5101 \begin_inset LatexCommand \index{-mpic16}
5102
5103 \end_inset
5104
5105
5106 \series default
5107  Generate code for the Microchip PIC 16
5108 \begin_inset LatexCommand \index{PIC16}
5109
5110 \end_inset
5111
5112 -bit processors (p18f452 and variants.
5113  In development, not complete).
5114 \layout List
5115 \labelwidthstring 00.00.0000
5116
5117
5118 \series bold
5119 -mtlcs900h
5120 \series default
5121  Generate code for the Toshiba TLCS-900H
5122 \begin_inset LatexCommand \index{TLCS-900H}
5123
5124 \end_inset
5125
5126  processor (Not maintained, not complete).
5127 \layout List
5128 \labelwidthstring 00.00.0000
5129
5130
5131 \series bold
5132 -mxa51
5133 \begin_inset LatexCommand \index{-mxa51}
5134
5135 \end_inset
5136
5137
5138 \series default
5139  Generate code for the Phillips XA51
5140 \begin_inset LatexCommand \index{XA51}
5141
5142 \end_inset
5143
5144  processor (Not maintained, not complete).
5145 \layout Subsection
5146
5147 Preprocessor Options
5148 \begin_inset LatexCommand \index{Options preprocessor}
5149
5150 \end_inset
5151
5152
5153 \begin_inset LatexCommand \index{Preprocessor options}
5154
5155 \end_inset
5156
5157
5158 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5159
5160 \end_inset
5161
5162
5163 \layout List
5164 \labelwidthstring 00.00.0000
5165
5166
5167 \series bold
5168 -I<path>
5169 \begin_inset LatexCommand \index{-I<path>}
5170
5171 \end_inset
5172
5173
5174 \series default
5175  The additional location where the pre processor will look for <..h> or
5176 \begin_inset Quotes eld
5177 \end_inset
5178
5179 ..h
5180 \begin_inset Quotes erd
5181 \end_inset
5182
5183  files.
5184 \layout List
5185 \labelwidthstring 00.00.0000
5186
5187
5188 \series bold
5189 -D<macro[=value]>
5190 \begin_inset LatexCommand \index{-D<macro[=value]>}
5191
5192 \end_inset
5193
5194
5195 \series default
5196  Command line definition of macros.
5197  Passed to the preprocessor.
5198 \layout List
5199 \labelwidthstring 00.00.0000
5200
5201
5202 \series bold
5203 -M
5204 \begin_inset LatexCommand \index{-M}
5205
5206 \end_inset
5207
5208
5209 \series default
5210  Tell the preprocessor to output a rule suitable for make describing the
5211  dependencies of each object file.
5212  For each source file, the preprocessor outputs one make-rule whose target
5213  is the object file name for that source file and whose dependencies are
5214  all the files `#include'd in it.
5215  This rule may be a single line or may be continued with `
5216 \backslash
5217 '-newline if it is long.
5218  The list of rules is printed on standard output instead of the preprocessed
5219  C program.
5220  `-M' implies `-E
5221 \begin_inset LatexCommand \index{-E}
5222
5223 \end_inset
5224
5225 '.
5226 \layout List
5227 \labelwidthstring 00.00.0000
5228
5229
5230 \series bold
5231 -C
5232 \begin_inset LatexCommand \index{-C}
5233
5234 \end_inset
5235
5236
5237 \series default
5238  Tell the preprocessor not to discard comments.
5239  Used with the `-E' option.
5240 \layout List
5241 \labelwidthstring 00.00.0000
5242
5243
5244 \series bold
5245 -MM
5246 \begin_inset LatexCommand \index{-MM}
5247
5248 \end_inset
5249
5250
5251 \size large
5252 \bar under
5253
5254 \series default
5255 \size default
5256 \bar default
5257 Like `-M' but the output mentions only the user header files included with
5258  `#include
5259 \begin_inset Quotes eld
5260 \end_inset
5261
5262 file"'.
5263  System header files included with `#include <file>' are omitted.
5264 \layout List
5265 \labelwidthstring 00.00.0000
5266
5267
5268 \series bold
5269 -Aquestion(answer)
5270 \begin_inset LatexCommand \index{-Aquestion(answer)}
5271
5272 \end_inset
5273
5274
5275 \series default
5276  Assert the answer answer for question, in case it is tested with a preprocessor
5277  conditional such as `#if #question(answer)'.
5278  `-A-' disables the standard assertions that normally describe the target
5279  machine.
5280 \layout List
5281 \labelwidthstring 00.00.0000
5282
5283
5284 \series bold
5285 -Umacro
5286 \begin_inset LatexCommand \index{-Umacro}
5287
5288 \end_inset
5289
5290
5291 \series default
5292  Undefine macro macro.
5293  `-U' options are evaluated after all `-D' options, but before any `-include'
5294  and `-imacros' options.
5295 \layout List
5296 \labelwidthstring 00.00.0000
5297
5298
5299 \series bold
5300 -dM
5301 \begin_inset LatexCommand \index{-dM}
5302
5303 \end_inset
5304
5305
5306 \series default
5307  Tell the preprocessor to output only a list of the macro definitions that
5308  are in effect at the end of preprocessing.
5309  Used with the `-E' option.
5310 \layout List
5311 \labelwidthstring 00.00.0000
5312
5313
5314 \series bold
5315 -dD
5316 \begin_inset LatexCommand \index{-dD}
5317
5318 \end_inset
5319
5320
5321 \series default
5322  Tell the preprocessor to pass all macro definitions into the output, in
5323  their proper sequence in the rest of the output.
5324 \layout List
5325 \labelwidthstring 00.00.0000
5326
5327
5328 \series bold
5329 -dN
5330 \begin_inset LatexCommand \index{-dN}
5331
5332 \end_inset
5333
5334
5335 \size large
5336 \bar under
5337
5338 \series default
5339 \size default
5340 \bar default
5341 Like `-dD' except that the macro arguments and contents are omitted.
5342  Only `#define name' is included in the output.
5343 \layout List
5344 \labelwidthstring 00.00.0000
5345
5346
5347 \series bold
5348 -Wp\SpecialChar ~
5349 preprocessorOption[,preprocessorOption]
5350 \series default
5351
5352 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5353
5354 \end_inset
5355
5356 ...
5357  Pass the preprocessorOption to the preprocessor
5358 \family typewriter
5359 sdcpp
5360 \family default
5361
5362 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5363
5364 \end_inset
5365
5366 .
5367  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5368  Collection (gcc), if you need more dedicated options please refer to the
5369  documentation at
5370 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5371
5372 \end_inset
5373
5374 .
5375 \layout Subsection
5376
5377 Linker Options
5378 \begin_inset LatexCommand \index{Options linker}
5379
5380 \end_inset
5381
5382
5383 \begin_inset LatexCommand \index{Linker options}
5384
5385 \end_inset
5386
5387
5388 \layout List
5389 \labelwidthstring 00.00.0000
5390
5391
5392 \series bold
5393 -L\SpecialChar ~
5394 -
5395 \series default
5396
5397 \begin_inset ERT
5398 status Collapsed
5399
5400 \layout Standard
5401
5402 \backslash
5403 /
5404 \end_inset
5405
5406
5407 \series bold
5408 -lib-path
5409 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5410
5411 \end_inset
5412
5413
5414 \begin_inset LatexCommand \index{-L -\/-lib-path}
5415
5416 \end_inset
5417
5418
5419 \series default
5420 \SpecialChar ~
5421 <absolute path to additional libraries> This option is passed to the linkage
5422  editor's additional libraries
5423 \begin_inset LatexCommand \index{Libraries}
5424
5425 \end_inset
5426
5427  search path.
5428  The path name must be absolute.
5429  Additional library files may be specified in the command line.
5430  See section Compiling programs for more details.
5431 \layout List
5432 \labelwidthstring 00.00.0000
5433
5434
5435 \series bold
5436 -
5437 \begin_inset ERT
5438 status Collapsed
5439
5440 \layout Standard
5441
5442 \backslash
5443 /
5444 \end_inset
5445
5446 -xram-loc
5447 \series default
5448
5449 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5450
5451 \end_inset
5452
5453 \SpecialChar ~
5454 <Value> The start location of the external ram
5455 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5456
5457 \end_inset
5458
5459 , default value is 0.
5460  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5461 \begin_inset ERT
5462 status Collapsed
5463
5464 \layout Standard
5465
5466 \backslash
5467 /
5468 \end_inset
5469
5470 -xram-loc 0x8000 or -
5471 \begin_inset ERT
5472 status Collapsed
5473
5474 \layout Standard
5475
5476 \backslash
5477 /
5478 \end_inset
5479
5480 -xram-loc 32768.
5481 \layout List
5482 \labelwidthstring 00.00.0000
5483
5484
5485 \series bold
5486 -
5487 \begin_inset ERT
5488 status Collapsed
5489
5490 \layout Standard
5491
5492 \backslash
5493 /
5494 \end_inset
5495
5496 -code-loc
5497 \series default
5498
5499 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5500
5501 \end_inset
5502
5503 \SpecialChar ~
5504 <Value> The start location of the code
5505 \begin_inset LatexCommand \index{code}
5506
5507 \end_inset
5508
5509  segment, default value 0.
5510  Note when this option is used the interrupt vector table is also relocated
5511  to the given address.
5512  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5513 \begin_inset ERT
5514 status Collapsed
5515
5516 \layout Standard
5517
5518 \backslash
5519 /
5520 \end_inset
5521
5522 -code-loc 0x8000 or -
5523 \begin_inset ERT
5524 status Collapsed
5525
5526 \layout Standard
5527
5528 \backslash
5529 /
5530 \end_inset
5531
5532 -code-loc 32768.
5533 \layout List
5534 \labelwidthstring 00.00.0000
5535
5536
5537 \series bold
5538 -
5539 \begin_inset ERT
5540 status Collapsed
5541
5542 \layout Standard
5543
5544 \backslash
5545 /
5546 \end_inset
5547
5548 -stack-loc
5549 \series default
5550
5551 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5552
5553 \end_inset
5554
5555 \SpecialChar ~
5556 <Value> By default the stack
5557 \begin_inset LatexCommand \index{stack}
5558
5559 \end_inset
5560
5561  is placed after the data segment.
5562  Using this option the stack can be placed anywhere in the internal memory
5563  space of the 8051.
5564  The value entered can be in Hexadecimal or Decimal format, e.g.
5565  -
5566 \begin_inset ERT
5567 status Collapsed
5568
5569 \layout Standard
5570
5571 \backslash
5572 /
5573 \end_inset
5574
5575 -stack-loc 0x20 or -
5576 \begin_inset ERT
5577 status Collapsed
5578
5579 \layout Standard
5580
5581 \backslash
5582 /
5583 \end_inset
5584
5585 -stack-loc 32.
5586  Since the sp register is incremented before a push or call, the initial
5587  sp will be set to one byte prior the provided value.
5588  The provided value should not overlap any other memory areas such as used
5589  register banks or the data segment and with enough space for the current
5590  application.
5591 \layout List
5592 \labelwidthstring 00.00.0000
5593
5594
5595 \series bold
5596 -
5597 \begin_inset ERT
5598 status Collapsed
5599
5600 \layout Standard
5601
5602 \backslash
5603 /
5604 \end_inset
5605
5606 -data-loc
5607 \series default
5608
5609 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5610
5611 \end_inset
5612
5613 \SpecialChar ~
5614 <Value> The start location of the internal ram data
5615 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5616
5617 \end_inset
5618
5619  segment.
5620  The value entered can be in Hexadecimal or Decimal format, eg.
5621  -
5622 \begin_inset ERT
5623 status Collapsed
5624
5625 \layout Standard
5626
5627 \backslash
5628 /
5629 \end_inset
5630
5631 -data-loc 0x20 or -
5632 \begin_inset ERT
5633 status Collapsed
5634
5635 \layout Standard
5636
5637 \backslash
5638 /
5639 \end_inset
5640
5641 -data-loc 32.
5642  (By default, the start location of the internal ram data segment  is set
5643  as low as possible in memory, taking into account the used register banks
5644  and the bit segment at address 0x20.
5645  For example if register banks 0 and 1 are used without bit variables, the
5646  data segment will be set, if -
5647 \begin_inset ERT
5648 status Collapsed
5649
5650 \layout Standard
5651
5652 \backslash
5653 /
5654 \end_inset
5655
5656 -data-loc is not used, to location 0x10.)
5657 \layout List
5658 \labelwidthstring 00.00.0000
5659
5660
5661 \series bold
5662 -
5663 \begin_inset ERT
5664 status Collapsed
5665
5666 \layout Standard
5667
5668 \backslash
5669 /
5670 \end_inset
5671
5672 -idata-loc
5673 \series default
5674
5675 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5676
5677 \end_inset
5678
5679 \SpecialChar ~
5680 <Value> The start location of the indirectly addressable internal ram
5681 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5682
5683 \end_inset
5684
5685  of the 8051, default value is 0x80.
5686  The value entered can be in Hexadecimal or Decimal format, eg.
5687  -
5688 \begin_inset ERT
5689 status Collapsed
5690
5691 \layout Standard
5692
5693 \backslash
5694 /
5695 \end_inset
5696
5697 -idata-loc 0x88 or -
5698 \begin_inset ERT
5699 status Collapsed
5700
5701 \layout Standard
5702
5703 \backslash
5704 /
5705 \end_inset
5706
5707 -idata-loc 136.
5708 \layout List
5709 \labelwidthstring 00.00.0000
5710
5711
5712 \series bold
5713 -
5714 \begin_inset ERT
5715 status Collapsed
5716
5717 \layout Standard
5718
5719 \backslash
5720 /
5721 \end_inset
5722
5723 -bit-loc
5724 \series default
5725 \SpecialChar ~
5726 <Value> The start location of the bit
5727 \begin_inset LatexCommand \index{bit}
5728
5729 \end_inset
5730
5731  addressable internal ram of the 8051.
5732  This is
5733 \emph on
5734 not
5735 \emph default
5736  implemented yet.
5737  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5738 -bBSEG=<Value>.
5739 \layout List
5740 \labelwidthstring 00.00.0000
5741
5742
5743 \series bold
5744 -
5745 \begin_inset ERT
5746 status Collapsed
5747
5748 \layout Standard
5749
5750 \backslash
5751 /
5752 \end_inset
5753
5754 -out-fmt-ihx
5755 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5756
5757 \end_inset
5758
5759
5760 \bar under
5761
5762 \series default
5763 \bar default
5764 The linker output (final object code) is in Intel Hex format.
5765 \begin_inset LatexCommand \index{Intel hex format}
5766
5767 \end_inset
5768
5769  This is the default option.
5770  The format itself is documented in the documentation of srecord
5771 \begin_inset LatexCommand \index{srecord (tool)}
5772
5773 \end_inset
5774
5775 .
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 -out-fmt-s19
5792 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5793
5794 \end_inset
5795
5796
5797 \bar under
5798
5799 \series default
5800 \bar default
5801 The linker output (final object code) is in Motorola S19 format
5802 \begin_inset LatexCommand \index{Motorola S19 format}
5803
5804 \end_inset
5805
5806 .
5807  The format itself is documented in the documentation of srecord.
5808 \layout List
5809 \labelwidthstring 00.00.0000
5810
5811
5812 \series bold
5813 -Wl\SpecialChar ~
5814 linkOption[,linkOption]
5815 \series default
5816
5817 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5818
5819 \end_inset
5820
5821 ...
5822  Pass the linkOption to the linker.
5823  See file sdcc/as/doc/asxhtm.html for more on linker options.
5824 \layout Subsection
5825
5826 MCS51 Options
5827 \begin_inset LatexCommand \index{Options MCS51}
5828
5829 \end_inset
5830
5831
5832 \begin_inset LatexCommand \index{MCS51 options}
5833
5834 \end_inset
5835
5836
5837 \layout List
5838 \labelwidthstring 00.00.0000
5839
5840
5841 \series bold
5842 -
5843 \begin_inset ERT
5844 status Collapsed
5845
5846 \layout Standard
5847
5848 \backslash
5849 /
5850 \end_inset
5851
5852 -model-small
5853 \begin_inset LatexCommand \index{-\/-model-small}
5854
5855 \end_inset
5856
5857
5858 \series default
5859 \size large
5860 \emph on
5861
5862 \size default
5863 \emph default
5864 Generate code for Small Model programs, see section Memory Models for more
5865  details.
5866  This is the default model.
5867 \layout List
5868 \labelwidthstring 00.00.0000
5869
5870
5871 \series bold
5872 -
5873 \begin_inset ERT
5874 status Collapsed
5875
5876 \layout Standard
5877
5878 \backslash
5879 /
5880 \end_inset
5881
5882 -model-large
5883 \begin_inset LatexCommand \index{-\/-model-large}
5884
5885 \end_inset
5886
5887
5888 \series default
5889  Generate code for Large model programs, see section Memory Models for more
5890  details.
5891  If this option is used all source files in the project have to be compiled
5892  with this option.
5893 \layout List
5894 \labelwidthstring 00.00.0000
5895
5896
5897 \series bold
5898 -
5899 \begin_inset ERT
5900 status Collapsed
5901
5902 \layout Standard
5903
5904 \backslash
5905 /
5906 \end_inset
5907
5908 -xstack
5909 \begin_inset LatexCommand \index{-\/-xstack}
5910
5911 \end_inset
5912
5913
5914 \series default
5915  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5916  variables and passing parameters.
5917  See section
5918 \begin_inset LatexCommand \ref{sub:External-Stack}
5919
5920 \end_inset
5921
5922 \SpecialChar ~
5923  External Stack for more details.
5924 \layout List
5925 \labelwidthstring 00.00.0000
5926
5927
5928 \series bold
5929 -
5930 \begin_inset ERT
5931 status Collapsed
5932
5933 \layout Standard
5934
5935 \backslash
5936 /
5937 \end_inset
5938
5939 -iram-size
5940 \series default
5941 \SpecialChar ~
5942 <Value>
5943 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
5944
5945 \end_inset
5946
5947  Causes the linker to check if the internal ram usage is within limits of
5948  the given value.
5949 \layout List
5950 \labelwidthstring 00.00.0000
5951
5952
5953 \series bold
5954 -
5955 \begin_inset ERT
5956 status Collapsed
5957
5958 \layout Standard
5959
5960 \backslash
5961 /
5962 \end_inset
5963
5964 -xram-size
5965 \series default
5966 \SpecialChar ~
5967 <Value>
5968 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
5969
5970 \end_inset
5971
5972  Causes the linker to check if the external ram usage is within limits of
5973  the given value.
5974 \layout List
5975 \labelwidthstring 00.00.0000
5976
5977
5978 \series bold
5979 -
5980 \begin_inset ERT
5981 status Collapsed
5982
5983 \layout Standard
5984
5985 \backslash
5986 /
5987 \end_inset
5988
5989 -code-size
5990 \series default
5991 \SpecialChar ~
5992 <Value>
5993 \begin_inset LatexCommand \index{-\/-code-size <Value>}
5994
5995 \end_inset
5996
5997  Causes the linker to check if the code memory usage is within limits of
5998  the given value.
5999 \layout List
6000 \labelwidthstring 00.00.0000
6001
6002
6003 \series bold
6004 -
6005 \begin_inset ERT
6006 status Collapsed
6007
6008 \layout Standard
6009
6010 \backslash
6011 /
6012 \end_inset
6013
6014 -stack-size
6015 \series default
6016 \SpecialChar ~
6017 <Value>
6018 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6019
6020 \end_inset
6021
6022  Causes the linker to check if there is at minimum <Value> bytes for stack.
6023 \layout List
6024 \labelwidthstring 00.00.0000
6025
6026
6027 \series bold
6028 -
6029 \begin_inset ERT
6030 status Collapsed
6031
6032 \layout Standard
6033
6034 \backslash
6035 /
6036 \end_inset
6037
6038 -pack-iram
6039 \series default
6040 \SpecialChar ~
6041
6042 \begin_inset LatexCommand \index{-\/-pack-iram}
6043
6044 \end_inset
6045
6046  Causes the linker to use unused register banks for data variables and pack
6047  data, idata and stack together.
6048  This is the default now.
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 -no-pack-iram
6065 \series default
6066 \SpecialChar ~
6067
6068 \begin_inset LatexCommand \index{-\/-pack-iram}
6069
6070 \end_inset
6071
6072  Causes the linker to use old style for allocating memory areas.
6073 \layout Subsection
6074
6075 DS390 / DS400 Options
6076 \begin_inset LatexCommand \index{Options DS390}
6077
6078 \end_inset
6079
6080
6081 \begin_inset LatexCommand \index{DS390 options}
6082
6083 \end_inset
6084
6085
6086 \layout List
6087 \labelwidthstring 00.00.0000
6088
6089
6090 \series bold
6091 -
6092 \begin_inset ERT
6093 status Collapsed
6094
6095 \layout Standard
6096
6097 \backslash
6098 /
6099 \end_inset
6100
6101 -model-flat24
6102 \series default
6103
6104 \begin_inset LatexCommand \index{-\/-model-flat24}
6105
6106 \end_inset
6107
6108
6109 \size large
6110 \emph on
6111
6112 \size default
6113 \emph default
6114 Generate 24-bit flat mode code.
6115  This is the one and only that the ds390 code generator supports right now
6116  and is default when using
6117 \emph on
6118 -mds390
6119 \emph default
6120 .
6121  See section Memory Models for more details.
6122 \layout List
6123 \labelwidthstring 00.00.0000
6124
6125
6126 \series bold
6127 -
6128 \begin_inset ERT
6129 status Collapsed
6130
6131 \layout Standard
6132
6133 \backslash
6134 /
6135 \end_inset
6136
6137 -protect-sp-update
6138 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6139
6140 \end_inset
6141
6142
6143 \series default
6144  disable interrupts during ESP:SP updates.
6145 \layout List
6146 \labelwidthstring 00.00.0000
6147
6148
6149 \series bold
6150 -
6151 \begin_inset ERT
6152 status Collapsed
6153
6154 \layout Standard
6155
6156 \backslash
6157 /
6158 \end_inset
6159
6160 -stack-10bit
6161 \series default
6162
6163 \begin_inset LatexCommand \index{-\/-stack-10bit}
6164
6165 \end_inset
6166
6167  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6168  This is the one and only that the ds390 code generator supports right now
6169  and is default when using
6170 \emph on
6171 -mds390
6172 \emph default
6173 .
6174  In this mode, the stack is located in the lower 1K of the internal RAM,
6175  which is mapped to 0x400000.
6176  Note that the support is incomplete, since it still uses a single byte
6177  as the stack pointer.
6178  This means that only the lower 256 bytes of the potential 1K stack space
6179  will actually be used.
6180  However, this does allow you to reclaim the precious 256 bytes of low RAM
6181  for use for the DATA and IDATA segments.
6182  The compiler will not generate any code to put the processor into 10 bit
6183  stack mode.
6184  It is important to ensure that the processor is in this mode before calling
6185  any re-entrant functions compiled with this option.
6186  In principle, this should work with the
6187 \emph on
6188 -
6189 \begin_inset ERT
6190 status Collapsed
6191
6192 \layout Standard
6193
6194 \backslash
6195 /
6196 \end_inset
6197
6198 -stack-auto
6199 \begin_inset LatexCommand \index{-\/-stack-auto}
6200
6201 \end_inset
6202
6203
6204 \emph default
6205  option, but that has not been tested.
6206  It is incompatible with the
6207 \emph on
6208 -
6209 \begin_inset ERT
6210 status Collapsed
6211
6212 \layout Standard
6213
6214 \backslash
6215 /
6216 \end_inset
6217
6218 -xstack
6219 \begin_inset LatexCommand \index{-\/-xstack}
6220
6221 \end_inset
6222
6223
6224 \emph default
6225  option.
6226  It also only makes sense if the processor is in 24 bit contiguous addressing
6227  mode (see the
6228 \emph on
6229 -
6230 \begin_inset ERT
6231 status Collapsed
6232
6233 \layout Standard
6234
6235 \backslash
6236 /
6237 \end_inset
6238
6239 -model-flat24 option
6240 \emph default
6241 ).
6242 \layout List
6243 \labelwidthstring 00.00.0000
6244
6245
6246 \series bold
6247 -
6248 \begin_inset ERT
6249 status Collapsed
6250
6251 \layout Standard
6252
6253 \backslash
6254 /
6255 \end_inset
6256
6257 -stack-probe
6258 \begin_inset LatexCommand \index{-\/-stack-probe}
6259
6260 \end_inset
6261
6262
6263 \series default
6264  insert call to function __stack_probe at each function prologue.
6265 \layout List
6266 \labelwidthstring 00.00.0000
6267
6268
6269 \series bold
6270 -
6271 \begin_inset ERT
6272 status Collapsed
6273
6274 \layout Standard
6275
6276 \backslash
6277 /
6278 \end_inset
6279
6280 -tini-libid
6281 \begin_inset LatexCommand \index{-\/-tini-libid}
6282
6283 \end_inset
6284
6285
6286 \series default
6287  <nnnn> LibraryID used in -mTININative.
6288
6289 \layout List
6290 \labelwidthstring 00.00.0000
6291
6292
6293 \series bold
6294 -
6295 \begin_inset ERT
6296 status Collapsed
6297
6298 \layout Standard
6299
6300 \backslash
6301 /
6302 \end_inset
6303
6304 -use-accelerator
6305 \begin_inset LatexCommand \index{-\/-use-accelerator}
6306
6307 \end_inset
6308
6309
6310 \series default
6311  generate code for DS390 Arithmetic Accelerator.
6312
6313 \layout Subsection
6314
6315 Z80 Options
6316 \begin_inset LatexCommand \index{Options Z80}
6317
6318 \end_inset
6319
6320
6321 \begin_inset LatexCommand \index{Z80 options}
6322
6323 \end_inset
6324
6325
6326 \layout List
6327 \labelwidthstring 00.00.0000
6328
6329
6330 \series bold
6331 -
6332 \begin_inset ERT
6333 status Collapsed
6334
6335 \layout Standard
6336
6337 \backslash
6338 /
6339 \end_inset
6340
6341 -callee-saves-bc
6342 \series default
6343
6344 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6345
6346 \end_inset
6347
6348
6349 \size large
6350 \emph on
6351
6352 \size default
6353 \emph default
6354 Force a called function to always save BC.
6355 \layout List
6356 \labelwidthstring 00.00.0000
6357
6358
6359 \series bold
6360 -
6361 \begin_inset ERT
6362 status Collapsed
6363
6364 \layout Standard
6365
6366 \backslash
6367 /
6368 \end_inset
6369
6370 -no-std-crt0
6371 \series default
6372
6373 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6374
6375 \end_inset
6376
6377  When linking, skip the standard crt0.o object file.
6378  You must provide your own crt0.o for your system when linking.
6379
6380 \layout Subsection
6381
6382 Optimization Options
6383 \begin_inset LatexCommand \index{Options optimization}
6384
6385 \end_inset
6386
6387
6388 \begin_inset LatexCommand \index{Optimization options}
6389
6390 \end_inset
6391
6392
6393 \layout List
6394 \labelwidthstring 00.00.0000
6395
6396
6397 \series bold
6398 -
6399 \begin_inset ERT
6400 status Collapsed
6401
6402 \layout Standard
6403
6404 \backslash
6405 /
6406 \end_inset
6407
6408 -nogcse
6409 \begin_inset LatexCommand \index{-\/-nogcse}
6410
6411 \end_inset
6412
6413
6414 \series default
6415  Will not do global subexpression elimination, this option may be used when
6416  the compiler creates undesirably large stack/data spaces to store compiler
6417  temporaries.
6418  A warning message will be generated when this happens and the compiler
6419  will indicate the number of extra bytes it allocated.
6420  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6421 nogcse
6422 \begin_inset LatexCommand \index{\#pragma nogcse}
6423
6424 \end_inset
6425
6426  can be used to turn off global subexpression elimination
6427 \begin_inset LatexCommand \index{Subexpression elimination}
6428
6429 \end_inset
6430
6431  for a given function only.
6432 \layout List
6433 \labelwidthstring 00.00.0000
6434
6435
6436 \series bold
6437 -
6438 \begin_inset ERT
6439 status Collapsed
6440
6441 \layout Standard
6442
6443 \backslash
6444 /
6445 \end_inset
6446
6447 -noinvariant
6448 \begin_inset LatexCommand \index{-\/-noinvariant}
6449
6450 \end_inset
6451
6452
6453 \series default
6454  Will not do loop invariant optimizations, this may be turned off for reasons
6455  explained for the previous option.
6456  For more details of loop optimizations performed see Loop Invariants in
6457  section
6458 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6459
6460 \end_inset
6461
6462 .
6463  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6464 noinvariant
6465 \begin_inset LatexCommand \index{\#pragma noinvariant}
6466
6467 \end_inset
6468
6469  can be used to turn off invariant optimizations for a given function only.
6470 \layout List
6471 \labelwidthstring 00.00.0000
6472
6473
6474 \series bold
6475 -
6476 \begin_inset ERT
6477 status Collapsed
6478
6479 \layout Standard
6480
6481 \backslash
6482 /
6483 \end_inset
6484
6485 -noinduction
6486 \begin_inset LatexCommand \index{-\/-noinduction}
6487
6488 \end_inset
6489
6490
6491 \series default
6492  Will not do loop induction optimizations, see section strength reduction
6493  for more details.
6494  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6495 noinduction
6496 \begin_inset LatexCommand \index{\#pragma noinduction}
6497
6498 \end_inset
6499
6500  can be used to turn off induction optimizations for a given function only.
6501 \layout List
6502 \labelwidthstring 00.00.0000
6503
6504
6505 \series bold
6506 -
6507 \begin_inset ERT
6508 status Collapsed
6509
6510 \layout Standard
6511
6512 \backslash
6513 /
6514 \end_inset
6515
6516 -nojtbound
6517 \begin_inset LatexCommand \index{-\/-nojtbound}
6518
6519 \end_inset
6520
6521
6522 \size large
6523 \bar under
6524
6525 \series default
6526 \size default
6527 \bar default
6528  Will not generate boundary condition check when switch statements
6529 \begin_inset LatexCommand \index{switch statement}
6530
6531 \end_inset
6532
6533  are implemented using jump-tables.
6534  See section
6535 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6536
6537 \end_inset
6538
6539 \SpecialChar ~
6540 Switch Statements for more details.
6541  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6542 nojtbound
6543 \begin_inset LatexCommand \index{\#pragma nojtbound}
6544
6545 \end_inset
6546
6547  can be used to turn off boundary checking for jump tables for a given function
6548  only.
6549 \layout List
6550 \labelwidthstring 00.00.0000
6551
6552
6553 \series bold
6554 -
6555 \begin_inset ERT
6556 status Collapsed
6557
6558 \layout Standard
6559
6560 \backslash
6561 /
6562 \end_inset
6563
6564 -noloopreverse
6565 \begin_inset LatexCommand \index{-\/-noloopreverse}
6566
6567 \end_inset
6568
6569
6570 \series default
6571 \size large
6572
6573 \size default
6574 Will not do loop reversal
6575 \begin_inset LatexCommand \index{Loop reversing}
6576
6577 \end_inset
6578
6579 optimization.
6580 \layout List
6581 \labelwidthstring 00.00.0000
6582
6583 -
6584 \begin_inset ERT
6585 status Collapsed
6586
6587 \layout Standard
6588
6589 \backslash
6590 /
6591 \end_inset
6592
6593 -
6594 \series bold
6595 nolabelopt
6596 \series default
6597
6598 \begin_inset LatexCommand \index{-\/-nolabelopt }
6599
6600 \end_inset
6601
6602 Will not optimize labels (makes the dumpfiles more readable).
6603 \layout List
6604 \labelwidthstring 00.00.0000
6605
6606
6607 \series bold
6608 -
6609 \begin_inset ERT
6610 status Collapsed
6611
6612 \layout Standard
6613
6614 \backslash
6615 /
6616 \end_inset
6617
6618 -no-xinit-opt
6619 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6620
6621 \end_inset
6622
6623
6624 \series default
6625  Will not memcpy initialized data from code space into xdata space.
6626  This saves a few bytes in code space if you don't have initialized data.
6627 \layout List
6628 \labelwidthstring 00.00.0000
6629
6630
6631 \series bold
6632 -
6633 \begin_inset ERT
6634 status Collapsed
6635
6636 \layout Standard
6637
6638 \backslash
6639 /
6640 \end_inset
6641
6642 -nooverlay
6643 \begin_inset LatexCommand \index{-\/-nooverlay}
6644
6645 \end_inset
6646
6647
6648 \series default
6649   The compiler will not overlay parameters and local variables of any function,
6650  see section Parameters and local variables for more details.
6651 \layout List
6652 \labelwidthstring 00.00.0000
6653
6654
6655 \series bold
6656 -
6657 \begin_inset ERT
6658 status Collapsed
6659
6660 \layout Standard
6661
6662 \backslash
6663 /
6664 \end_inset
6665
6666 -no-peep
6667 \begin_inset LatexCommand \index{-\/-no-peep}
6668
6669 \end_inset
6670
6671
6672 \series default
6673  Disable peep-hole optimization.
6674 \layout List
6675 \labelwidthstring 00.00.0000
6676
6677
6678 \series bold
6679 -
6680 \begin_inset ERT
6681 status Collapsed
6682
6683 \layout Standard
6684
6685 \backslash
6686 /
6687 \end_inset
6688
6689 -peep-file
6690 \series default
6691
6692 \begin_inset LatexCommand \index{-\/-peep-file}
6693
6694 \end_inset
6695
6696 \SpecialChar ~
6697 <filename> This option can be used to use additional rules to be used by
6698  the peep hole optimizer.
6699  See section
6700 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6701
6702 \end_inset
6703
6704 \SpecialChar ~
6705 Peep Hole optimizations for details on how to write these rules.
6706 \layout List
6707 \labelwidthstring 00.00.0000
6708
6709
6710 \series bold
6711 -
6712 \begin_inset ERT
6713 status Collapsed
6714
6715 \layout Standard
6716
6717 \backslash
6718 /
6719 \end_inset
6720
6721 -peep-asm
6722 \begin_inset LatexCommand \index{-\/-peep-asm}
6723
6724 \end_inset
6725
6726
6727 \series default
6728  Pass the inline assembler code through the peep hole optimizer.
6729  This can cause unexpected changes to inline assembler code, please go through
6730  the peephole optimizer
6731 \begin_inset LatexCommand \index{Peephole optimizer}
6732
6733 \end_inset
6734
6735  rules defined in the source file tree '<target>/peeph.def' before using
6736  this option.
6737 \layout List
6738 \labelwidthstring 00.00.0000
6739
6740
6741 \series bold
6742 -
6743 \begin_inset ERT
6744 status Collapsed
6745
6746 \layout Standard
6747
6748 \backslash
6749 /
6750 \end_inset
6751
6752 -opt-code-speed
6753 \begin_inset LatexCommand \index{-\/-opt-code-speed}
6754
6755 \end_inset
6756
6757
6758 \series default
6759  The compiler will optimize code generation towards fast code, possibly
6760  at the expense of code size.
6761 \layout List
6762 \labelwidthstring 00.00.0000
6763
6764
6765 \series bold
6766 -
6767 \begin_inset ERT
6768 status Collapsed
6769
6770 \layout Standard
6771
6772 \backslash
6773 /
6774 \end_inset
6775
6776 -opt-code-size
6777 \begin_inset LatexCommand \index{-\/-opt-code-size}
6778
6779 \end_inset
6780
6781
6782 \series default
6783  The compiler will optimize code generation towards compact code, possibly
6784  at the expense of code speed.
6785 \layout Subsection
6786
6787 Other Options
6788 \begin_inset LatexCommand \index{Options other}
6789
6790 \end_inset
6791
6792
6793 \layout List
6794 \labelwidthstring 00.00.0000
6795
6796
6797 \series bold
6798 -c\SpecialChar ~
6799 -
6800 \begin_inset ERT
6801 status Collapsed
6802
6803 \layout Standard
6804
6805 \backslash
6806 /
6807 \end_inset
6808
6809 -compile-only
6810 \begin_inset LatexCommand \index{-\/-compile-only}
6811
6812 \end_inset
6813
6814
6815 \begin_inset LatexCommand \index{-c -\/-compile-only}
6816
6817 \end_inset
6818
6819
6820 \series default
6821  will compile and assemble the source, but will not call the linkage editor.
6822 \layout List
6823 \labelwidthstring 00.00.0000
6824
6825
6826 \series bold
6827 -
6828 \series default
6829
6830 \begin_inset ERT
6831 status Collapsed
6832
6833 \layout Standard
6834
6835 \backslash
6836 /
6837 \end_inset
6838
6839
6840 \series bold
6841 -c1mode
6842 \begin_inset LatexCommand \index{-\/-c1mode}
6843
6844 \end_inset
6845
6846
6847 \series default
6848  reads the preprocessed source from standard input and compiles it.
6849  The file name for the assembler output must be specified using the -o option.
6850 \layout List
6851 \labelwidthstring 00.00.0000
6852
6853
6854 \series bold
6855 -E
6856 \begin_inset LatexCommand \index{-E}
6857
6858 \end_inset
6859
6860
6861 \series default
6862  Run only the C preprocessor.
6863  Preprocess all the C source files specified and output the results to standard
6864  output.
6865 \layout List
6866 \labelwidthstring 00.00.0000
6867
6868
6869 \series bold
6870 -o\SpecialChar ~
6871 <path/file>
6872 \begin_inset LatexCommand \index{-o <path/file>}
6873
6874 \end_inset
6875
6876
6877 \series default
6878 The output path resp.
6879  file where everything will be placed.
6880  If the parameter is a path, it must have a trailing slash (or backslash
6881  for the Windows binaries) to be recognized as a path.
6882
6883 \layout List
6884 \labelwidthstring 00.00.0000
6885
6886
6887 \series bold
6888 -
6889 \begin_inset ERT
6890 status Collapsed
6891
6892 \layout Standard
6893
6894 \backslash
6895 /
6896 \end_inset
6897
6898 -stack-auto
6899 \begin_inset LatexCommand \index{-\/-stack-auto}
6900
6901 \end_inset
6902
6903
6904 \series default
6905 \size large
6906 \emph on
6907
6908 \size default
6909 \emph default
6910 All functions in the source file will be compiled as
6911 \emph on
6912 reentrant
6913 \emph default
6914
6915 \begin_inset LatexCommand \index{reentrant}
6916
6917 \end_inset
6918
6919 , i.e.
6920  the parameters and local variables will be allocated on the stack
6921 \begin_inset LatexCommand \index{stack}
6922
6923 \end_inset
6924
6925 .
6926  See section
6927 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
6928
6929 \end_inset
6930
6931  Parameters and Local Variables for more details.
6932  If this option is used all source files in the project should be compiled
6933  with this option.
6934  It automatically implies --int-long-reent and --float-reent.
6935
6936 \layout List
6937 \labelwidthstring 00.00.0000
6938
6939
6940 \series bold
6941 -
6942 \begin_inset ERT
6943 status Collapsed
6944
6945 \layout Standard
6946
6947 \backslash
6948 /
6949 \end_inset
6950
6951 -callee-saves
6952 \begin_inset LatexCommand \index{-\/-callee-saves}
6953
6954 \end_inset
6955
6956  function1[,function2][,function3]....
6957
6958 \series default
6959  The compiler by default uses a caller saves convention for register saving
6960  across function calls, however this can cause unnecessary register pushing
6961  & popping when calling small functions from larger functions.
6962  This option can be used to switch the register saving convention for the
6963  function names specified.
6964  The compiler will not save registers when calling these functions, no extra
6965  code will be generated at the entry & exit (function prologue
6966 \series bold
6967
6968 \begin_inset LatexCommand \index{function prologue}
6969
6970 \end_inset
6971
6972
6973 \series default
6974  & epilogue
6975 \series bold
6976
6977 \begin_inset LatexCommand \index{function epilogue}
6978
6979 \end_inset
6980
6981
6982 \series default
6983 ) for these functions to save & restore the registers used by these functions,
6984  this can SUBSTANTIALLY reduce code & improve run time performance of the
6985  generated code.
6986  In the future the compiler (with inter procedural analysis) will be able
6987  to determine the appropriate scheme to use for each function call.
6988  DO NOT use this option for built-in functions such as _mulint..., if this
6989  option is used for a library function the appropriate library function
6990  needs to be recompiled with the same option.
6991  If the project consists of multiple source files then all the source file
6992  should be compiled with the same -
6993 \begin_inset ERT
6994 status Collapsed
6995
6996 \layout Standard
6997
6998 \backslash
6999 /
7000 \end_inset
7001
7002 -callee-saves option string.
7003  Also see #pragma\SpecialChar ~
7004 callee_saves
7005 \begin_inset LatexCommand \index{\#pragma callee\_saves}
7006
7007 \end_inset
7008
7009 .
7010 \layout List
7011 \labelwidthstring 00.00.0000
7012
7013
7014 \series bold
7015 -
7016 \begin_inset ERT
7017 status Collapsed
7018
7019 \layout Standard
7020
7021 \backslash
7022 /
7023 \end_inset
7024
7025 -debug
7026 \begin_inset LatexCommand \index{-\/-debug}
7027
7028 \end_inset
7029
7030
7031 \bar under
7032
7033 \series default
7034 \bar default
7035 When this option is used the compiler will generate debug information.
7036  The debug information collected in a file with .cdb extension can be used
7037  with the SDCDB.
7038  For more information see documentation for SDCDB.
7039  Another file with no extension contains debug information in AOMF or AOMF51
7040 \begin_inset LatexCommand \index{AOMF, AOMF51}
7041
7042 \end_inset
7043
7044  format which is commonly used by third party tools.
7045 \layout List
7046 \labelwidthstring 00.00.0000
7047
7048
7049 \series bold
7050 -S
7051 \begin_inset LatexCommand \index{-S}
7052
7053 \end_inset
7054
7055
7056 \size large
7057 \bar under
7058
7059 \series default
7060 \size default
7061 \bar default
7062 Stop after the stage of compilation proper; do not assemble.
7063  The output is an assembler code file for the input file specified.
7064 \layout List
7065 \labelwidthstring 00.00.0000
7066
7067
7068 \series bold
7069 -
7070 \begin_inset ERT
7071 status Collapsed
7072
7073 \layout Standard
7074
7075 \backslash
7076 /
7077 \end_inset
7078
7079 -int-long-reent
7080 \begin_inset LatexCommand \index{-\/-int-long-reent}
7081
7082 \end_inset
7083
7084
7085 \series default
7086  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7087  Note by default these libraries are compiled as non-reentrant.
7088  See section Installation for more details.
7089 \layout List
7090 \labelwidthstring 00.00.0000
7091
7092
7093 \series bold
7094 -
7095 \begin_inset ERT
7096 status Collapsed
7097
7098 \layout Standard
7099
7100 \backslash
7101 /
7102 \end_inset
7103
7104 -cyclomatic
7105 \begin_inset LatexCommand \index{-\/-cyclomatic}
7106
7107 \end_inset
7108
7109
7110 \bar under
7111
7112 \series default
7113 \bar default
7114 This option will cause the compiler to generate an information message for
7115  each function in the source file.
7116  The message contains some
7117 \emph on
7118 important
7119 \emph default
7120  information about the function.
7121  The number of edges and nodes the compiler detected in the control flow
7122  graph of the function, and most importantly the
7123 \emph on
7124 cyclomatic complexity
7125 \begin_inset LatexCommand \index{Cyclomatic complexity}
7126
7127 \end_inset
7128
7129
7130 \emph default
7131  see section on Cyclomatic Complexity for more details.
7132 \layout List
7133 \labelwidthstring 00.00.0000
7134
7135
7136 \series bold
7137 -
7138 \begin_inset ERT
7139 status Collapsed
7140
7141 \layout Standard
7142
7143 \backslash
7144 /
7145 \end_inset
7146
7147 -float-reent
7148 \begin_inset LatexCommand \index{-\/-float-reent}
7149
7150 \end_inset
7151
7152
7153 \series default
7154  Floating point library is compiled as reentrant
7155 \begin_inset LatexCommand \index{reentrant}
7156
7157 \end_inset
7158
7159 .
7160  See section Installation for more details.
7161 \layout List
7162 \labelwidthstring 00.00.0000
7163
7164
7165 \series bold
7166 -
7167 \begin_inset ERT
7168 status Collapsed
7169
7170 \layout Standard
7171
7172 \backslash
7173 /
7174 \end_inset
7175
7176 -main-return
7177 \begin_inset LatexCommand \index{-\/-main-return}
7178
7179 \end_inset
7180
7181
7182 \series default
7183  This option can be used if the code generated is called by a monitor program
7184  or if the main routine includes an endless loop.
7185  This option might result in slightly smaller code and save two bytes of
7186  stack space.
7187  The return from the 'main'
7188 \begin_inset LatexCommand \index{main return}
7189
7190 \end_inset
7191
7192  function will return to the function calling main.
7193  The default setting is to lock up i.e.
7194  generate a '
7195 \family typewriter
7196 sjmp .
7197 \family default
7198 '.
7199 \layout List
7200 \labelwidthstring 00.00.0000
7201
7202
7203 \series bold
7204 -
7205 \begin_inset ERT
7206 status Collapsed
7207
7208 \layout Standard
7209
7210 \backslash
7211 /
7212 \end_inset
7213
7214 -nostdinc
7215 \begin_inset LatexCommand \index{-\/-nostdinc}
7216
7217 \end_inset
7218
7219
7220 \series default
7221  This will prevent the compiler from passing on the default include path
7222  to the preprocessor.
7223 \layout List
7224 \labelwidthstring 00.00.0000
7225
7226
7227 \series bold
7228 -
7229 \begin_inset ERT
7230 status Collapsed
7231
7232 \layout Standard
7233
7234 \backslash
7235 /
7236 \end_inset
7237
7238 -nostdlib
7239 \begin_inset LatexCommand \index{-\/-nostdlib}
7240
7241 \end_inset
7242
7243
7244 \series default
7245  This will prevent the compiler from passing on the default library
7246 \begin_inset LatexCommand \index{Libraries}
7247
7248 \end_inset
7249
7250  path to the linker.
7251 \layout List
7252 \labelwidthstring 00.00.0000
7253
7254
7255 \series bold
7256 -
7257 \begin_inset ERT
7258 status Collapsed
7259
7260 \layout Standard
7261
7262 \backslash
7263 /
7264 \end_inset
7265
7266 -verbose
7267 \begin_inset LatexCommand \index{-\/-verbose}
7268
7269 \end_inset
7270
7271
7272 \series default
7273  Shows the various actions the compiler is performing.
7274 \layout List
7275 \labelwidthstring 00.00.0000
7276
7277
7278 \series bold
7279 -V
7280 \begin_inset LatexCommand \index{-V}
7281
7282 \end_inset
7283
7284
7285 \series default
7286  Shows the actual commands the compiler is executing.
7287 \layout List
7288 \labelwidthstring 00.00.0000
7289
7290
7291 \series bold
7292 -
7293 \begin_inset ERT
7294 status Collapsed
7295
7296 \layout Standard
7297
7298 \backslash
7299 /
7300 \end_inset
7301
7302 -no-c-code-in-asm
7303 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7304
7305 \end_inset
7306
7307
7308 \series default
7309  Hides your ugly and inefficient c-code from the asm file, so you can always
7310  blame the compiler :)
7311 \layout List
7312 \labelwidthstring 00.00.0000
7313
7314
7315 \series bold
7316 -
7317 \begin_inset ERT
7318 status Collapsed
7319
7320 \layout Standard
7321
7322 \backslash
7323 /
7324 \end_inset
7325
7326 -no-peep-comments
7327 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7328
7329 \end_inset
7330
7331
7332 \series default
7333  Will not include peep-hole comments in the generated files.
7334 \layout List
7335 \labelwidthstring 00.00.0000
7336
7337
7338 \series bold
7339 -
7340 \begin_inset ERT
7341 status Collapsed
7342
7343 \layout Standard
7344
7345 \backslash
7346 /
7347 \end_inset
7348
7349 -i-code-in-asm
7350 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7351
7352 \end_inset
7353
7354
7355 \series default
7356  Include i-codes in the asm file.
7357  Sounds like noise but is most helpful for debugging the compiler itself.
7358 \layout List
7359 \labelwidthstring 00.00.0000
7360
7361
7362 \series bold
7363 -
7364 \begin_inset ERT
7365 status Collapsed
7366
7367 \layout Standard
7368
7369 \backslash
7370 /
7371 \end_inset
7372
7373 -less-pedantic
7374 \begin_inset LatexCommand \index{-\/-less-pedantic}
7375
7376 \end_inset
7377
7378
7379 \series default
7380  Disable some of the more pedantic warnings
7381 \begin_inset LatexCommand \index{Warnings}
7382
7383 \end_inset
7384
7385  (jwk burps: please be more specific here, please!).
7386  If you want rather more than less warnings you should consider using a
7387  separate tool dedicated to syntax checking like splint
7388 \begin_inset LatexCommand \url{www.splint.org}
7389
7390 \end_inset
7391
7392 .
7393 \layout List
7394 \labelwidthstring 00.00.0000
7395
7396
7397 \series bold
7398 -
7399 \begin_inset ERT
7400 status Collapsed
7401
7402 \layout Standard
7403
7404 \backslash
7405 /
7406 \end_inset
7407
7408 -disable-warning\SpecialChar ~
7409 <nnnn>
7410 \begin_inset LatexCommand \index{-\/-disable-warning}
7411
7412 \end_inset
7413
7414
7415 \series default
7416  Disable specific warning with number <nnnn>.
7417 \layout List
7418 \labelwidthstring 00.00.0000
7419
7420
7421 \series bold
7422 -
7423 \begin_inset ERT
7424 status Collapsed
7425
7426 \layout Standard
7427
7428 \backslash
7429 /
7430 \end_inset
7431
7432 -print-search-dirs
7433 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7434
7435 \end_inset
7436
7437
7438 \series default
7439  Display the directories in the compiler's search path
7440 \layout List
7441 \labelwidthstring 00.00.0000
7442
7443
7444 \series bold
7445 -
7446 \begin_inset ERT
7447 status Collapsed
7448
7449 \layout Standard
7450
7451 \backslash
7452 /
7453 \end_inset
7454
7455 -vc
7456 \begin_inset LatexCommand \index{-\/-vc}
7457
7458 \end_inset
7459
7460
7461 \series default
7462  Display errors and warnings using MSVC style, so you can use SDCC with
7463  visual studio.
7464 \layout List
7465 \labelwidthstring 00.00.0000
7466
7467
7468 \series bold
7469 -
7470 \begin_inset ERT
7471 status Collapsed
7472
7473 \layout Standard
7474
7475 \backslash
7476 /
7477 \end_inset
7478
7479 -use-stdout
7480 \begin_inset LatexCommand \index{-\/-use-stdout}
7481
7482 \end_inset
7483
7484
7485 \series default
7486  Send errors and warnings to stdout instead of stderr.
7487 \layout List
7488 \labelwidthstring 00.00.0000
7489
7490
7491 \series bold
7492 -Wa\SpecialChar ~
7493 asmOption[,asmOption]
7494 \series default
7495
7496 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7497
7498 \end_inset
7499
7500 ...
7501  Pass the asmOption to the assembler
7502 \begin_inset LatexCommand \index{Options assembler}
7503
7504 \end_inset
7505
7506
7507 \begin_inset LatexCommand \index{Assembler options}
7508
7509 \end_inset
7510
7511 .
7512  See file sdcc/as/doc/asxhtm.html for assembler options.
7513 \layout Subsection
7514
7515 Intermediate Dump Options
7516 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7517
7518 \end_inset
7519
7520
7521 \begin_inset LatexCommand \index{Options intermediate dump}
7522
7523 \end_inset
7524
7525
7526 \begin_inset LatexCommand \index{Intermediate dump options}
7527
7528 \end_inset
7529
7530
7531 \layout Standard
7532
7533 The following options are provided for the purpose of retargetting and debugging
7534  the compiler.
7535  These provided a means to dump the intermediate code (iCode
7536 \begin_inset LatexCommand \index{iCode}
7537
7538 \end_inset
7539
7540 ) generated by the compiler in human readable form at various stages of
7541  the compilation process.
7542  More on iCodes see chapter
7543 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7544
7545 \end_inset
7546
7547
7548 \begin_inset Quotes srd
7549 \end_inset
7550
7551 The anatomy of the compiler
7552 \begin_inset Quotes srd
7553 \end_inset
7554
7555 .
7556 \layout List
7557 \labelwidthstring 00.00.0000
7558
7559
7560 \series bold
7561 -
7562 \begin_inset ERT
7563 status Collapsed
7564
7565 \layout Standard
7566
7567 \backslash
7568 /
7569 \end_inset
7570
7571 -dumpraw
7572 \begin_inset LatexCommand \index{-\/-dumpraw}
7573
7574 \end_inset
7575
7576
7577 \series default
7578  This option will cause the compiler to dump the intermediate code into
7579  a file of named
7580 \emph on
7581 <source filename>.dumpraw
7582 \emph default
7583  just after the intermediate code has been generated for a function, i.e.
7584  before any optimizations are done.
7585  The basic blocks
7586 \begin_inset LatexCommand \index{Basic blocks}
7587
7588 \end_inset
7589
7590  at this stage ordered in the depth first number, so they may not be in
7591  sequence of execution.
7592 \layout List
7593 \labelwidthstring 00.00.0000
7594
7595
7596 \series bold
7597 -
7598 \begin_inset ERT
7599 status Collapsed
7600
7601 \layout Standard
7602
7603 \backslash
7604 /
7605 \end_inset
7606
7607 -dumpgcse
7608 \begin_inset LatexCommand \index{-\/-dumpgcse}
7609
7610 \end_inset
7611
7612
7613 \series default
7614  Will create a dump of iCode's, after global subexpression elimination
7615 \begin_inset LatexCommand \index{Global subexpression elimination}
7616
7617 \end_inset
7618
7619 , into a file named
7620 \emph on
7621 <source filename>.dumpgcse.
7622 \layout List
7623 \labelwidthstring 00.00.0000
7624
7625
7626 \series bold
7627 -
7628 \begin_inset ERT
7629 status Collapsed
7630
7631 \layout Standard
7632
7633 \backslash
7634 /
7635 \end_inset
7636
7637 -dumpdeadcode
7638 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
7639
7640 \end_inset
7641
7642
7643 \series default
7644  Will create a dump of iCode's, after deadcode elimination
7645 \begin_inset LatexCommand \index{Dead-code elimination}
7646
7647 \end_inset
7648
7649 , into a file named
7650 \emph on
7651 <source filename>.dumpdeadcode.
7652 \layout List
7653 \labelwidthstring 00.00.0000
7654
7655
7656 \series bold
7657 -
7658 \begin_inset ERT
7659 status Collapsed
7660
7661 \layout Standard
7662
7663 \backslash
7664 /
7665 \end_inset
7666
7667 -dumploop
7668 \begin_inset LatexCommand \index{-\/-dumploop}
7669
7670 \end_inset
7671
7672
7673 \series default
7674 \size large
7675
7676 \size default
7677 Will create a dump of iCode's, after loop optimizations
7678 \begin_inset LatexCommand \index{Loop optimization}
7679
7680 \end_inset
7681
7682 , into a file named
7683 \emph on
7684 <source filename>.dumploop.
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 -dumprange
7701 \begin_inset LatexCommand \index{-\/-dumprange}
7702
7703 \end_inset
7704
7705
7706 \series default
7707 \size large
7708
7709 \size default
7710 Will create a dump of iCode's, after live range analysis
7711 \begin_inset LatexCommand \index{Live range analysis}
7712
7713 \end_inset
7714
7715 , into a file named
7716 \emph on
7717 <source filename>.dumprange.
7718 \layout List
7719 \labelwidthstring 00.00.0000
7720
7721
7722 \series bold
7723 -
7724 \begin_inset ERT
7725 status Collapsed
7726
7727 \layout Standard
7728
7729 \backslash
7730 /
7731 \end_inset
7732
7733 -dumlrange
7734 \begin_inset LatexCommand \index{-\/-dumlrange}
7735
7736 \end_inset
7737
7738
7739 \series default
7740  Will dump the life ranges
7741 \begin_inset LatexCommand \index{Live range analysis}
7742
7743 \end_inset
7744
7745  for all symbols.
7746 \layout List
7747 \labelwidthstring 00.00.0000
7748
7749
7750 \series bold
7751 -
7752 \begin_inset ERT
7753 status Collapsed
7754
7755 \layout Standard
7756
7757 \backslash
7758 /
7759 \end_inset
7760
7761 -dumpregassign
7762 \begin_inset LatexCommand \index{-\/-dumpregassign}
7763
7764 \end_inset
7765
7766
7767 \bar under
7768
7769 \series default
7770 \bar default
7771 Will create a dump of iCode's, after register assignment
7772 \begin_inset LatexCommand \index{Register assignment}
7773
7774 \end_inset
7775
7776 , into a file named
7777 \emph on
7778 <source filename>.dumprassgn.
7779 \layout List
7780 \labelwidthstring 00.00.0000
7781
7782
7783 \series bold
7784 -
7785 \begin_inset ERT
7786 status Collapsed
7787
7788 \layout Standard
7789
7790 \backslash
7791 /
7792 \end_inset
7793
7794 -dumplrange
7795 \begin_inset LatexCommand \index{-\/-dumplrange}
7796
7797 \end_inset
7798
7799
7800 \series default
7801  Will create a dump of the live ranges of iTemp's
7802 \layout List
7803 \labelwidthstring 00.00.0000
7804
7805
7806 \series bold
7807 -
7808 \begin_inset ERT
7809 status Collapsed
7810
7811 \layout Standard
7812
7813 \backslash
7814 /
7815 \end_inset
7816
7817 -dumpall
7818 \begin_inset LatexCommand \index{-\/-dumpall}
7819
7820 \end_inset
7821
7822
7823 \size large
7824 \bar under
7825
7826 \series default
7827 \size default
7828 \bar default
7829 Will cause all the above mentioned dumps to be created.
7830 \layout Subsection
7831
7832 Redirecting output on Windows Shells
7833 \layout Standard
7834
7835 By default SDCC writes it's error messages to
7836 \begin_inset Quotes sld
7837 \end_inset
7838
7839 standard error
7840 \begin_inset Quotes srd
7841 \end_inset
7842
7843 .
7844  To force all messages to
7845 \begin_inset Quotes sld
7846 \end_inset
7847
7848 standard output
7849 \begin_inset Quotes srd
7850 \end_inset
7851
7852  use
7853 \series bold
7854 -
7855 \series default
7856 \emph on
7857
7858 \begin_inset ERT
7859 status Collapsed
7860
7861 \layout Standard
7862
7863 \backslash
7864 /
7865 \end_inset
7866
7867
7868 \series bold
7869 \emph default
7870 -
7871 \series default
7872 use-stdout
7873 \begin_inset LatexCommand \index{-\/-use-stdout}
7874
7875 \end_inset
7876
7877 .
7878  Additionally, if you happen to have visual studio installed in your windows
7879  machine, you can use it to compile your sources using a custom build and
7880  the SDCC -
7881 \emph on
7882
7883 \begin_inset ERT
7884 status Collapsed
7885
7886 \layout Standard
7887
7888 \backslash
7889 /
7890 \end_inset
7891
7892
7893 \emph default
7894 -vc
7895 \begin_inset LatexCommand \index{-\/-vc}
7896
7897 \end_inset
7898
7899  option.
7900  Something like this should work:
7901 \newline
7902
7903 \newline
7904
7905 \series bold
7906 c:
7907 \backslash
7908 sdcc
7909 \backslash
7910 bin
7911 \backslash
7912 sdcc.exe -
7913 \series default
7914 \emph on
7915
7916 \begin_inset ERT
7917 status Collapsed
7918
7919 \layout Standard
7920
7921 \backslash
7922 /
7923 \end_inset
7924
7925
7926 \series bold
7927 \emph default
7928 -vc -
7929 \series default
7930 \emph on
7931
7932 \begin_inset ERT
7933 status Collapsed
7934
7935 \layout Standard
7936
7937 \backslash
7938 /
7939 \end_inset
7940
7941
7942 \series bold
7943 \emph default
7944 -model-large -c $(InputPath)
7945 \layout Section
7946
7947 Environment variables
7948 \begin_inset LatexCommand \index{Environment variables}
7949
7950 \end_inset
7951
7952
7953 \layout Standard
7954
7955 SDCC recognizes the following environment variables:
7956 \layout List
7957 \labelwidthstring 00.00.0000
7958
7959
7960 \series bold
7961 SDCC_LEAVE_SIGNALS
7962 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7963
7964 \end_inset
7965
7966
7967 \series default
7968  SDCC installs a signal handler
7969 \begin_inset LatexCommand \index{signal handler}
7970
7971 \end_inset
7972
7973  to be able to delete temporary files after an user break (^C) or an exception.
7974  If this environment variable is set, SDCC won't install the signal handler
7975  in order to be able to debug SDCC.
7976 \layout List
7977 \labelwidthstring 00.00.0000
7978
7979
7980 \series bold
7981 TMP,\SpecialChar ~
7982 TEMP,\SpecialChar ~
7983 TMPDIR
7984 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7985
7986 \end_inset
7987
7988
7989 \series default
7990  Path, where temporary files will be created.
7991  The order of the variables is the search order.
7992  In a standard *nix environment these variables are not set, and there's
7993  no need to set them.
7994  On Windows it's recommended to set one of them.
7995 \layout List
7996 \labelwidthstring 00.00.0000
7997
7998
7999 \series bold
8000 SDCC_HOME
8001 \begin_inset LatexCommand \index{SDCC\_HOME}
8002
8003 \end_inset
8004
8005
8006 \series default
8007  Path, see section
8008 \begin_inset LatexCommand \ref{sub:Install-paths}
8009
8010 \end_inset
8011
8012 \SpecialChar ~
8013
8014 \begin_inset Quotes sld
8015 \end_inset
8016
8017  Install Paths
8018 \begin_inset Quotes srd
8019 \end_inset
8020
8021 .
8022 \layout List
8023 \labelwidthstring 00.00.0000
8024
8025
8026 \series bold
8027 SDCC_INCLUDE
8028 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
8029
8030 \end_inset
8031
8032
8033 \series default
8034  Path, see section
8035 \begin_inset LatexCommand \ref{sub:Search-Paths}
8036
8037 \end_inset
8038
8039 \SpecialChar ~
8040
8041 \begin_inset Quotes sld
8042 \end_inset
8043
8044 Search Paths
8045 \begin_inset Quotes srd
8046 \end_inset
8047
8048 .
8049 \layout List
8050 \labelwidthstring 00.00.0000
8051
8052
8053 \series bold
8054 SDCC_LIB
8055 \begin_inset LatexCommand \index{SDCC\_LIB}
8056
8057 \end_inset
8058
8059
8060 \series default
8061  Path, see section
8062 \begin_inset LatexCommand \ref{sub:Search-Paths}
8063
8064 \end_inset
8065
8066 \SpecialChar ~
8067
8068 \begin_inset Quotes sld
8069 \end_inset
8070
8071 Search Paths
8072 \begin_inset Quotes srd
8073 \end_inset
8074
8075 ..
8076 \layout Standard
8077
8078 There are some more environment variables recognized by SDCC, but these
8079  are solely used for debugging purposes.
8080  They can change or disappear very quickly, and will never be documented.
8081 \layout Section
8082
8083 Storage Class Language Extensions
8084 \layout Subsection
8085
8086 MCS51/DS390 Storage Class
8087 \begin_inset LatexCommand \index{Storage class}
8088
8089 \end_inset
8090
8091  Language Extensions
8092 \layout Standard
8093
8094 In addition to the ANSI storage classes SDCC allows the following MCS51
8095  specific storage classes:
8096 \layout Subsubsection
8097
8098 data
8099 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8100
8101 \end_inset
8102
8103  / near
8104 \begin_inset LatexCommand \index{near (storage class)}
8105
8106 \end_inset
8107
8108
8109 \layout Standard
8110
8111 This is the
8112 \series bold
8113 default
8114 \series default
8115  storage class for the Small Memory model (
8116 \emph on
8117 data
8118 \emph default
8119  and
8120 \emph on
8121 near
8122 \emph default
8123  can be used synonymously).
8124  Variables declared with this storage class will be allocated in the directly
8125  addressable portion of the internal RAM of a 8051, e.g.:
8126 \layout Verse
8127
8128
8129 \family typewriter
8130 data unsigned char test_data;
8131 \layout Standard
8132
8133 Writing 0x01 to this variable generates the assembly code:
8134 \layout Verse
8135
8136
8137 \family typewriter
8138 75*00 01\SpecialChar ~
8139 \SpecialChar ~
8140 \SpecialChar ~
8141 mov\SpecialChar ~
8142 \SpecialChar ~
8143 _test_data,#0x01
8144 \layout Subsubsection
8145
8146 xdata
8147 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8148
8149 \end_inset
8150
8151  / far
8152 \begin_inset LatexCommand \index{far (storage class)}
8153
8154 \end_inset
8155
8156
8157 \layout Standard
8158
8159 Variables declared with this storage class will be placed in the external
8160  RAM.
8161  This is the
8162 \series bold
8163 default
8164 \series default
8165  storage class for the Large Memory model, e.g.:
8166 \layout Verse
8167
8168
8169 \family typewriter
8170 xdata unsigned char test_xdata;
8171 \layout Standard
8172
8173 Writing 0x01 to this variable generates the assembly code:
8174 \layout Verse
8175
8176
8177 \family typewriter
8178 90s00r00\SpecialChar ~
8179 \SpecialChar ~
8180 \SpecialChar ~
8181 mov\SpecialChar ~
8182 \SpecialChar ~
8183 dptr,#_test_xdata
8184 \newline
8185 74\SpecialChar ~
8186 01\SpecialChar ~
8187 \SpecialChar ~
8188 \SpecialChar ~
8189 \SpecialChar ~
8190 \SpecialChar ~
8191 \SpecialChar ~
8192 mov\SpecialChar ~
8193 \SpecialChar ~
8194 a,#0x01
8195 \newline
8196 F0\SpecialChar ~
8197 \SpecialChar ~
8198 \SpecialChar ~
8199 \SpecialChar ~
8200 \SpecialChar ~
8201 \SpecialChar ~
8202 \SpecialChar ~
8203 \SpecialChar ~
8204 \SpecialChar ~
8205 movx\SpecialChar ~
8206 @dptr,a
8207 \layout Subsubsection
8208
8209 idata
8210 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8211
8212 \end_inset
8213
8214
8215 \layout Standard
8216
8217 Variables declared with this storage class will be allocated into the indirectly
8218  addressable portion of the internal ram of a 8051, e.g.:
8219 \layout Verse
8220
8221
8222 \family typewriter
8223 idata unsigned char test_idata;
8224 \layout Standard
8225
8226 Writing 0x01 to this variable generates the assembly code:
8227 \layout Verse
8228
8229
8230 \family typewriter
8231 78r00\SpecialChar ~
8232 \SpecialChar ~
8233 \SpecialChar ~
8234 \SpecialChar ~
8235 \SpecialChar ~
8236 \SpecialChar ~
8237 \SpecialChar ~
8238 mov\SpecialChar ~
8239 \SpecialChar ~
8240 r0,#_test_idata
8241 \newline
8242 76\SpecialChar ~
8243 01\SpecialChar ~
8244 \SpecialChar ~
8245 \SpecialChar ~
8246 \SpecialChar ~
8247 \SpecialChar ~
8248 \SpecialChar ~
8249 \SpecialChar ~
8250 mov\SpecialChar ~
8251 \SpecialChar ~
8252 @r0,#0x01
8253 \layout Standard
8254
8255 Please note, the first 128 byte of idata physically access the same RAM
8256  as the data memory.
8257  The original 8051 had 128 byte idata memory, nowadays most devices have
8258  256 byte idata memory.
8259  The stack
8260 \begin_inset LatexCommand \index{stack}
8261
8262 \end_inset
8263
8264  is located in idata memory.
8265 \layout Subsubsection
8266
8267 pdata
8268 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8269
8270 \end_inset
8271
8272
8273 \layout Standard
8274
8275 Paged xdata access is just as straightforward as using the other addressing
8276  modes of a 8051.
8277  It is typically located at the start of xdata and has a maximum size of
8278  256 bytes.
8279  The following example writes 0x01 to the address pointed to.
8280  Please note, pdata access physically accesses xdata memory.
8281  The high byte of the address is determined by port P2
8282 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8283
8284 \end_inset
8285
8286 (or in case of some 8051 variants by a separate Special Function Register,
8287  see section
8288 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8289
8290 \end_inset
8291
8292 ).
8293 \layout Verse
8294
8295
8296 \family typewriter
8297 pdata unsigned char *test_pdata_ptr;
8298 \newline
8299
8300 \newline
8301 void main()
8302 \newline
8303 {
8304 \newline
8305 \SpecialChar ~
8306 \SpecialChar ~
8307 \SpecialChar ~
8308 \SpecialChar ~
8309 test_pdata_ptr = (pdata *)0xfe;
8310 \newline
8311 \SpecialChar ~
8312 \SpecialChar ~
8313 \SpecialChar ~
8314 \SpecialChar ~
8315 *test_pdata_ptr = 1;
8316 \newline
8317 }
8318 \layout Standard
8319
8320 Generates the assembly code:
8321 \layout Verse
8322
8323
8324 \family typewriter
8325 75*01 FE\SpecialChar ~
8326 \SpecialChar ~
8327 \SpecialChar ~
8328 mov\SpecialChar ~
8329  _test_pdata_ptr,#0xFE
8330 \newline
8331 78 FE\SpecialChar ~
8332 \SpecialChar ~
8333 \SpecialChar ~
8334 \SpecialChar ~
8335 \SpecialChar ~
8336 \SpecialChar ~
8337 mov\SpecialChar ~
8338  r0,#0xFE
8339 \newline
8340 74 01\SpecialChar ~
8341 \SpecialChar ~
8342 \SpecialChar ~
8343 \SpecialChar ~
8344 \SpecialChar ~
8345 \SpecialChar ~
8346 mov\SpecialChar ~
8347  a,#0x01
8348 \newline
8349 F2\SpecialChar ~
8350 \SpecialChar ~
8351 \SpecialChar ~
8352 \SpecialChar ~
8353 \SpecialChar ~
8354 \SpecialChar ~
8355 \SpecialChar ~
8356 \SpecialChar ~
8357 \SpecialChar ~
8358 movx @r0,a
8359 \layout Standard
8360
8361 If the -
8362 \begin_inset ERT
8363 status Collapsed
8364
8365 \layout Standard
8366
8367 \backslash
8368 /
8369 \end_inset
8370
8371 -xstack
8372 \begin_inset LatexCommand \index{-\/-xstack}
8373
8374 \end_inset
8375
8376  option is used the pdata memory area is followed by the xstack memory area
8377  and the sum of their sizes is limited to 256 bytes.
8378 \layout Subsubsection
8379
8380 code
8381 \begin_inset LatexCommand \index{code}
8382
8383 \end_inset
8384
8385
8386 \layout Standard
8387
8388 'Variables' declared with this storage class will be placed in the code
8389  memory:
8390 \layout Verse
8391
8392
8393 \family typewriter
8394 code unsigned char test_code;
8395 \layout Standard
8396
8397 Read access to this variable generates the assembly code:
8398 \layout Verse
8399
8400
8401 \family typewriter
8402 90s00r6F\SpecialChar ~
8403 \SpecialChar ~
8404 \SpecialChar ~
8405 mov dptr,#_test_code
8406 \newline
8407 E4\SpecialChar ~
8408 \SpecialChar ~
8409 \SpecialChar ~
8410 \SpecialChar ~
8411 \SpecialChar ~
8412 \SpecialChar ~
8413 \SpecialChar ~
8414 \SpecialChar ~
8415 \SpecialChar ~
8416 clr a
8417 \newline
8418 93\SpecialChar ~
8419 \SpecialChar ~
8420 \SpecialChar ~
8421 \SpecialChar ~
8422 \SpecialChar ~
8423 \SpecialChar ~
8424 \SpecialChar ~
8425 \SpecialChar ~
8426 \SpecialChar ~
8427 movc a,@a+dptr
8428 \layout Standard
8429
8430
8431 \family typewriter
8432 char
8433 \family default
8434  indexed arrays of characters in code memory can be accessed efficiently:
8435 \layout Verse
8436
8437
8438 \family typewriter
8439 code char test_array[] = {'c','h','e','a','p'};
8440 \layout Standard
8441
8442 Read access to this array using an 8-bit unsigned index generates the assembly
8443  code:
8444 \layout Verse
8445
8446
8447 \family typewriter
8448 E5*00\SpecialChar ~
8449 \SpecialChar ~
8450 \SpecialChar ~
8451 \SpecialChar ~
8452 \SpecialChar ~
8453 \SpecialChar ~
8454 mov a,_index
8455 \layout Verse
8456
8457
8458 \family typewriter
8459 90s00r41\SpecialChar ~
8460 \SpecialChar ~
8461 \SpecialChar ~
8462 mov dptr,#_test_array
8463 \layout Verse
8464
8465
8466 \family typewriter
8467 93\SpecialChar ~
8468 \SpecialChar ~
8469 \SpecialChar ~
8470 \SpecialChar ~
8471 \SpecialChar ~
8472 \SpecialChar ~
8473 \SpecialChar ~
8474 \SpecialChar ~
8475 \SpecialChar ~
8476 movc a,@a+dptr
8477 \layout Subsubsection
8478
8479 bit
8480 \begin_inset LatexCommand \index{bit}
8481
8482 \end_inset
8483
8484
8485 \layout Standard
8486
8487 This is a data-type and a storage class specifier.
8488  When a variable is declared as a bit, it is allocated into the bit addressable
8489  memory of 8051, e.g.:
8490 \layout Verse
8491
8492
8493 \family typewriter
8494 bit test_bit;
8495 \layout Standard
8496
8497 Writing 1 to this variable generates the assembly code:
8498 \layout Verse
8499
8500
8501 \family typewriter
8502 D2*00\SpecialChar ~
8503 \SpecialChar ~
8504 \SpecialChar ~
8505 \SpecialChar ~
8506 \SpecialChar ~
8507 \SpecialChar ~
8508 \SpecialChar ~
8509 setb\SpecialChar ~
8510 _test_bit
8511 \layout Standard
8512
8513 The bit addressable memory consists of 128 bits which are located from 0x20
8514  to 0x2f in data memory.
8515
8516 \newline
8517 Apart from this 8051 specific storage class most architectures support ANSI-C
8518  bitfields
8519 \begin_inset LatexCommand \index{bitfields}
8520
8521 \end_inset
8522
8523
8524 \begin_inset Foot
8525 collapsed false
8526
8527 \layout Standard
8528
8529 Not really meant as examples, but nevertheless showing what bitfields are
8530  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8531 \end_inset
8532
8533 .
8534  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8535  signed modifier are implemented as unsigned.
8536 \layout Subsubsection
8537
8538 sfr
8539 \begin_inset LatexCommand \index{sfr}
8540
8541 \end_inset
8542
8543  / sbit
8544 \begin_inset LatexCommand \index{sbit}
8545
8546 \end_inset
8547
8548
8549 \layout Standard
8550
8551 Like the bit keyword,
8552 \emph on
8553 sfr / sbit
8554 \emph default
8555 signifies both a data-type and storage class, they are used to describe
8556  the
8557 \emph on
8558 s
8559 \emph default
8560 pecial
8561 \emph on
8562 f
8563 \emph default
8564 unction
8565 \emph on
8566 r
8567 \emph default
8568 egisters and
8569 \emph on
8570 s
8571 \emph default
8572 pecial
8573 \emph on
8574 bit
8575 \emph default
8576  variables of a 8051, eg:
8577 \layout Verse
8578
8579
8580 \family typewriter
8581 sfr at
8582 \begin_inset LatexCommand \index{at}
8583
8584 \end_inset
8585
8586  0x80 P0;\SpecialChar ~
8587  /* special function register P0 at location 0x80 */
8588 \newline
8589 sbit at 0xd7 CY; /* CY (Carry Flag
8590 \begin_inset LatexCommand \index{Flags}
8591
8592 \end_inset
8593
8594
8595 \begin_inset LatexCommand \index{Carry flag}
8596
8597 \end_inset
8598
8599 ) */
8600 \layout Standard
8601
8602 Special function registers which are located on an address dividable by
8603  8 are bit-addressable, an
8604 \emph on
8605  sbit
8606 \emph default
8607  addresses a specific bit within these sfr.
8608 \layout Subsubsection
8609
8610 Pointers
8611 \begin_inset LatexCommand \index{Pointer}
8612
8613 \end_inset
8614
8615  to MCS51/DS390 specific memory spaces
8616 \layout Standard
8617
8618 SDCC allows (via language extensions) pointers to explicitly point to any
8619  of the memory spaces
8620 \begin_inset LatexCommand \index{Memory model}
8621
8622 \end_inset
8623
8624  of the 8051.
8625  In addition to the explicit pointers, the compiler uses (by default) generic
8626  pointers which can be used to point to any of the memory spaces.
8627 \newline
8628
8629 \newline
8630 Pointer declaration examples:
8631 \layout Verse
8632
8633
8634 \family typewriter
8635 /* pointer physically in internal ram pointing to object in external ram
8636  */
8637 \newline
8638 xdata unsigned char * data p;
8639 \newline
8640
8641 \newline
8642 /* pointer physically in external ram pointing to object in internal ram
8643  */
8644 \newline
8645 data unsigned char * xdata p;
8646 \newline
8647
8648 \newline
8649 /* pointer physically in code rom pointing to data in xdata space */
8650 \newline
8651 xdata unsigned char * code p;
8652 \newline
8653
8654 \newline
8655 /* pointer physically in code space pointing to data in code space */
8656 \newline
8657 code unsigned char * code p;
8658 \newline
8659
8660 \newline
8661 /* the following is a generic pointer physically located in xdata space
8662  */
8663 \newline
8664 char * xdata p;
8665 \layout Standard
8666
8667 Well you get the idea.
8668
8669 \newline
8670
8671 \newline
8672 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
8673 \emph on
8674 generic
8675 \emph default
8676  pointers.
8677
8678 \size small
8679
8680 \newline
8681
8682 \newline
8683
8684 \size default
8685 The highest order byte of the
8686 \emph on
8687 generic
8688 \emph default
8689  pointers contains the data space information.
8690  Assembler support routines are called whenever data is stored or retrieved
8691  using
8692 \emph on
8693 generic
8694 \emph default
8695  pointers.
8696  These are useful for developing reusable library
8697 \begin_inset LatexCommand \index{Libraries}
8698
8699 \end_inset
8700
8701  routines.
8702  Explicitly specifying the pointer type will generate the most efficient
8703  code.
8704 \layout Subsubsection
8705
8706 Notes on MCS51 memory
8707 \begin_inset LatexCommand \index{MCS51 memory}
8708
8709 \end_inset
8710
8711  layout
8712 \layout Standard
8713
8714 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
8715  RAM memory which is structured as follows:
8716 \newline
8717
8718 \newline
8719 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
8720
8721 \newline
8722 - Bytes 20-2F - 16 bytes to hold 128 bit
8723 \begin_inset LatexCommand \index{bit}
8724
8725 \end_inset
8726
8727  variables and,
8728 \newline
8729 - Bytes 30-7F - 80 bytes for general purpose use.
8730 \newline
8731
8732 \layout Standard
8733
8734 Additionally some members of the MCS51 family may have up to 128 bytes of
8735  additional, indirectly addressable, internal RAM memory (
8736 \emph on
8737 idata
8738 \emph default
8739
8740 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8741
8742 \end_inset
8743
8744 ).
8745  Furthermore, some chips may have some built in external memory (
8746 \emph on
8747 xdata
8748 \emph default
8749
8750 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8751
8752 \end_inset
8753
8754 ) which should not be confused with the internal, directly addressable RAM
8755  memory (
8756 \emph on
8757 data
8758 \emph default
8759
8760 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8761
8762 \end_inset
8763
8764 ).
8765  Sometimes this built in
8766 \emph on
8767 xdata
8768 \emph default
8769  memory has to be activated before using it (you can probably find this
8770  information on the datasheet of the microcontroller your are using, see
8771  also section
8772 \begin_inset LatexCommand \ref{sub:Startup-Code}
8773
8774 \end_inset
8775
8776 \SpecialChar ~
8777 Startup-Code).
8778 \layout Standard
8779
8780 Normally SDCC will only use the first bank
8781 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
8782
8783 \end_inset
8784
8785  of registers (register bank 0), but it is possible to specify that other
8786  banks of registers should be used in interrupt
8787 \begin_inset LatexCommand \index{interrupt}
8788
8789 \end_inset
8790
8791  routines.
8792  By default, the compiler will place the stack after the last byte of allocated
8793  memory for variables.
8794  For example, if the first 2 banks of registers are used, and only four
8795  bytes are used for
8796 \emph on
8797 data
8798 \emph default
8799  variables, it will position the base of the internal stack at address 20
8800  (0x14).
8801  This implies that as the stack
8802 \begin_inset LatexCommand \index{stack}
8803
8804 \end_inset
8805
8806  grows, it will use up the remaining register banks, and the 16 bytes used
8807  by the 128 bit variables, and 80 bytes for general purpose use.
8808  If any bit variables are used, the data variables will be placed in unused
8809  register banks and after the byte holding the last bit variable.
8810  For example, if register banks 0 and 1 are used, and there are 9 bit variables
8811  (two bytes used),
8812 \emph on
8813 data
8814 \emph default
8815  variables will be placed starting from address 0x10 to 0x20 and continue
8816  at address 0x22.
8817  You can also use -
8818 \begin_inset ERT
8819 status Collapsed
8820
8821 \layout Standard
8822
8823 \backslash
8824 /
8825 \end_inset
8826
8827 -data-loc
8828 \begin_inset LatexCommand \index{-\/-data-loc<Value>}
8829
8830 \end_inset
8831
8832  to specify the start address of the
8833 \emph on
8834 data
8835 \emph default
8836  and -
8837 \begin_inset ERT
8838 status Collapsed
8839
8840 \layout Standard
8841
8842 \backslash
8843 /
8844 \end_inset
8845
8846 -iram-size to specify the size of the total internal RAM (
8847 \emph on
8848 data
8849 \emph default
8850 +
8851 \emph on
8852 idata
8853 \emph default
8854 ).
8855
8856 \layout Standard
8857
8858 By default the 8051 linker will place the stack after the last byte of (i)data
8859  variables.
8860  Option -
8861 \begin_inset ERT
8862 status Collapsed
8863
8864 \layout Standard
8865
8866 \backslash
8867 /
8868 \end_inset
8869
8870 -stack-loc
8871 \begin_inset LatexCommand \index{-\/-stack-loc<Value>}
8872
8873 \end_inset
8874
8875  allows you to specify the start of the stack, i.e.
8876  you could start it after any data in the general purpose area.
8877  If your microcontroller has additional indirectly addressable internal
8878  RAM (
8879 \emph on
8880 idata
8881 \emph default
8882 ) you can place the stack on it.
8883  You may also need to use -
8884 \begin_inset ERT
8885 status Collapsed
8886
8887 \layout Standard
8888
8889 \backslash
8890 /
8891 \end_inset
8892
8893 -xdata-loc
8894 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
8895
8896 \end_inset
8897
8898  to set the start address of the external RAM (
8899 \emph on
8900 xdata
8901 \emph default
8902 ) and -
8903 \begin_inset ERT
8904 status Collapsed
8905
8906 \layout Standard
8907
8908 \backslash
8909 /
8910 \end_inset
8911
8912 -xram-size
8913 \begin_inset LatexCommand \index{-\/-data-loc}
8914
8915 \end_inset
8916
8917  to specify its size.
8918  Same goes for the code memory, using -
8919 \begin_inset ERT
8920 status Collapsed
8921
8922 \layout Standard
8923
8924 \backslash
8925 /
8926 \end_inset
8927
8928 -code-loc
8929 \begin_inset LatexCommand \index{-\/-data-loc}
8930
8931 \end_inset
8932
8933  and -
8934 \begin_inset ERT
8935 status Collapsed
8936
8937 \layout Standard
8938
8939 \backslash
8940 /
8941 \end_inset
8942
8943 -code-size
8944 \begin_inset LatexCommand \index{-\/-data-loc}
8945
8946 \end_inset
8947
8948 .
8949  If in doubt, don't specify any options and see if the resulting memory
8950  layout is appropriate, then you can adjust it.
8951 \layout Standard
8952
8953 The linker generates two files with memory allocation information.
8954  The first, with extension .map
8955 \begin_inset LatexCommand \index{<file>.map}
8956
8957 \end_inset
8958
8959  shows all the variables and segments.
8960  The second with extension .mem
8961 \begin_inset LatexCommand \index{<file>.mem}
8962
8963 \end_inset
8964
8965  shows the final memory layout.
8966  The linker will complain either if memory segments overlap, there is not
8967  enough memory, or there is not enough space for stack.
8968  If you get any linking warnings and/or errors related to stack or segments
8969  allocation, take a look at either the .map or .mem files to find out what
8970  the problem is.
8971  The .mem file may even suggest a solution to the problem.
8972 \layout Subsection
8973
8974 Z80/Z180 Storage Class
8975 \begin_inset LatexCommand \index{Storage class}
8976
8977 \end_inset
8978
8979  Language Extensions
8980 \layout Subsubsection
8981
8982 sfr
8983 \begin_inset LatexCommand \index{sfr}
8984
8985 \end_inset
8986
8987  (in/out to 8-bit addresses)
8988 \layout Standard
8989
8990 The Z80
8991 \begin_inset LatexCommand \index{Z80}
8992
8993 \end_inset
8994
8995  family has separate address spaces for memory and
8996 \emph on
8997 i
8998 \emph default
8999 nput/
9000 \emph on
9001 o
9002 \emph default
9003 utput memory.
9004  I/O memory
9005 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
9006
9007 \end_inset
9008
9009  is accessed with special instructions, e.g.:
9010 \layout Verse
9011
9012
9013 \family typewriter
9014 sfr at 0x78 IoPort;\SpecialChar ~
9015 \SpecialChar ~
9016 /* define a var in I/O space at 78h called IoPort */
9017
9018 \layout Standard
9019
9020 Writing 0x01 to this variable generates the assembly code:
9021 \layout Verse
9022
9023
9024 \family typewriter
9025 3E 01\SpecialChar ~
9026 \SpecialChar ~
9027 \SpecialChar ~
9028 \SpecialChar ~
9029 \SpecialChar ~
9030 \SpecialChar ~
9031 ld a,#0x01
9032 \newline
9033 D3 78\SpecialChar ~
9034 \SpecialChar ~
9035 \SpecialChar ~
9036 \SpecialChar ~
9037 \SpecialChar ~
9038 \SpecialChar ~
9039 out (_IoPort),a
9040 \layout Subsubsection
9041
9042 banked sfr
9043 \begin_inset LatexCommand \index{sfr}
9044
9045 \end_inset
9046
9047  (in/out to 16-bit addresses)
9048 \layout Standard
9049
9050 The keyword
9051 \emph on
9052 banked
9053 \emph default
9054  is used to support 16 bit addresses in I/O memory e.g.:
9055 \layout Verse
9056
9057
9058 \family typewriter
9059 sfr banked at
9060 \begin_inset LatexCommand \index{at}
9061
9062 \end_inset
9063
9064  0x123 IoPort;
9065 \layout Standard
9066
9067 Writing 0x01 to this variable generates the assembly code:
9068 \layout Verse
9069
9070
9071 \family typewriter
9072 01 23 01\SpecialChar ~
9073 \SpecialChar ~
9074 \SpecialChar ~
9075 ld bc,#_IoPort
9076 \newline
9077 3E 01\SpecialChar ~
9078 \SpecialChar ~
9079 \SpecialChar ~
9080 \SpecialChar ~
9081 \SpecialChar ~
9082 \SpecialChar ~
9083 ld a,#0x01
9084 \newline
9085 ED 79\SpecialChar ~
9086 \SpecialChar ~
9087 \SpecialChar ~
9088 \SpecialChar ~
9089 \SpecialChar ~
9090 \SpecialChar ~
9091 out (c),a
9092 \layout Subsubsection
9093
9094 sfr
9095 \begin_inset LatexCommand \index{sfr}
9096
9097 \end_inset
9098
9099  (in0/out0 to 8 bit addresses on Z180
9100 \begin_inset LatexCommand \index{Z180}
9101
9102 \end_inset
9103
9104 /HD64180
9105 \begin_inset LatexCommand \index{HD64180}
9106
9107 \end_inset
9108
9109 )
9110 \layout Standard
9111
9112 The compiler option -
9113 \begin_inset ERT
9114 status Collapsed
9115
9116 \layout Standard
9117
9118 \backslash
9119 /
9120 \end_inset
9121
9122 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9123 portmode
9124 \begin_inset LatexCommand \index{\#pragma portmode}
9125
9126 \end_inset
9127
9128 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9129 ns
9130 \family typewriter
9131 in0/out0
9132 \family default
9133  instead of
9134 \family typewriter
9135 in/out
9136 \family default
9137 .
9138  If you include the file z180.h this will be set automatically.
9139 \layout Subsection
9140
9141 HC08 Storage Class
9142 \begin_inset LatexCommand \index{Storage class}
9143
9144 \end_inset
9145
9146  Language Extensions
9147 \layout Subsubsection
9148
9149 data
9150 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9151
9152 \end_inset
9153
9154
9155 \layout Standard
9156
9157 The data storage class declares a variable that resides in the first 256
9158  bytes of memory (the direct page).
9159  The HC08 is most efficient at accessing variables (especially pointers)
9160  stored here.
9161 \layout Subsubsection
9162
9163 xdata
9164 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9165
9166 \end_inset
9167
9168
9169 \layout Standard
9170
9171 The xdata storage class declares a variable that can reside anywhere in
9172  memory.
9173  This is the default if no storage class is specified.
9174
9175 \layout Section
9176
9177 Absolute Addressing
9178 \begin_inset LatexCommand \index{Absolute addressing}
9179
9180 \end_inset
9181
9182
9183 \layout Standard
9184
9185 Data items can be assigned an absolute address with the
9186 \emph on
9187 at
9188 \begin_inset LatexCommand \index{at}
9189
9190 \end_inset
9191
9192  <address>
9193 \emph default
9194  keyword, in addition to a storage class, e.g.:
9195 \layout Verse
9196
9197
9198 \family typewriter
9199 xdata
9200 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9201
9202 \end_inset
9203
9204  at
9205 \begin_inset LatexCommand \index{at}
9206
9207 \end_inset
9208
9209  0x7ffe unsigned int chksum;
9210 \layout Standard
9211
9212 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9213  of the external ram.
9214  The compiler does
9215 \emph on
9216 not
9217 \emph default
9218  reserve any space for variables declared in this way (they are implemented
9219  with an equate in the assembler).
9220  Thus it is left to the programmer to make sure there are no overlaps with
9221  other variables that are declared without the absolute address.
9222  The assembler listing file (.lst
9223 \begin_inset LatexCommand \index{<file>.lst}
9224
9225 \end_inset
9226
9227 ) and the linker output files (.rst
9228 \begin_inset LatexCommand \index{<file>.rst}
9229
9230 \end_inset
9231
9232 ) and (.map
9233 \begin_inset LatexCommand \index{<file>.map}
9234
9235 \end_inset
9236
9237 ) are good places to look for such overlaps.
9238  Variables with an absolute address are
9239 \emph on
9240 not
9241 \emph default
9242  initialized
9243 \begin_inset LatexCommand \index{Variable initialization}
9244
9245 \end_inset
9246
9247 .
9248 \layout Standard
9249
9250 In case of memory mapped I/O devices the keyword
9251 \emph on
9252 volatile
9253 \emph default
9254  has to be used to tell the compiler that accesses might not be removed:
9255 \layout Verse
9256
9257
9258 \family typewriter
9259 volatile
9260 \begin_inset LatexCommand \index{volatile}
9261
9262 \end_inset
9263
9264  xdata
9265 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9266
9267 \end_inset
9268
9269  at
9270 \begin_inset LatexCommand \index{at}
9271
9272 \end_inset
9273
9274  0x8000 unsigned char PORTA_8255;
9275 \layout Standard
9276
9277 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9278 r) array
9279 \family typewriter
9280 \size footnotesize
9281
9282 \begin_inset LatexCommand \index{Aligned array}
9283
9284 \end_inset
9285
9286
9287 \family default
9288 \size default
9289  starts at a block (256 byte) boundary
9290 \begin_inset LatexCommand \index{block boundary}
9291
9292 \end_inset
9293
9294  (section
9295 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9296
9297 \end_inset
9298
9299  has an example).
9300 \newline
9301 Absolute addresses can be specified for variables in all storage classes,
9302  e.g.:
9303 \layout Verse
9304
9305
9306 \family typewriter
9307 bit
9308 \begin_inset LatexCommand \index{bit}
9309
9310 \end_inset
9311
9312  at
9313 \begin_inset LatexCommand \index{at}
9314
9315 \end_inset
9316
9317  0x02 bvar;
9318 \layout Standard
9319
9320 The above example will allocate the variable at offset 0x02 in the bit-addressab
9321 le space.
9322  There is no real advantage to assigning absolute addresses to variables
9323  in this manner, unless you want strict control over all the variables allocated.
9324  One possible use would be to write hardware portable code.
9325  For example, if you have a routine that uses one or more of the microcontroller
9326  I/O pins, and such pins are different for two different hardwares, you
9327  can declare the I/O pins in your routine using:
9328 \layout Verse
9329
9330
9331 \family typewriter
9332 extern volatile bit MOSI;\SpecialChar ~
9333 \SpecialChar ~
9334 \SpecialChar ~
9335 \SpecialChar ~
9336 /* master out, slave in */
9337 \newline
9338 extern volatile bit MISO;\SpecialChar ~
9339 \SpecialChar ~
9340 \SpecialChar ~
9341 \SpecialChar ~
9342 /* master in, slave out */
9343 \newline
9344 extern volatile bit MCLK;\SpecialChar ~
9345 \SpecialChar ~
9346 \SpecialChar ~
9347 \SpecialChar ~
9348 /* master clock */
9349 \newline
9350
9351 \newline
9352 /* Input and Output of a byte on a 3-wire serial bus.
9353 \newline
9354 \SpecialChar ~
9355 \SpecialChar ~
9356 \SpecialChar ~
9357 If needed adapt polarity of clock, polarity of data and bit order
9358 \newline
9359 \SpecialChar ~
9360 */
9361 \newline
9362 unsigned char spi_io(unsigned char out_byte)
9363 \newline
9364 {
9365 \newline
9366 \SpecialChar ~
9367 \SpecialChar ~
9368 \SpecialChar ~
9369 \SpecialChar ~
9370 unsigned char i=8;
9371 \newline
9372 \SpecialChar ~
9373 \SpecialChar ~
9374 \SpecialChar ~
9375 \SpecialChar ~
9376 do {
9377 \newline
9378 \SpecialChar ~
9379 \SpecialChar ~
9380 \SpecialChar ~
9381 \SpecialChar ~
9382 \SpecialChar ~
9383 \SpecialChar ~
9384 \SpecialChar ~
9385 \SpecialChar ~
9386 MOSI = out_byte & 0x80;
9387 \newline
9388 \SpecialChar ~
9389 \SpecialChar ~
9390 \SpecialChar ~
9391 \SpecialChar ~
9392 \SpecialChar ~
9393 \SpecialChar ~
9394 \SpecialChar ~
9395 \SpecialChar ~
9396 out_byte <<= 1;
9397 \newline
9398 \SpecialChar ~
9399 \SpecialChar ~
9400 \SpecialChar ~
9401 \SpecialChar ~
9402 \SpecialChar ~
9403 \SpecialChar ~
9404 \SpecialChar ~
9405 \SpecialChar ~
9406 MCLK = 1;
9407 \newline
9408 \SpecialChar ~
9409 \SpecialChar ~
9410 \SpecialChar ~
9411 \SpecialChar ~
9412 \SpecialChar ~
9413 \SpecialChar ~
9414 \SpecialChar ~
9415 \SpecialChar ~
9416 /* _asm nop _endasm; */\SpecialChar ~
9417 \SpecialChar ~
9418 \SpecialChar ~
9419 \SpecialChar ~
9420 \SpecialChar ~
9421 \SpecialChar ~
9422 \SpecialChar ~
9423 \SpecialChar ~
9424 /* for slow peripherals */
9425 \newline
9426 \SpecialChar ~
9427 \SpecialChar ~
9428 \SpecialChar ~
9429 \SpecialChar ~
9430 \SpecialChar ~
9431 \SpecialChar ~
9432 \SpecialChar ~
9433 \SpecialChar ~
9434 if(MISO)
9435 \newline
9436 \SpecialChar ~
9437 \SpecialChar ~
9438 \SpecialChar ~
9439 \SpecialChar ~
9440 \SpecialChar ~
9441 \SpecialChar ~
9442 \SpecialChar ~
9443 \SpecialChar ~
9444 \SpecialChar ~
9445 \SpecialChar ~
9446 \SpecialChar ~
9447 \SpecialChar ~
9448 out_byte += 1;
9449 \newline
9450 \SpecialChar ~
9451 \SpecialChar ~
9452 \SpecialChar ~
9453 \SpecialChar ~
9454 \SpecialChar ~
9455 \SpecialChar ~
9456 \SpecialChar ~
9457 \SpecialChar ~
9458 MCLK = 0;
9459 \newline
9460 \SpecialChar ~
9461 \SpecialChar ~
9462 \SpecialChar ~
9463 \SpecialChar ~
9464 } while(--i);
9465 \newline
9466 \SpecialChar ~
9467 \SpecialChar ~
9468 \SpecialChar ~
9469 \SpecialChar ~
9470 return out_byte;
9471 \newline
9472 }
9473 \layout Standard
9474
9475 Then, someplace in the code for the first hardware you would use
9476 \layout Verse
9477
9478
9479 \family typewriter
9480 bit at 0x80 MOSI;\SpecialChar ~
9481 \SpecialChar ~
9482 \SpecialChar ~
9483 \SpecialChar ~
9484 /* I/O port 0, bit 0 */
9485 \newline
9486 bit at 0x81 MISO;\SpecialChar ~
9487 \SpecialChar ~
9488 \SpecialChar ~
9489 \SpecialChar ~
9490 /* I/O port 0, bit 1 */
9491 \newline
9492 bit at 0x82 MCLK;\SpecialChar ~
9493 \SpecialChar ~
9494 \SpecialChar ~
9495 \SpecialChar ~
9496 /* I/O port 0, bit 2 */
9497 \layout Standard
9498
9499 Similarly, for the second hardware you would use
9500 \layout Verse
9501
9502
9503 \family typewriter
9504 bit at 0x83 MOSI;\SpecialChar ~
9505 \SpecialChar ~
9506 \SpecialChar ~
9507 \SpecialChar ~
9508 /* I/O port 0, bit 3 */
9509 \newline
9510 bit at 0x91 MISO;\SpecialChar ~
9511 \SpecialChar ~
9512 \SpecialChar ~
9513 \SpecialChar ~
9514 /* I/O port 1, bit 1 */
9515 \newline
9516 bit
9517 \begin_inset LatexCommand \index{bit}
9518
9519 \end_inset
9520
9521  at 0x92 MCLK;\SpecialChar ~
9522 \SpecialChar ~
9523 \SpecialChar ~
9524 \SpecialChar ~
9525 /* I/O port 1, bit 2 */
9526 \layout Standard
9527
9528 and you can use the same hardware dependent routine without changes, as
9529  for example in a library.
9530  This is somehow similar to sbit, but only one absolute address has to be
9531  specified in the whole project.
9532 \layout Section
9533
9534 Parameters
9535 \begin_inset LatexCommand \index{Parameters}
9536
9537 \end_inset
9538
9539
9540 \begin_inset LatexCommand \index{function parameter}
9541
9542 \end_inset
9543
9544  & Local Variables
9545 \begin_inset LatexCommand \index{local variables}
9546
9547 \end_inset
9548
9549
9550 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
9551
9552 \end_inset
9553
9554
9555 \layout Standard
9556
9557 Automatic (local) variables and parameters to functions can either be placed
9558  on the stack or in data-space.
9559  The default action of the compiler is to place these variables in the internal
9560  RAM (for small model) or external RAM (for large model).
9561  This in fact makes them similar to
9562 \emph on
9563 static
9564 \begin_inset LatexCommand \index{static}
9565
9566 \end_inset
9567
9568
9569 \emph default
9570  so by default functions are non-reentrant
9571 \begin_inset LatexCommand \index{reentrant}
9572
9573 \end_inset
9574
9575 .
9576
9577 \newline
9578
9579 \newline
9580 They can be placed on the stack
9581 \begin_inset LatexCommand \index{stack}
9582
9583 \end_inset
9584
9585  by using the
9586 \emph on
9587  -
9588 \begin_inset ERT
9589 status Collapsed
9590
9591 \layout Standard
9592
9593 \backslash
9594 /
9595 \end_inset
9596
9597 -stack-auto
9598 \begin_inset LatexCommand \index{-\/-stack-auto}
9599
9600 \end_inset
9601
9602
9603 \emph default
9604  option, by using
9605 \emph on
9606 #pragma\SpecialChar ~
9607 stackauto
9608 \emph default
9609
9610 \begin_inset LatexCommand \index{\#pragma stackauto}
9611
9612 \end_inset
9613
9614  or by using the
9615 \emph on
9616 reentrant
9617 \begin_inset LatexCommand \index{reentrant}
9618
9619 \end_inset
9620
9621
9622 \emph default
9623  keyword in the function declaration, e.g.:
9624 \layout Verse
9625
9626
9627 \family typewriter
9628 unsigned char foo(char i) reentrant
9629 \newline
9630 {
9631 \newline
9632 \SpecialChar ~
9633 \SpecialChar ~
9634 \SpecialChar ~
9635 \SpecialChar ~
9636 ...
9637
9638 \newline
9639 }
9640 \layout Standard
9641
9642 Since stack space on 8051 is limited, the
9643 \emph on
9644 reentrant
9645 \emph default
9646 keyword or the
9647 \emph on
9648  -
9649 \begin_inset ERT
9650 status Collapsed
9651
9652 \layout Standard
9653
9654 \backslash
9655 /
9656 \end_inset
9657
9658 -stack-auto
9659 \emph default
9660  option should be used sparingly.
9661  Note that the reentrant keyword just means that the parameters & local
9662  variables will be allocated to the stack, it
9663 \emph on
9664 does not
9665 \emph default
9666  mean that the function is register bank
9667 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9668
9669 \end_inset
9670
9671  independent.
9672 \newline
9673
9674 \newline
9675 Local variables
9676 \begin_inset LatexCommand \index{local variables}
9677
9678 \end_inset
9679
9680  can be assigned storage classes and absolute
9681 \begin_inset LatexCommand \index{Absolute addressing}
9682
9683 \end_inset
9684
9685  addresses, e.g.:
9686 \layout Verse
9687
9688
9689 \family typewriter
9690 unsigned char foo()
9691 \newline
9692 {
9693 \newline
9694 \SpecialChar ~
9695 \SpecialChar ~
9696 \SpecialChar ~
9697 \SpecialChar ~
9698 xdata unsigned char i;
9699 \newline
9700 \SpecialChar ~
9701 \SpecialChar ~
9702 \SpecialChar ~
9703 \SpecialChar ~
9704 bit bvar;
9705 \newline
9706 \SpecialChar ~
9707 \SpecialChar ~
9708 \SpecialChar ~
9709 \SpecialChar ~
9710 data at
9711 \begin_inset LatexCommand \index{at}
9712
9713 \end_inset
9714
9715  0x31 unsigned char j;
9716 \newline
9717 \SpecialChar ~
9718 \SpecialChar ~
9719 \SpecialChar ~
9720 \SpecialChar ~
9721 ...
9722
9723 \newline
9724 }
9725 \layout Standard
9726
9727 In the above example the variable
9728 \emph on
9729 i
9730 \emph default
9731  will be allocated in the external ram,
9732 \emph on
9733 bvar
9734 \emph default
9735  in bit addressable space and
9736 \emph on
9737  j
9738 \emph default
9739  in internal ram.
9740  When compiled with
9741 \emph on
9742 -
9743 \begin_inset ERT
9744 status Collapsed
9745
9746 \layout Standard
9747
9748 \backslash
9749 /
9750 \end_inset
9751
9752 -stack-auto
9753 \emph default
9754  or when a function is declared as
9755 \emph on
9756 reentrant
9757 \emph default
9758  this should only be done for static variables.
9759 \layout Standard
9760
9761 Parameters
9762 \begin_inset LatexCommand \index{function parameter}
9763
9764 \end_inset
9765
9766  however are not allowed any storage class
9767 \begin_inset LatexCommand \index{Storage class}
9768
9769 \end_inset
9770
9771 , (storage classes for parameters will be ignored), their allocation is
9772  governed by the memory model in use, and the reentrancy options.
9773 \layout Section
9774
9775 Overlaying
9776 \begin_inset LatexCommand \label{sub:Overlaying}
9777
9778 \end_inset
9779
9780
9781 \begin_inset LatexCommand \index{Overlaying}
9782
9783 \end_inset
9784
9785
9786 \layout Standard
9787
9788 For non-reentrant
9789 \begin_inset LatexCommand \index{reentrant}
9790
9791 \end_inset
9792
9793  functions SDCC will try to reduce internal ram space usage by overlaying
9794  parameters and local variables of a function (if possible).
9795  Parameters and local variables
9796 \begin_inset LatexCommand \index{local variables}
9797
9798 \end_inset
9799
9800  of a function will be allocated to an overlayable segment if the function
9801  has
9802 \emph on
9803 no other function calls and the function is non-reentrant and the memory
9804  model
9805 \begin_inset LatexCommand \index{Memory model}
9806
9807 \end_inset
9808
9809  is small.
9810
9811 \emph default
9812  If an explicit storage class
9813 \begin_inset LatexCommand \index{Storage class}
9814
9815 \end_inset
9816
9817  is specified for a local variable, it will NOT be overlayed.
9818 \layout Standard
9819
9820 Note that the compiler (not the linkage editor) makes the decision for overlayin
9821 g the data items.
9822  Functions that are called from an interrupt service routine should be preceded
9823  by a #pragma\SpecialChar ~
9824 nooverlay
9825 \begin_inset LatexCommand \index{\#pragma nooverlay}
9826
9827 \end_inset
9828
9829  if they are not reentrant.
9830 \layout Standard
9831
9832 Also note that the compiler does not do any processing of inline assembler
9833  code, so the compiler might incorrectly assign local variables and parameters
9834  of a function into the overlay segment if the inline assembler code calls
9835  other c-functions that might use the overlay.
9836  In that case the #pragma\SpecialChar ~
9837 nooverlay should be used.
9838 \layout Standard
9839
9840 Parameters and local variables of functions that contain 16 or 32 bit multiplica
9841 tion
9842 \begin_inset LatexCommand \index{Multiplication}
9843
9844 \end_inset
9845
9846  or division
9847 \begin_inset LatexCommand \index{Division}
9848
9849 \end_inset
9850
9851  will NOT be overlayed since these are implemented using external functions,
9852  e.g.:
9853 \layout Verse
9854
9855
9856 \family typewriter
9857 #pragma save
9858 \newline
9859 #pragma nooverlay
9860 \begin_inset LatexCommand \index{\#pragma nooverlay}
9861
9862 \end_inset
9863
9864
9865 \newline
9866 void set_error(unsigned char errcd)
9867 \newline
9868 {
9869 \newline
9870 \SpecialChar ~
9871 \SpecialChar ~
9872 \SpecialChar ~
9873 \SpecialChar ~
9874 P3 = errcd;
9875 \newline
9876 }
9877 \newline
9878 #pragma restore
9879 \newline
9880
9881 \newline
9882 void some_isr () interrupt
9883 \begin_inset LatexCommand \index{interrupt}
9884
9885 \end_inset
9886
9887  2
9888 \newline
9889 {
9890 \newline
9891 \SpecialChar ~
9892 \SpecialChar ~
9893 \SpecialChar ~
9894 \SpecialChar ~
9895 ...
9896 \newline
9897 \SpecialChar ~
9898 \SpecialChar ~
9899 \SpecialChar ~
9900 \SpecialChar ~
9901 set_error(10);
9902 \newline
9903 \SpecialChar ~
9904 \SpecialChar ~
9905 \SpecialChar ~
9906 \SpecialChar ~
9907 ...
9908
9909 \newline
9910 }
9911 \layout Standard
9912
9913 In the above example the parameter
9914 \emph on
9915 errcd
9916 \emph default
9917  for the function
9918 \emph on
9919 set_error
9920 \emph default
9921  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
9922 nooverlay was
9923  not present, this could cause unpredictable runtime behavior when called
9924  from an interrupt service routine.
9925  The #pragma\SpecialChar ~
9926 nooverlay ensures that the parameters and local variables for
9927  the function are NOT overlayed.
9928 \layout Section
9929
9930 Interrupt Service Routines
9931 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
9932
9933 \end_inset
9934
9935
9936 \layout Subsection
9937
9938 General Information
9939 \layout Standard
9940
9941 SDCC allows
9942 \emph on
9943 i
9944 \emph default
9945 nterrupt
9946 \emph on
9947 s
9948 \emph default
9949 ervice
9950 \emph on
9951 r
9952 \emph default
9953 outines to be coded in C, with some extended keywords.
9954 \layout Verse
9955
9956
9957 \family typewriter
9958 void timer_isr (void) interrupt 1 using 1
9959 \newline
9960 {
9961 \newline
9962 \SpecialChar ~
9963 \SpecialChar ~
9964 \SpecialChar ~
9965 \SpecialChar ~
9966 ...
9967
9968 \newline
9969 }
9970 \layout Standard
9971
9972 The optional number following the
9973 \emph on
9974 interrupt
9975 \begin_inset LatexCommand \index{interrupt}
9976
9977 \end_inset
9978
9979
9980 \emph default
9981  keyword is the interrupt number this routine will service.
9982  When present, the compiler will insert a call to this routine in the interrupt
9983  vector table for the interrupt number specified.
9984  If you have multiple source files in your project, interrupt service routines
9985  can be present in any of them, but a prototype of the isr MUST be present
9986  or included in the file that contains the function
9987 \emph on
9988 main
9989 \emph default
9990 .
9991  The
9992 \emph on
9993 using
9994 \emph default
9995  keyword can be used to tell the compiler to use the specified register
9996  bank (8051 specific) when generating code for this function.
9997
9998 \newline
9999
10000 \layout Standard
10001
10002 Interrupt service routines open the door for some very interesting bugs:
10003 \newline
10004 If an interrupt service routine changes variables which are accessed by
10005  other functions these variables have to be declared
10006 \emph on
10007 volatile
10008 \emph default
10009
10010 \begin_inset LatexCommand \index{volatile}
10011
10012 \end_inset
10013
10014 .
10015
10016 \layout Standard
10017
10018 If the access to these variables is not
10019 \emph on
10020 atomic
10021 \begin_inset LatexCommand \index{atomic}
10022
10023 \end_inset
10024
10025
10026 \emph default
10027  (i.e.
10028  the processor needs more than one instruction for the access and could
10029  be interrupted while accessing the variable) the interrupt must be disabled
10030  during the access to avoid inconsistent data.
10031  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
10032  and should be protected by disabling interrupts.
10033  You're not automatically on the safe side if you use 8 bit variables though.
10034  We need an example here: f.e.
10035  on the 8051 the harmless looking
10036 \begin_inset Quotes srd
10037 \end_inset
10038
10039
10040 \family typewriter
10041 flags\SpecialChar ~
10042 |=\SpecialChar ~
10043 0x80;
10044 \family default
10045
10046 \begin_inset Quotes sld
10047 \end_inset
10048
10049  is not atomic if
10050 \family typewriter
10051 flags
10052 \family default
10053  resides in xdata.
10054  Setting
10055 \begin_inset Quotes srd
10056 \end_inset
10057
10058
10059 \family typewriter
10060 flags\SpecialChar ~
10061 |=\SpecialChar ~
10062 0x40;
10063 \family default
10064
10065 \begin_inset Quotes sld
10066 \end_inset
10067
10068  from within an interrupt routine might get lost if the interrupt occurs
10069  at the wrong time.
10070
10071 \begin_inset Quotes sld
10072 \end_inset
10073
10074
10075 \family typewriter
10076 counter\SpecialChar ~
10077 +=\SpecialChar ~
10078 8;
10079 \family default
10080
10081 \begin_inset Quotes srd
10082 \end_inset
10083
10084  is not atomic on the 8051 even if
10085 \family typewriter
10086 counter
10087 \family default
10088  is located in data memory.
10089  Bugs like these are hard to reproduce and can cause a lot of trouble.
10090
10091 \layout Standard
10092
10093 The return address and the registers used in the interrupt service routine
10094  are saved on the stack
10095 \begin_inset LatexCommand \index{stack}
10096
10097 \end_inset
10098
10099  so there must be sufficient stack space.
10100  If there isn't variables or registers (or even the return address itself)
10101  will be corrupted.
10102  This
10103 \emph on
10104 stack overflow
10105 \emph default
10106
10107 \begin_inset LatexCommand \index{stack overflow}
10108
10109 \end_inset
10110
10111  is most likely to happen if the interrupt occurs during the
10112 \begin_inset Quotes sld
10113 \end_inset
10114
10115 deepest
10116 \begin_inset Quotes srd
10117 \end_inset
10118
10119  subroutine when the stack is already in use for f.e.
10120  many return addresses.
10121 \layout Standard
10122
10123 A special note here, int (16 bit) and long (32 bit) integer division
10124 \begin_inset LatexCommand \index{Division}
10125
10126 \end_inset
10127
10128 , multiplication
10129 \begin_inset LatexCommand \index{Multiplication}
10130
10131 \end_inset
10132
10133  & modulus
10134 \begin_inset LatexCommand \index{Modulus}
10135
10136 \end_inset
10137
10138  and floating-point
10139 \begin_inset LatexCommand \index{Floating point support}
10140
10141 \end_inset
10142
10143  operations are implemented using external support routines developed in
10144  ANSI-C.
10145  If an interrupt service routine needs to do any of these operations then
10146  the support routines (as mentioned in a following section) will have to
10147  be recompiled using the
10148 \emph on
10149  -
10150 \begin_inset ERT
10151 status Collapsed
10152
10153 \layout Standard
10154
10155 \backslash
10156 /
10157 \end_inset
10158
10159 -stack-auto
10160 \begin_inset LatexCommand \index{-\/-stack-auto}
10161
10162 \end_inset
10163
10164
10165 \emph default
10166  option and the source file will need to be compiled using the
10167 \emph on
10168 -
10169 \begin_inset ERT
10170 status Collapsed
10171
10172 \layout Standard
10173
10174 \backslash
10175 /
10176 \end_inset
10177
10178 -int-long-reent
10179 \emph default
10180
10181 \begin_inset LatexCommand \index{-\/-int-long-reent}
10182
10183 \end_inset
10184
10185  compiler option.
10186 \layout Standard
10187
10188 Calling other functions from an interrupt service routine is not recommended,
10189  avoid it if possible.
10190  Note that when some function is called from an interrupt service routine
10191  it should be preceded by a #pragma\SpecialChar ~
10192 nooverlay
10193 \begin_inset LatexCommand \index{\#pragma nooverlay}
10194
10195 \end_inset
10196
10197  if it is not reentrant.
10198  Furthermore nonreentrant functions should not be called from the main program
10199  while the interrupt service routine might be active.
10200
10201 \newline
10202
10203 \newline
10204 Also see section
10205 \begin_inset LatexCommand \ref{sub:Overlaying}
10206
10207 \end_inset
10208
10209 \SpecialChar ~
10210 about Overlaying and section
10211 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10212
10213 \end_inset
10214
10215 \SpecialChar ~
10216 about Functions using private register banks.
10217 \layout Subsection
10218
10219 MCS51/DS390 Interrupt Service Routines
10220 \layout Standard
10221
10222 Interrupt numbers and the corresponding address & descriptions for the Standard
10223  8051/8052 are listed below.
10224  SDCC will automatically adjust the interrupt vector table to the maximum
10225  interrupt number specified.
10226 \newline
10227
10228 \layout Standard
10229 \align center
10230
10231 \begin_inset  Tabular
10232 <lyxtabular version="3" rows="7" columns="3">
10233 <features>
10234 <column alignment="center" valignment="top" leftline="true" width="0in">
10235 <column alignment="center" valignment="top" leftline="true" width="0in">
10236 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10237 <row topline="true" bottomline="true">
10238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10239 \begin_inset Text
10240
10241 \layout Standard
10242
10243 Interrupt #
10244 \end_inset
10245 </cell>
10246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10247 \begin_inset Text
10248
10249 \layout Standard
10250
10251 Description
10252 \end_inset
10253 </cell>
10254 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10255 \begin_inset Text
10256
10257 \layout Standard
10258
10259 Vector Address
10260 \end_inset
10261 </cell>
10262 </row>
10263 <row topline="true">
10264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10265 \begin_inset Text
10266
10267 \layout Standard
10268
10269 0
10270 \end_inset
10271 </cell>
10272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10273 \begin_inset Text
10274
10275 \layout Standard
10276
10277 External 0
10278 \end_inset
10279 </cell>
10280 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10281 \begin_inset Text
10282
10283 \layout Standard
10284
10285 0x0003
10286 \end_inset
10287 </cell>
10288 </row>
10289 <row topline="true">
10290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10291 \begin_inset Text
10292
10293 \layout Standard
10294
10295 1
10296 \end_inset
10297 </cell>
10298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10299 \begin_inset Text
10300
10301 \layout Standard
10302
10303 Timer 0
10304 \end_inset
10305 </cell>
10306 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10307 \begin_inset Text
10308
10309 \layout Standard
10310
10311 0x000B
10312 \end_inset
10313 </cell>
10314 </row>
10315 <row topline="true">
10316 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10317 \begin_inset Text
10318
10319 \layout Standard
10320
10321 2
10322 \end_inset
10323 </cell>
10324 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10325 \begin_inset Text
10326
10327 \layout Standard
10328
10329 External 1
10330 \end_inset
10331 </cell>
10332 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10333 \begin_inset Text
10334
10335 \layout Standard
10336
10337 0x0013
10338 \end_inset
10339 </cell>
10340 </row>
10341 <row topline="true">
10342 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10343 \begin_inset Text
10344
10345 \layout Standard
10346
10347 3
10348 \end_inset
10349 </cell>
10350 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10351 \begin_inset Text
10352
10353 \layout Standard
10354
10355 Timer 1
10356 \end_inset
10357 </cell>
10358 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10359 \begin_inset Text
10360
10361 \layout Standard
10362
10363 0x001B
10364 \end_inset
10365 </cell>
10366 </row>
10367 <row topline="true">
10368 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10369 \begin_inset Text
10370
10371 \layout Standard
10372
10373 4
10374 \end_inset
10375 </cell>
10376 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10377 \begin_inset Text
10378
10379 \layout Standard
10380
10381 Serial
10382 \end_inset
10383 </cell>
10384 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10385 \begin_inset Text
10386
10387 \layout Standard
10388
10389 0x0023
10390 \end_inset
10391 </cell>
10392 </row>
10393 <row topline="true" bottomline="true">
10394 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10395 \begin_inset Text
10396
10397 \layout Standard
10398
10399 5
10400 \end_inset
10401 </cell>
10402 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10403 \begin_inset Text
10404
10405 \layout Standard
10406
10407 Timer 2 (8052)
10408 \end_inset
10409 </cell>
10410 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10411 \begin_inset Text
10412
10413 \layout Standard
10414
10415 0x002B
10416 \end_inset
10417 </cell>
10418 </row>
10419 </lyxtabular>
10420
10421 \end_inset
10422
10423
10424 \newline
10425
10426 \layout Standard
10427
10428 If the interrupt service routine is defined without
10429 \emph on
10430 using
10431 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10432
10433 \end_inset
10434
10435
10436 \emph default
10437  a register bank or with register bank 0 (
10438 \emph on
10439 using
10440 \emph default
10441  0), the compiler will save the registers used by itself on the stack upon
10442  entry and restore them at exit, however if such an interrupt service routine
10443  calls another function then the entire register bank will be saved on the
10444  stack.
10445  This scheme may be advantageous for small interrupt service routines which
10446  have low register usage.
10447 \layout Standard
10448
10449 If the interrupt service routine is defined to be using a specific register
10450  bank then only
10451 \emph on
10452 a, b, dptr
10453 \emph default
10454  & psw are saved and restored, if such an interrupt service routine calls
10455  another function (using another register bank) then the entire register
10456  bank of the called function will be saved on the stack.
10457  This scheme is recommended for larger interrupt service routines.
10458 \layout Subsection
10459
10460 HC08 Interrupt Service Routines
10461 \layout Standard
10462
10463 Since the number of interrupts available is chip specific and the interrupt
10464  vector table always ends at the last byte of memory, the interrupt numbers
10465  corresponds to the interrupt vectors in reverse order of address.
10466  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
10467  2 will use the interrupt vector at 0xfffa, and so on.
10468  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
10469  this way; instead see section
10470 \begin_inset LatexCommand \ref{sub:Startup-Code}
10471
10472 \end_inset
10473
10474  for details on customizing startup.
10475 \layout Subsection
10476
10477 Z80 Interrupt Service Routines
10478 \layout Standard
10479
10480 The Z80 uses several different methods for determining the correct interrupt
10481  vector depending on the hardware implementation.
10482  Therefore, SDCC ignores the optional interrupt number and does not attempt
10483  to generate an interrupt vector table.
10484 \layout Standard
10485
10486 By default, SDCC generates code for a maskable interrupt, which uses an
10487  RETI instruction to return from the interrupt.
10488  To write an interrupt handler for the non-maskable interrupt, which needs
10489  an RETN instruction instead, add the
10490 \emph on
10491 critical
10492 \emph default
10493  keyword:
10494 \layout Verse
10495
10496
10497 \family typewriter
10498 void nmi_isr (void) critical interrupt
10499 \newline
10500 {
10501 \newline
10502 \SpecialChar ~
10503 \SpecialChar ~
10504 \SpecialChar ~
10505 \SpecialChar ~
10506 ...
10507
10508 \newline
10509 }
10510 \layout Section
10511
10512 Enabling and Disabling Interrupts
10513 \layout Subsection
10514
10515 Critical Functions and Critical Statements
10516 \layout Standard
10517
10518 A special keyword may be associated with a block or a function declaring
10519  it as
10520 \emph on
10521 critical
10522 \emph default
10523 .
10524  SDCC will generate code to disable all interrupts
10525 \begin_inset LatexCommand \index{interrupt}
10526
10527 \end_inset
10528
10529  upon entry to a critical function and restore the interrupt enable to the
10530  previous state before returning.
10531  Nesting critical functions will need one additional byte on the stack
10532 \begin_inset LatexCommand \index{stack}
10533
10534 \end_inset
10535
10536  for each call.
10537 \layout Verse
10538
10539
10540 \family typewriter
10541 int foo () critical
10542 \begin_inset LatexCommand \index{critical}
10543
10544 \end_inset
10545
10546
10547 \newline
10548 {
10549 \newline
10550 \SpecialChar ~
10551 \SpecialChar ~
10552 \SpecialChar ~
10553 \SpecialChar ~
10554 ...
10555
10556 \newline
10557 \SpecialChar ~
10558 \SpecialChar ~
10559 \SpecialChar ~
10560 \SpecialChar ~
10561 ...
10562
10563 \newline
10564 }
10565 \layout Standard
10566
10567 The critical attribute maybe used with other attributes like
10568 \emph on
10569 reentrant.
10570 \emph default
10571
10572 \newline
10573 The keyword
10574 \emph on
10575 critical
10576 \emph default
10577  may also be used to disable interrupts more locally:
10578 \layout Verse
10579
10580
10581 \family typewriter
10582 critical{ i++; }
10583 \layout Standard
10584
10585 More than one statement could have been included in the block.
10586 \layout Subsection
10587
10588 Enabling and Disabling Interrupts directly
10589 \layout Standard
10590
10591 Interrupts
10592 \begin_inset LatexCommand \index{interrupt}
10593
10594 \end_inset
10595
10596  can also be disabled and enabled directly (8051):
10597 \layout Verse
10598
10599
10600 \family typewriter
10601 EA = 0;\SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 \SpecialChar ~
10605 \SpecialChar ~
10606 \SpecialChar ~
10607 \SpecialChar ~
10608 \SpecialChar ~
10609 \SpecialChar ~
10610 \SpecialChar ~
10611 \SpecialChar ~
10612 \SpecialChar ~
10613 or:\SpecialChar ~
10614 \SpecialChar ~
10615 \SpecialChar ~
10616 \SpecialChar ~
10617 \SpecialChar ~
10618 \SpecialChar ~
10619 \SpecialChar ~
10620 \SpecialChar ~
10621 \SpecialChar ~
10622 \SpecialChar ~
10623 \SpecialChar ~
10624 EA_SAVE = EA;
10625 \layout Verse
10626
10627
10628 \family typewriter
10629 ...\SpecialChar ~
10630 \SpecialChar ~
10631 \SpecialChar ~
10632 \SpecialChar ~
10633 \SpecialChar ~
10634 \SpecialChar ~
10635 \SpecialChar ~
10636 \SpecialChar ~
10637 \SpecialChar ~
10638 \SpecialChar ~
10639 \SpecialChar ~
10640 \SpecialChar ~
10641 \SpecialChar ~
10642 \SpecialChar ~
10643 \SpecialChar ~
10644 \SpecialChar ~
10645 \SpecialChar ~
10646 \SpecialChar ~
10647 \SpecialChar ~
10648 \SpecialChar ~
10649 \SpecialChar ~
10650 \SpecialChar ~
10651 \SpecialChar ~
10652 \SpecialChar ~
10653 \SpecialChar ~
10654 \SpecialChar ~
10655 \SpecialChar ~
10656 \SpecialChar ~
10657 \SpecialChar ~
10658 \SpecialChar ~
10659 EA = 0;
10660 \layout Verse
10661
10662
10663 \family typewriter
10664 EA = 1;\SpecialChar ~
10665 \SpecialChar ~
10666 \SpecialChar ~
10667 \SpecialChar ~
10668 \SpecialChar ~
10669 \SpecialChar ~
10670 \SpecialChar ~
10671 \SpecialChar ~
10672 \SpecialChar ~
10673 \SpecialChar ~
10674 \SpecialChar ~
10675 \SpecialChar ~
10676 \SpecialChar ~
10677 \SpecialChar ~
10678 \SpecialChar ~
10679 \SpecialChar ~
10680 \SpecialChar ~
10681 \SpecialChar ~
10682 \SpecialChar ~
10683 \SpecialChar ~
10684 \SpecialChar ~
10685 \SpecialChar ~
10686 \SpecialChar ~
10687 \SpecialChar ~
10688 \SpecialChar ~
10689 \SpecialChar ~
10690 ...
10691 \layout Verse
10692
10693
10694 \family typewriter
10695 \SpecialChar ~
10696 \SpecialChar ~
10697 \SpecialChar ~
10698 \SpecialChar ~
10699 \SpecialChar ~
10700 \SpecialChar ~
10701 \SpecialChar ~
10702 \SpecialChar ~
10703 \SpecialChar ~
10704 \SpecialChar ~
10705 \SpecialChar ~
10706 \SpecialChar ~
10707 \SpecialChar ~
10708 \SpecialChar ~
10709 \SpecialChar ~
10710 \SpecialChar ~
10711 \SpecialChar ~
10712 \SpecialChar ~
10713 \SpecialChar ~
10714 \SpecialChar ~
10715 \SpecialChar ~
10716 \SpecialChar ~
10717 \SpecialChar ~
10718 \SpecialChar ~
10719 \SpecialChar ~
10720 \SpecialChar ~
10721 \SpecialChar ~
10722 \SpecialChar ~
10723 \SpecialChar ~
10724 \SpecialChar ~
10725 \SpecialChar ~
10726 \SpecialChar ~
10727 \SpecialChar ~
10728 EA = EA_SAVE;
10729 \layout Standard
10730
10731 On other architectures which have seperate opcodes for enabling and disabling
10732  interrupts you might want to make use of defines with inline assembly
10733 \begin_inset LatexCommand \index{Assembler routines}
10734
10735 \end_inset
10736
10737  (HC08):
10738 \layout Verse
10739
10740
10741 \family typewriter
10742 #define CLI _asm
10743 \begin_inset LatexCommand \index{\_asm}
10744
10745 \end_inset
10746
10747 \SpecialChar ~
10748 \SpecialChar ~
10749 cli\SpecialChar ~
10750 \SpecialChar ~
10751 _endasm
10752 \begin_inset LatexCommand \index{\_endasm}
10753
10754 \end_inset
10755
10756 ;
10757 \layout Verse
10758
10759
10760 \family typewriter
10761 #define SEI _asm\SpecialChar ~
10762 \SpecialChar ~
10763 sei\SpecialChar ~
10764 \SpecialChar ~
10765 _endasm;
10766 \layout Verse
10767
10768
10769 \family typewriter
10770 ...
10771 \layout Standard
10772
10773 Note: it is sometimes sufficient to disable only a specific interrupt source
10774  like f.e.
10775  a timer or serial interrupt by manipulating an
10776 \emph on
10777 interrupt mask
10778 \begin_inset LatexCommand \index{interrupt mask}
10779
10780 \end_inset
10781
10782
10783 \emph default
10784  register.
10785
10786 \layout Standard
10787
10788 Usually the time during which interrupts are disabled should be kept as
10789  short as possible.
10790  This minimizes both
10791 \emph on
10792 interrupt latency
10793 \emph default
10794
10795 \begin_inset LatexCommand \index{interrupt latency}
10796
10797 \end_inset
10798
10799  (the time between the occurrence of the interrupt and the execution of
10800  the first code in the interrupt routine) and
10801 \emph on
10802 interrupt jitter
10803 \emph default
10804
10805 \begin_inset LatexCommand \index{interrupt jitter}
10806
10807 \end_inset
10808
10809  (the difference between the shortest and the longest interrupt latency).
10810  These really are something different, f.e.
10811  a serial interrupt has to be served before its buffer overruns so it cares
10812  for the maximum interrupt latency, whereas it does not care about jitter.
10813  On a loudspeaker driven via a digital to analog converter which is fed
10814  by an interrupt a latency of a few milliseconds might be tolerable, whereas
10815  a much smaller jitter will be very audible.
10816 \layout Standard
10817
10818 You can reenable interrupts within an interrupt routine and on some architecture
10819 s you can make use of two (or more) levels of
10820 \emph on
10821 interrupt priorities
10822 \emph default
10823
10824 \begin_inset LatexCommand \index{interrupt priority}
10825
10826 \end_inset
10827
10828 .
10829  On some architectures which don't support interrupt priorities these can
10830  be implemented by manipulating the interrupt mask and reenabling interrupts
10831  within the interrupt routine.
10832  Check there is sufficient space on the stack
10833 \begin_inset LatexCommand \index{stack}
10834
10835 \end_inset
10836
10837  and don't add complexity unless you have to.
10838
10839 \layout Subsection
10840
10841 Semaphore
10842 \begin_inset LatexCommand \index{semaphore}
10843
10844 \end_inset
10845
10846  locking (mcs51/ds390)
10847 \layout Standard
10848
10849 Some architectures (mcs51/ds390) have an atomic
10850 \begin_inset LatexCommand \index{atomic}
10851
10852 \end_inset
10853
10854  bit test and
10855 \emph on
10856
10857 \emph default
10858 clear
10859 \emph on
10860
10861 \emph default
10862 instruction.
10863  These type of instructions are typically used in preemptive multitasking
10864  systems, where a routine f.e.
10865  claims the use of a data structure ('acquires a lock
10866 \begin_inset LatexCommand \index{lock}
10867
10868 \end_inset
10869
10870  on it'), makes some modifications and then releases the lock when the data
10871  structure is consistent again.
10872  The instruction may also be used if interrupt and non-interrupt code have
10873  to compete for a resource.
10874  With the atomic bit test and clear instruction interrupts
10875 \begin_inset LatexCommand \index{interrupt}
10876
10877 \end_inset
10878
10879  don't have to be disabled for the locking operation.
10880
10881 \layout Standard
10882
10883 SDCC generates this instruction if the source follows this pattern:
10884 \layout Verse
10885
10886
10887 \family typewriter
10888 volatile bit resource_is_free;
10889 \newline
10890
10891 \newline
10892 if (resource_is_free)
10893 \newline
10894 \SpecialChar ~
10895 \SpecialChar ~
10896 {
10897 \newline
10898 \SpecialChar ~
10899 \SpecialChar ~
10900 \SpecialChar ~
10901 \SpecialChar ~
10902 resource_is_free=0;
10903 \newline
10904 \SpecialChar ~
10905 \SpecialChar ~
10906 \SpecialChar ~
10907 \SpecialChar ~
10908 ...
10909
10910 \newline
10911 \SpecialChar ~
10912 \SpecialChar ~
10913 \SpecialChar ~
10914 \SpecialChar ~
10915 resource_is_free=1;
10916 \newline
10917 \SpecialChar ~
10918 \SpecialChar ~
10919 }
10920 \layout Standard
10921
10922 Note, mcs51 and ds390 support only an atomic
10923 \begin_inset LatexCommand \index{atomic}
10924
10925 \end_inset
10926
10927  bit test and
10928 \emph on
10929 clear
10930 \emph default
10931  instruction (as opposed to atomic bit test and
10932 \emph on
10933 set).
10934 \layout Section
10935
10936 Functions using private register banks
10937 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
10938
10939 \end_inset
10940
10941  (mcs51/ds390)
10942 \layout Standard
10943
10944 Some architectures have support for quickly changing register sets.
10945  SDCC supports this feature with the
10946 \emph on
10947 using
10948 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10949
10950 \end_inset
10951
10952
10953 \emph default
10954  attribute (which tells the compiler to use a register bank
10955 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10956
10957 \end_inset
10958
10959  other than the default bank zero).
10960  It should only be applied to
10961 \emph on
10962 interrupt
10963 \begin_inset LatexCommand \index{interrupt}
10964
10965 \end_inset
10966
10967
10968 \emph default
10969  functions (see footnote below).
10970  This will in most circumstances make the generated ISR code more efficient
10971  since it will not have to save registers on the stack.
10972 \layout Standard
10973
10974 The
10975 \emph on
10976 using
10977 \emph default
10978  attribute will have no effect on the generated code for a
10979 \emph on
10980 non-interrupt
10981 \emph default
10982  function (but may occasionally be useful anyway
10983 \begin_inset Foot
10984 collapsed false
10985
10986 \layout Standard
10987
10988 possible exception: if a function is called ONLY from 'interrupt' functions
10989  using a particular bank, it can be declared with the same 'using' attribute
10990  as the calling 'interrupt' functions.
10991  For instance, if you have several ISRs using bank one, and all of them
10992  call memcpy(), it might make sense to create a specialized version of memcpy()
10993  'using 1', since this would prevent the ISR from having to save bank zero
10994  to the stack on entry and switch to bank zero before calling the function
10995 \end_inset
10996
10997 ).
10998 \newline
10999
11000 \emph on
11001 (pending: I don't think this has been done yet)
11002 \layout Standard
11003
11004 An
11005 \emph on
11006 interrupt
11007 \emph default
11008  function using a non-zero bank will assume that it can trash that register
11009  bank, and will not save it.
11010  Since high-priority interrupts
11011 \begin_inset LatexCommand \index{interrupt priority}
11012
11013 \end_inset
11014
11015  can interrupt low-priority ones on the 8051 and friends, this means that
11016  if a high-priority ISR
11017 \emph on
11018 using
11019 \emph default
11020  a particular bank occurs while processing a low-priority ISR
11021 \emph on
11022 using
11023 \emph default
11024  the same bank, terrible and bad things can happen.
11025  To prevent this, no single register bank should be
11026 \emph on
11027 used
11028 \emph default
11029  by both a high priority and a low priority ISR.
11030  This is probably most easily done by having all high priority ISRs use
11031  one bank and all low priority ISRs use another.
11032  If you have an ISR which can change priority at runtime, you're on your
11033  own: I suggest using the default bank zero and taking the small performance
11034  hit.
11035 \layout Standard
11036
11037 It is most efficient if your ISR calls no other functions.
11038  If your ISR must call other functions, it is most efficient if those functions
11039  use the same bank as the ISR (see note 1 below); the next best is if the
11040  called functions use bank zero.
11041  It is very inefficient to call a function using a different, non-zero bank
11042  from an ISR.
11043
11044 \layout Section
11045
11046 Startup Code
11047 \begin_inset LatexCommand \label{sub:Startup-Code}
11048
11049 \end_inset
11050
11051
11052 \begin_inset LatexCommand \index{Startup code}
11053
11054 \end_inset
11055
11056
11057 \layout Subsection
11058
11059 MCS51/DS390 Startup Code
11060 \layout Standard
11061
11062 The compiler inserts a call to the C routine
11063 \emph on
11064 _sdcc_external_startup()
11065 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
11066
11067 \end_inset
11068
11069
11070 \series bold
11071 \emph default
11072
11073 \series default
11074 at the start of the CODE area.
11075  This routine is in the runtime library
11076 \begin_inset LatexCommand \index{Runtime library}
11077
11078 \end_inset
11079
11080 .
11081  By default this routine returns 0, if this routine returns a non-zero value,
11082  the static & global variable initialization will be skipped and the function
11083  main will be invoked.
11084  Otherwise static & global variables will be initialized before the function
11085  main is invoked.
11086  You could add a
11087 \emph on
11088 _sdcc_external_startup()
11089 \emph default
11090  routine to your program to override the default if you need to setup hardware
11091  or perform some other critical operation prior to static & global variable
11092  initialization.
11093  On some mcs51 variants xdata has to be explicitly enabled before it can
11094  be accessed or if the watchdog needs to be disabled, this is the place
11095  to do it.
11096  The startup code clears all internal data memory, 256 bytes by default,
11097  but from 0 to n-1 if
11098 \emph on
11099 -
11100 \begin_inset ERT
11101 status Collapsed
11102
11103 \layout Standard
11104
11105 \backslash
11106 /
11107 \end_inset
11108
11109 -iram-size
11110 \begin_inset LatexCommand \index{-\/-iram-size}
11111
11112 \end_inset
11113
11114 n
11115 \emph default
11116  is used.
11117  (recommended for Chipcon CC1010).
11118 \layout Standard
11119
11120 See also the compiler option
11121 \emph on
11122 -
11123 \begin_inset ERT
11124 status Collapsed
11125
11126 \layout Standard
11127
11128 \backslash
11129 /
11130 \end_inset
11131
11132 -no-xinit
11133 \emph default
11134 -
11135 \emph on
11136 opt
11137 \emph default
11138
11139 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11140
11141 \end_inset
11142
11143  and section
11144 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11145
11146 \end_inset
11147
11148 \SpecialChar ~
11149 about MCS51-variants.
11150 \layout Subsection
11151
11152 HC08 Startup Code
11153 \layout Standard
11154
11155 The HC08 startup code follows the same scheme as the MCS51 startup code.
11156 \layout Subsection
11157
11158 Z80 Startup Code
11159 \layout Standard
11160
11161 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11162  from sdcc/device/lib/z80/crt0.s.
11163  If you need a different startup code you can use the compiler option
11164 \emph on
11165 -
11166 \series bold
11167 \emph default
11168
11169 \begin_inset ERT
11170 status Collapsed
11171
11172 \layout Standard
11173
11174 \backslash
11175 /
11176 \end_inset
11177
11178
11179 \series default
11180 \emph on
11181 -no-std-crt0
11182 \emph default
11183
11184 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11185
11186 \end_inset
11187
11188  and provide your own crt0.o.
11189
11190 \layout Section
11191
11192 Inline Assembler Code
11193 \begin_inset LatexCommand \index{Assembler routines}
11194
11195 \end_inset
11196
11197
11198 \layout Subsection
11199
11200 A Step by Step Introduction
11201 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11202
11203 \end_inset
11204
11205
11206 \layout Standard
11207
11208 Starting from a small snippet of c-code this example shows for the MCS51
11209  how to use inline assembly, access variables, a function parameter and
11210  an array in xdata memory.
11211  The example uses an MCS51 here but is easily adapted for other architectures.
11212  This is a buffer routine which should be optimized:
11213 \layout Verse
11214
11215
11216 \family typewriter
11217 \size footnotesize
11218 unsigned char far
11219 \begin_inset LatexCommand \index{far (storage class)}
11220
11221 \end_inset
11222
11223  at
11224 \begin_inset LatexCommand \index{at}
11225
11226 \end_inset
11227
11228  0x7f00 buf[0x100];
11229 \begin_inset LatexCommand \index{Aligned array}
11230
11231 \end_inset
11232
11233
11234 \newline
11235 unsigned char head,tail;
11236 \newline
11237
11238 \newline
11239 void to_buffer( unsigned char c )
11240 \newline
11241 {
11242 \newline
11243 \SpecialChar ~
11244 \SpecialChar ~
11245 \SpecialChar ~
11246 \SpecialChar ~
11247 if( head != tail-1 )
11248 \newline
11249 \SpecialChar ~
11250 \SpecialChar ~
11251 \SpecialChar ~
11252 \SpecialChar ~
11253 \SpecialChar ~
11254 \SpecialChar ~
11255 \SpecialChar ~
11256 \SpecialChar ~
11257 buf[ head++ ] = c;\SpecialChar ~
11258 \SpecialChar ~
11259 \SpecialChar ~
11260 \SpecialChar ~
11261 /* access to a 256 byte aligned array */
11262 \newline
11263 }
11264 \layout Standard
11265
11266 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11267  then a corresponding buffer.asm file is generated.
11268  We define a new function
11269 \family typewriter
11270 to_buffer_asm()
11271 \family default
11272  in file buffer.c in which we cut and paste the generated code, removing
11273  unwanted comments and some ':'.
11274  Then add
11275 \begin_inset Quotes sld
11276 \end_inset
11277
11278 _asm
11279 \begin_inset Quotes srd
11280 \end_inset
11281
11282  and
11283 \begin_inset Quotes sld
11284 \end_inset
11285
11286 _endasm;
11287 \begin_inset Quotes srd
11288 \end_inset
11289
11290  to the beginning and the end of the function body:
11291 \layout Verse
11292
11293
11294 \family typewriter
11295 \size footnotesize
11296 /* With a cut and paste from the .asm file, we have something to start with.
11297 \newline
11298 \SpecialChar ~
11299 \SpecialChar ~
11300 \SpecialChar ~
11301 The function is not yet OK! (registers aren't saved) */
11302 \newline
11303 void to_buffer_asm( unsigned char c )
11304 \newline
11305 {
11306 \newline
11307 \SpecialChar ~
11308 \SpecialChar ~
11309 \SpecialChar ~
11310 \SpecialChar ~
11311 _asm
11312 \begin_inset LatexCommand \index{\_asm}
11313
11314 \end_inset
11315
11316
11317 \newline
11318 \SpecialChar ~
11319 \SpecialChar ~
11320 \SpecialChar ~
11321 \SpecialChar ~
11322 mov\SpecialChar ~
11323 \SpecialChar ~
11324 r2,dpl
11325 \newline
11326 ;buffer.c if( head != tail-1 )
11327 \newline
11328 \SpecialChar ~
11329 \SpecialChar ~
11330 \SpecialChar ~
11331 \SpecialChar ~
11332 mov\SpecialChar ~
11333 \SpecialChar ~
11334 a,_tail
11335 \newline
11336 \SpecialChar ~
11337 \SpecialChar ~
11338 \SpecialChar ~
11339 \SpecialChar ~
11340 dec\SpecialChar ~
11341 \SpecialChar ~
11342 a
11343 \newline
11344 \SpecialChar ~
11345 \SpecialChar ~
11346 \SpecialChar ~
11347 \SpecialChar ~
11348 mov\SpecialChar ~
11349 \SpecialChar ~
11350 r3,a
11351 \newline
11352 \SpecialChar ~
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 mov\SpecialChar ~
11357 \SpecialChar ~
11358 a,_head
11359 \newline
11360 \SpecialChar ~
11361 \SpecialChar ~
11362 \SpecialChar ~
11363 \SpecialChar ~
11364 cjne a,ar3,00106$
11365 \newline
11366 \SpecialChar ~
11367 \SpecialChar ~
11368 \SpecialChar ~
11369 \SpecialChar ~
11370 ret
11371 \newline
11372 00106$:
11373 \newline
11374 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
11375 \begin_inset LatexCommand \index{Aligned array}
11376
11377 \end_inset
11378
11379
11380 \newline
11381 \SpecialChar ~
11382 \SpecialChar ~
11383 \SpecialChar ~
11384 \SpecialChar ~
11385 mov\SpecialChar ~
11386 \SpecialChar ~
11387 r3,_head
11388 \newline
11389 \SpecialChar ~
11390 \SpecialChar ~
11391 \SpecialChar ~
11392 \SpecialChar ~
11393 inc\SpecialChar ~
11394 \SpecialChar ~
11395 _head
11396 \newline
11397 \SpecialChar ~
11398 \SpecialChar ~
11399 \SpecialChar ~
11400 \SpecialChar ~
11401 mov\SpecialChar ~
11402 \SpecialChar ~
11403 dpl,r3
11404 \newline
11405 \SpecialChar ~
11406 \SpecialChar ~
11407 \SpecialChar ~
11408 \SpecialChar ~
11409 mov\SpecialChar ~
11410 \SpecialChar ~
11411 dph,#(_buf >> 8)
11412 \newline
11413 \SpecialChar ~
11414 \SpecialChar ~
11415 \SpecialChar ~
11416 \SpecialChar ~
11417 mov\SpecialChar ~
11418 \SpecialChar ~
11419 a,r2
11420 \newline
11421 \SpecialChar ~
11422 \SpecialChar ~
11423 \SpecialChar ~
11424 \SpecialChar ~
11425 movx @dptr,a
11426 \newline
11427 00103$:
11428 \newline
11429 \SpecialChar ~
11430 \SpecialChar ~
11431 \SpecialChar ~
11432 \SpecialChar ~
11433 ret
11434 \newline
11435 \SpecialChar ~
11436 \SpecialChar ~
11437 \SpecialChar ~
11438 \SpecialChar ~
11439 _endasm;
11440 \newline
11441 }
11442 \layout Standard
11443
11444 The new file buffer.c should compile with only one warning about the unreferenced
11445  function argument 'c'.
11446  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
11447  (1) and finally have:
11448 \layout Verse
11449
11450
11451 \family typewriter
11452 \size footnotesize
11453 unsigned char far at 0x7f00 buf[0x100];
11454 \newline
11455 unsigned char head,tail;
11456 \newline
11457 #define USE_ASSEMBLY (1)
11458 \newline
11459
11460 \newline
11461 #if !USE_ASSEMBLY
11462 \newline
11463
11464 \newline
11465 void to_buffer( unsigned char c )
11466 \newline
11467 {
11468 \newline
11469 \SpecialChar ~
11470 \SpecialChar ~
11471 \SpecialChar ~
11472 \SpecialChar ~
11473 if( head != tail-1 )
11474 \newline
11475 \SpecialChar ~
11476 \SpecialChar ~
11477 \SpecialChar ~
11478 \SpecialChar ~
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 \SpecialChar ~
11482 \SpecialChar ~
11483 buf[ head++ ] = c;
11484 \newline
11485 }
11486 \newline
11487
11488 \newline
11489 #else
11490 \newline
11491
11492 \newline
11493 void to_buffer( unsigned char c )
11494 \newline
11495 {
11496 \newline
11497 \SpecialChar ~
11498 \SpecialChar ~
11499 \SpecialChar ~
11500 \SpecialChar ~
11501 c; // to avoid warning: unreferenced function argument
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 \SpecialChar ~
11519 \SpecialChar ~
11520 \SpecialChar ~
11521 \SpecialChar ~
11522 ; save used registers here.
11523
11524 \newline
11525 \SpecialChar ~
11526 \SpecialChar ~
11527 \SpecialChar ~
11528 \SpecialChar ~
11529 \SpecialChar ~
11530 \SpecialChar ~
11531 \SpecialChar ~
11532 \SpecialChar ~
11533 ; If we were still using r2,r3 we would have to push them here.
11534
11535 \newline
11536 ; if( head != tail-1 )
11537 \newline
11538 \SpecialChar ~
11539 \SpecialChar ~
11540 \SpecialChar ~
11541 \SpecialChar ~
11542 \SpecialChar ~
11543 \SpecialChar ~
11544 \SpecialChar ~
11545 \SpecialChar ~
11546 mov\SpecialChar ~
11547  a,_tail
11548 \newline
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 \SpecialChar ~
11553 \SpecialChar ~
11554 \SpecialChar ~
11555 \SpecialChar ~
11556 \SpecialChar ~
11557 dec\SpecialChar ~
11558  a
11559 \newline
11560 \SpecialChar ~
11561 \SpecialChar ~
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 \SpecialChar ~
11566 \SpecialChar ~
11567 \SpecialChar ~
11568 xrl\SpecialChar ~
11569  a,_head
11570 \newline
11571 \SpecialChar ~
11572 \SpecialChar ~
11573 \SpecialChar ~
11574 \SpecialChar ~
11575 \SpecialChar ~
11576 \SpecialChar ~
11577 \SpecialChar ~
11578 \SpecialChar ~
11579 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
11580 \newline
11581 \SpecialChar ~
11582 \SpecialChar ~
11583 \SpecialChar ~
11584 \SpecialChar ~
11585 \SpecialChar ~
11586 \SpecialChar ~
11587 \SpecialChar ~
11588 \SpecialChar ~
11589 jz\SpecialChar ~
11590 \SpecialChar ~
11591  t_b_end$
11592 \newline
11593 \SpecialChar ~
11594 \SpecialChar ~
11595 \SpecialChar ~
11596 \SpecialChar ~
11597 \SpecialChar ~
11598 \SpecialChar ~
11599 \SpecialChar ~
11600 \SpecialChar ~
11601 ;
11602 \newline
11603 ; buf[ head++ ] = c;
11604 \newline
11605 \SpecialChar ~
11606 \SpecialChar ~
11607 \SpecialChar ~
11608 \SpecialChar ~
11609 \SpecialChar ~
11610 \SpecialChar ~
11611 \SpecialChar ~
11612 \SpecialChar ~
11613 mov\SpecialChar ~
11614  a,dpl \SpecialChar ~
11615 \SpecialChar ~
11616 \SpecialChar ~
11617 \SpecialChar ~
11618 \SpecialChar ~
11619 \SpecialChar ~
11620 \SpecialChar ~
11621 ; dpl holds lower byte of function argument
11622 \newline
11623 \SpecialChar ~
11624 \SpecialChar ~
11625 \SpecialChar ~
11626 \SpecialChar ~
11627 \SpecialChar ~
11628 \SpecialChar ~
11629 \SpecialChar ~
11630 \SpecialChar ~
11631 mov\SpecialChar ~
11632  dpl,_head \SpecialChar ~
11633 \SpecialChar ~
11634 \SpecialChar ~
11635 ; buf is 0x100 byte aligned so head can be used directly
11636 \newline
11637 \SpecialChar ~
11638 \SpecialChar ~
11639 \SpecialChar ~
11640 \SpecialChar ~
11641 \SpecialChar ~
11642 \SpecialChar ~
11643 \SpecialChar ~
11644 \SpecialChar ~
11645 mov\SpecialChar ~
11646  dph,#(_buf>>8)
11647 \newline
11648 \SpecialChar ~
11649 \SpecialChar ~
11650 \SpecialChar ~
11651 \SpecialChar ~
11652 \SpecialChar ~
11653 \SpecialChar ~
11654 \SpecialChar ~
11655 \SpecialChar ~
11656 movx @dptr,a
11657 \newline
11658 \SpecialChar ~
11659 \SpecialChar ~
11660 \SpecialChar ~
11661 \SpecialChar ~
11662 \SpecialChar ~
11663 \SpecialChar ~
11664 \SpecialChar ~
11665 \SpecialChar ~
11666 inc \SpecialChar ~
11667 _head
11668 \newline
11669 \SpecialChar ~
11670 \SpecialChar ~
11671 \SpecialChar ~
11672 \SpecialChar ~
11673 \SpecialChar ~
11674 \SpecialChar ~
11675 \SpecialChar ~
11676 \SpecialChar ~
11677 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
11678 \newline
11679 t_b_end$:
11680 \newline
11681 \SpecialChar ~
11682 \SpecialChar ~
11683 \SpecialChar ~
11684 \SpecialChar ~
11685 \SpecialChar ~
11686 \SpecialChar ~
11687 \SpecialChar ~
11688 \SpecialChar ~
11689 ; restore used registers here
11690 \newline
11691 \SpecialChar ~
11692 \SpecialChar ~
11693 \SpecialChar ~
11694 \SpecialChar ~
11695 _endasm;
11696 \newline
11697 }
11698 \newline
11699 #endif
11700 \layout Standard
11701
11702 The inline assembler code can contain any valid code understood by the assembler
11703 , this includes any assembler directives and comment lines
11704 \begin_inset Foot
11705 collapsed false
11706
11707 \layout Standard
11708
11709 The assembler does not like some characters like ':' or ''' in comments.
11710  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
11711 \end_inset
11712
11713 .
11714  The compiler does not do any validation of the code within the
11715 \family typewriter
11716 _asm
11717 \begin_inset LatexCommand \index{\_asm}
11718
11719 \end_inset
11720
11721  ...
11722  _endasm;
11723 \family default
11724  keyword pair.
11725  Specifically it will not know which registers are used and thus register
11726  pushing/popping
11727 \begin_inset LatexCommand \index{push/pop}
11728
11729 \end_inset
11730
11731  has to be done manually.
11732
11733 \layout Standard
11734
11735 It is recommended that each assembly instruction (including labels) be placed
11736  in a separate line (as the example shows).
11737  When the -
11738 \begin_inset ERT
11739 status Collapsed
11740
11741 \layout Standard
11742
11743 \backslash
11744 /
11745 \end_inset
11746
11747 -
11748 \emph on
11749 peep-asm
11750 \begin_inset LatexCommand \index{-\/-peep-asm}
11751
11752 \end_inset
11753
11754
11755 \emph default
11756  command line option is used, the inline assembler code will be passed through
11757  the peephole optimizer
11758 \begin_inset LatexCommand \index{Peephole optimizer}
11759
11760 \end_inset
11761
11762 .
11763  There are only a few (if any) cases where this option makes sense, it might
11764  cause some unexpected changes in the inline assembler code.
11765  Please go through the peephole optimizer rules defined in file
11766 \emph on
11767 SDCCpeeph.def
11768 \emph default
11769  before using this option.
11770 \layout Subsection
11771
11772 Naked Functions
11773 \begin_inset LatexCommand \label{sub:Naked-Functions}
11774
11775 \end_inset
11776
11777
11778 \begin_inset LatexCommand \index{Naked functions}
11779
11780 \end_inset
11781
11782
11783 \layout Standard
11784
11785 A special keyword may be associated with a function declaring it as
11786 \emph on
11787 _naked
11788 \begin_inset LatexCommand \index{\_naked}
11789
11790 \end_inset
11791
11792 .
11793
11794 \emph default
11795 The
11796 \emph on
11797 _naked
11798 \emph default
11799  function modifier attribute prevents the compiler from generating prologue
11800 \begin_inset LatexCommand \index{function prologue}
11801
11802 \end_inset
11803
11804  and epilogue
11805 \begin_inset LatexCommand \index{function epilogue}
11806
11807 \end_inset
11808
11809  code for that function.
11810  This means that the user is entirely responsible for such things as saving
11811  any registers that may need to be preserved, selecting the proper register
11812  bank, generating the
11813 \emph on
11814 return
11815 \emph default
11816  instruction at the end, etc.
11817  Practically, this means that the contents of the function must be written
11818  in inline assembler.
11819  This is particularly useful for interrupt functions, which can have a large
11820  (and often unnecessary) prologue/epilogue.
11821  For example, compare the code generated by these two functions:
11822 \layout Verse
11823
11824
11825 \family typewriter
11826 volatile
11827 \begin_inset LatexCommand \index{volatile}
11828
11829 \end_inset
11830
11831  data unsigned char counter;
11832 \newline
11833
11834 \newline
11835 void simpleInterrupt(void) interrupt
11836 \begin_inset LatexCommand \index{interrupt}
11837
11838 \end_inset
11839
11840  1
11841 \newline
11842 {
11843 \newline
11844 \SpecialChar ~
11845 \SpecialChar ~
11846 \SpecialChar ~
11847 \SpecialChar ~
11848 counter++;
11849 \newline
11850 }
11851 \newline
11852
11853 \newline
11854 void nakedInterrupt(void) interrupt 2 _naked
11855 \newline
11856 {
11857 \newline
11858 \SpecialChar ~
11859 \SpecialChar ~
11860 \SpecialChar ~
11861 \SpecialChar ~
11862 _asm
11863 \begin_inset LatexCommand \index{\_asm}
11864
11865 \end_inset
11866
11867
11868 \newline
11869 \SpecialChar ~
11870 \SpecialChar ~
11871 \SpecialChar ~
11872 \SpecialChar ~
11873 \SpecialChar ~
11874 \SpecialChar ~
11875 inc\SpecialChar ~
11876 \SpecialChar ~
11877 \SpecialChar ~
11878 \SpecialChar ~
11879 \SpecialChar ~
11880 _counter ; does not change flags, no need to save psw
11881 \newline
11882 \SpecialChar ~
11883 \SpecialChar ~
11884 \SpecialChar ~
11885 \SpecialChar ~
11886 \SpecialChar ~
11887 \SpecialChar ~
11888 reti\SpecialChar ~
11889 \SpecialChar ~
11890 \SpecialChar ~
11891 \SpecialChar ~
11892 ; MUST explicitly include ret or reti in _naked function.
11893 \newline
11894 \SpecialChar ~
11895 \SpecialChar ~
11896 \SpecialChar ~
11897 \SpecialChar ~
11898 _endasm
11899 \begin_inset LatexCommand \index{\_endasm}
11900
11901 \end_inset
11902
11903 ;
11904 \newline
11905 }
11906 \layout Standard
11907
11908 For an 8051 target, the generated simpleInterrupt looks like:
11909 \layout Verse
11910
11911
11912 \family typewriter
11913 _simpleInterrupt:
11914 \newline
11915 \SpecialChar ~
11916 \SpecialChar ~
11917 \SpecialChar ~
11918 \SpecialChar ~
11919 push\SpecialChar ~
11920 \SpecialChar ~
11921 \SpecialChar ~
11922 \SpecialChar ~
11923 acc
11924 \newline
11925 \SpecialChar ~
11926 \SpecialChar ~
11927 \SpecialChar ~
11928 \SpecialChar ~
11929 push\SpecialChar ~
11930 \SpecialChar ~
11931 \SpecialChar ~
11932 \SpecialChar ~
11933 b
11934 \newline
11935 \SpecialChar ~
11936 \SpecialChar ~
11937 \SpecialChar ~
11938 \SpecialChar ~
11939 push\SpecialChar ~
11940 \SpecialChar ~
11941 \SpecialChar ~
11942 \SpecialChar ~
11943 dpl
11944 \newline
11945 \SpecialChar ~
11946 \SpecialChar ~
11947 \SpecialChar ~
11948 \SpecialChar ~
11949 push\SpecialChar ~
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 dph
11954 \newline
11955 \SpecialChar ~
11956 \SpecialChar ~
11957 \SpecialChar ~
11958 \SpecialChar ~
11959 push\SpecialChar ~
11960 \SpecialChar ~
11961 \SpecialChar ~
11962 \SpecialChar ~
11963 psw
11964 \newline
11965 \SpecialChar ~
11966 \SpecialChar ~
11967 \SpecialChar ~
11968 \SpecialChar ~
11969 mov\SpecialChar ~
11970 \SpecialChar ~
11971 \SpecialChar ~
11972 \SpecialChar ~
11973 \SpecialChar ~
11974 psw,#0x00
11975 \newline
11976 \SpecialChar ~
11977 \SpecialChar ~
11978 \SpecialChar ~
11979 \SpecialChar ~
11980 inc\SpecialChar ~
11981 \SpecialChar ~
11982 \SpecialChar ~
11983 \SpecialChar ~
11984 \SpecialChar ~
11985 _counter
11986 \newline
11987 \SpecialChar ~
11988 \SpecialChar ~
11989 \SpecialChar ~
11990 \SpecialChar ~
11991 pop\SpecialChar ~
11992 \SpecialChar ~
11993 \SpecialChar ~
11994 \SpecialChar ~
11995 \SpecialChar ~
11996 psw
11997 \newline
11998 \SpecialChar ~
11999 \SpecialChar ~
12000 \SpecialChar ~
12001 \SpecialChar ~
12002 pop\SpecialChar ~
12003 \SpecialChar ~
12004 \SpecialChar ~
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 dph
12008 \newline
12009 \SpecialChar ~
12010 \SpecialChar ~
12011 \SpecialChar ~
12012 \SpecialChar ~
12013 pop\SpecialChar ~
12014 \SpecialChar ~
12015 \SpecialChar ~
12016 \SpecialChar ~
12017 \SpecialChar ~
12018 dpl
12019 \newline
12020 \SpecialChar ~
12021 \SpecialChar ~
12022 \SpecialChar ~
12023 \SpecialChar ~
12024 pop\SpecialChar ~
12025 \SpecialChar ~
12026 \SpecialChar ~
12027 \SpecialChar ~
12028 \SpecialChar ~
12029 b
12030 \newline
12031 \SpecialChar ~
12032 \SpecialChar ~
12033 \SpecialChar ~
12034 \SpecialChar ~
12035 pop\SpecialChar ~
12036 \SpecialChar ~
12037 \SpecialChar ~
12038 \SpecialChar ~
12039 \SpecialChar ~
12040 acc
12041 \newline
12042 \SpecialChar ~
12043 \SpecialChar ~
12044 \SpecialChar ~
12045 \SpecialChar ~
12046 reti
12047 \layout Standard
12048
12049 whereas nakedInterrupt looks like:
12050 \layout Verse
12051
12052
12053 \family typewriter
12054 _nakedInterrupt:
12055 \newline
12056 \SpecialChar ~
12057 \SpecialChar ~
12058 \SpecialChar ~
12059 \SpecialChar ~
12060 inc\SpecialChar ~
12061 \SpecialChar ~
12062 \SpecialChar ~
12063 \SpecialChar ~
12064 _counter ; does not change flags, no need to save psw
12065 \newline
12066 \SpecialChar ~
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 reti\SpecialChar ~
12071 \SpecialChar ~
12072 \SpecialChar ~
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 \SpecialChar ~
12076 \SpecialChar ~
12077 \SpecialChar ~
12078 \SpecialChar ~
12079 \SpecialChar ~
12080 \SpecialChar ~
12081 \SpecialChar ~
12082 ; MUST explicitly include ret or reti in _naked function
12083 \layout Standard
12084
12085 The related directive #pragma exclude
12086 \begin_inset LatexCommand \index{\#pragma exclude}
12087
12088 \end_inset
12089
12090  allows a more fine grained control over pushing & popping
12091 \begin_inset LatexCommand \index{push/pop}
12092
12093 \end_inset
12094
12095  the registers.
12096 \layout Standard
12097
12098 While there is nothing preventing you from writing C code inside a
12099 \family typewriter
12100 _naked
12101 \family default
12102  function, there are many ways to shoot yourself in the foot doing this,
12103  and it is recommended that you stick to inline assembler.
12104 \layout Subsection
12105
12106 Use of Labels within Inline Assembler
12107 \layout Standard
12108
12109 SDCC allows the use of in-line assembler with a few restrictions regarding
12110  labels.
12111  In older versions of the compiler all labels defined within inline assembler
12112  code
12113 \emph on
12114 had to be
12115 \emph default
12116  of the form
12117 \emph on
12118 nnnnn$
12119 \emph default
12120  where nnnn is a number less than 100 (which implies a limit of utmost 100
12121  inline assembler labels
12122 \emph on
12123 per function
12124 \emph default
12125 \noun on
12126 )
12127 \noun default
12128 .
12129
12130 \layout Verse
12131
12132
12133 \family typewriter
12134 _asm
12135 \begin_inset LatexCommand \index{\_asm}
12136
12137 \end_inset
12138
12139
12140 \newline
12141 \SpecialChar ~
12142 \SpecialChar ~
12143 \SpecialChar ~
12144 \SpecialChar ~
12145 mov\SpecialChar ~
12146 \SpecialChar ~
12147 \SpecialChar ~
12148 \SpecialChar ~
12149 \SpecialChar ~
12150 b,#10
12151 \newline
12152 00001$:
12153 \newline
12154 \SpecialChar ~
12155 \SpecialChar ~
12156 \SpecialChar ~
12157 \SpecialChar ~
12158 djnz\SpecialChar ~
12159 \SpecialChar ~
12160 \SpecialChar ~
12161 \SpecialChar ~
12162 b,00001$
12163 \newline
12164 _endasm
12165 \begin_inset LatexCommand \index{\_endasm}
12166
12167 \end_inset
12168
12169  ;
12170 \layout Standard
12171
12172 Inline assembler code cannot reference any C-Labels, however it can reference
12173  labels
12174 \begin_inset LatexCommand \index{Labels}
12175
12176 \end_inset
12177
12178  defined by the inline assembler, e.g.:
12179 \layout Verse
12180
12181
12182 \family typewriter
12183 foo() {
12184 \newline
12185 \SpecialChar ~
12186 \SpecialChar ~
12187 \SpecialChar ~
12188 \SpecialChar ~
12189 /* some c code */
12190 \newline
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 \SpecialChar ~
12195 _asm
12196 \newline
12197 \SpecialChar ~
12198 \SpecialChar ~
12199 \SpecialChar ~
12200 \SpecialChar ~
12201 \SpecialChar ~
12202 \SpecialChar ~
12203 ; some assembler code
12204 \newline
12205 \SpecialChar ~
12206 \SpecialChar ~
12207 \SpecialChar ~
12208 \SpecialChar ~
12209 \SpecialChar ~
12210 \SpecialChar ~
12211 ljmp $0003
12212 \newline
12213 \SpecialChar ~
12214 \SpecialChar ~
12215 \SpecialChar ~
12216 \SpecialChar ~
12217 _endasm;
12218 \newline
12219 \SpecialChar ~
12220 \SpecialChar ~
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 /* some more c code */
12224 \newline
12225 clabel:\SpecialChar ~
12226 \SpecialChar ~
12227 /* inline assembler cannot reference this label */
12228 \newline
12229 \SpecialChar ~
12230 \SpecialChar ~
12231 \SpecialChar ~
12232 \SpecialChar ~
12233 _asm
12234 \newline
12235 \SpecialChar ~
12236 \SpecialChar ~
12237 \SpecialChar ~
12238 \SpecialChar ~
12239 $0003: ;label (can be referenced by inline assembler only)
12240 \newline
12241 \SpecialChar ~
12242 \SpecialChar ~
12243 \SpecialChar ~
12244 \SpecialChar ~
12245 _endasm ;
12246 \newline
12247 \SpecialChar ~
12248 \SpecialChar ~
12249 \SpecialChar ~
12250 \SpecialChar ~
12251 /* some more c code */
12252 \newline
12253 }
12254 \layout Standard
12255
12256 In other words inline assembly code can access labels defined in inline
12257  assembly within the scope of the function.
12258  The same goes the other way, i.e.
12259  labels defines in inline assembly can not be accessed by C statements.
12260 \layout Section
12261
12262 Interfacing with Assembler Code
12263 \begin_inset LatexCommand \index{Assembler routines}
12264
12265 \end_inset
12266
12267
12268 \layout Subsection
12269
12270 Global Registers used for Parameter Passing
12271 \begin_inset LatexCommand \index{Parameter passing}
12272
12273 \end_inset
12274
12275
12276 \layout Standard
12277
12278 The compiler always uses the global registers
12279 \emph on
12280 DPL, DPH
12281 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12282
12283 \end_inset
12284
12285
12286 \begin_inset LatexCommand \index{DPTR}
12287
12288 \end_inset
12289
12290 , B
12291 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
12292
12293 \end_inset
12294
12295
12296 \emph default
12297 and
12298 \emph on
12299  ACC
12300 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
12301
12302 \end_inset
12303
12304
12305 \emph default
12306  to pass the first parameter to a routine.
12307  The second parameter onwards is either allocated on the stack (for reentrant
12308  routines or if -
12309 \begin_inset ERT
12310 status Collapsed
12311
12312 \layout Standard
12313
12314 \backslash
12315 /
12316 \end_inset
12317
12318 -stack-auto is used) or in data / xdata memory (depending on the memory
12319  model).
12320
12321 \layout Subsection
12322
12323 Assembler Routine (non-reentrant)
12324 \layout Standard
12325
12326 In the following example
12327 \begin_inset LatexCommand \index{reentrant}
12328
12329 \end_inset
12330
12331
12332 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
12333
12334 \end_inset
12335
12336  the function c_func calls an assembler routine asm_func, which takes two
12337  parameters
12338 \begin_inset LatexCommand \index{function parameter}
12339
12340 \end_inset
12341
12342 .
12343 \layout Verse
12344
12345
12346 \family typewriter
12347 extern int asm_func(unsigned char, unsigned char);
12348 \newline
12349
12350 \newline
12351 int c_func (unsigned char i, unsigned char j)
12352 \newline
12353 {
12354 \newline
12355 \SpecialChar ~
12356 \SpecialChar ~
12357 \SpecialChar ~
12358 \SpecialChar ~
12359 return asm_func(i,j);
12360 \newline
12361 }
12362 \newline
12363
12364 \newline
12365 int main()
12366 \newline
12367 {
12368 \newline
12369 \SpecialChar ~
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 return c_func(10,9);
12374 \newline
12375 }
12376 \layout Standard
12377
12378 The corresponding assembler function is:
12379 \layout Verse
12380
12381
12382 \family typewriter
12383 .globl _asm_func_PARM_2
12384 \newline
12385 \SpecialChar ~
12386 \SpecialChar ~
12387 \SpecialChar ~
12388 \SpecialChar ~
12389 \SpecialChar ~
12390 \SpecialChar ~
12391 \SpecialChar ~
12392 \SpecialChar ~
12393 .globl _asm_func
12394 \newline
12395 \SpecialChar ~
12396 \SpecialChar ~
12397 \SpecialChar ~
12398 \SpecialChar ~
12399 \SpecialChar ~
12400 \SpecialChar ~
12401 \SpecialChar ~
12402 \SpecialChar ~
12403 .area OSEG
12404 \newline
12405 _asm_func_PARM_2:
12406 \newline
12407 \SpecialChar ~
12408 \SpecialChar ~
12409 \SpecialChar ~
12410 \SpecialChar ~
12411 \SpecialChar ~
12412 \SpecialChar ~
12413 \SpecialChar ~
12414 \SpecialChar ~
12415 .ds    1
12416 \newline
12417 \SpecialChar ~
12418 \SpecialChar ~
12419 \SpecialChar ~
12420 \SpecialChar ~
12421 \SpecialChar ~
12422 \SpecialChar ~
12423 \SpecialChar ~
12424 \SpecialChar ~
12425 .area CSEG
12426 \newline
12427 _asm_func:
12428 \newline
12429 \SpecialChar ~
12430 \SpecialChar ~
12431 \SpecialChar ~
12432 \SpecialChar ~
12433 \SpecialChar ~
12434 \SpecialChar ~
12435 \SpecialChar ~
12436 \SpecialChar ~
12437 mov\SpecialChar ~
12438 \SpecialChar ~
12439 \SpecialChar ~
12440 \SpecialChar ~
12441 a,dpl
12442 \newline
12443 \SpecialChar ~
12444 \SpecialChar ~
12445 \SpecialChar ~
12446 \SpecialChar ~
12447 \SpecialChar ~
12448 \SpecialChar ~
12449 \SpecialChar ~
12450 \SpecialChar ~
12451 add\SpecialChar ~
12452 \SpecialChar ~
12453 \SpecialChar ~
12454 \SpecialChar ~
12455 a,_asm_func_PARM_2
12456 \newline
12457 \SpecialChar ~
12458 \SpecialChar ~
12459 \SpecialChar ~
12460 \SpecialChar ~
12461 \SpecialChar ~
12462 \SpecialChar ~
12463 \SpecialChar ~
12464 \SpecialChar ~
12465 mov\SpecialChar ~
12466 \SpecialChar ~
12467 \SpecialChar ~
12468 \SpecialChar ~
12469 dpl,a
12470 \newline
12471 \SpecialChar ~
12472 \SpecialChar ~
12473 \SpecialChar ~
12474 \SpecialChar ~
12475 \SpecialChar ~
12476 \SpecialChar ~
12477 \SpecialChar ~
12478 \SpecialChar ~
12479 mov\SpecialChar ~
12480 \SpecialChar ~
12481 \SpecialChar ~
12482 \SpecialChar ~
12483 dph
12484 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12485
12486 \end_inset
12487
12488 ,#0x00
12489 \newline
12490 \SpecialChar ~
12491 \SpecialChar ~
12492 \SpecialChar ~
12493 \SpecialChar ~
12494 \SpecialChar ~
12495 \SpecialChar ~
12496 \SpecialChar ~
12497 \SpecialChar ~
12498 ret
12499 \layout Standard
12500
12501 Note here that the return values
12502 \begin_inset LatexCommand \index{return value}
12503
12504 \end_inset
12505
12506  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
12507  two byte values.
12508  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12509 b' & 'acc' for four byte values.
12510 \layout Standard
12511
12512 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12513  the parameter number starting from 1, and counting from the left.
12514  The first parameter is passed in
12515 \begin_inset Quotes eld
12516 \end_inset
12517
12518 dpl
12519 \begin_inset Quotes erd
12520 \end_inset
12521
12522  for a one byte parameter,
12523 \begin_inset Quotes eld
12524 \end_inset
12525
12526 dptr
12527 \begin_inset Quotes erd
12528 \end_inset
12529
12530  for two bytes,
12531 \begin_inset Quotes eld
12532 \end_inset
12533
12534 b,dptr
12535 \begin_inset Quotes erd
12536 \end_inset
12537
12538  for three bytes and
12539 \begin_inset Quotes eld
12540 \end_inset
12541
12542 acc,b,dptr
12543 \begin_inset Quotes erd
12544 \end_inset
12545
12546  for a four bytes parameter.
12547  The variable name for the second parameter will be _<function_name>_PARM_2.
12548 \newline
12549
12550 \newline
12551 Assemble the assembler routine with the following command:
12552 \newline
12553
12554 \newline
12555
12556 \family sans
12557 \series bold
12558 asx8051 -losg asmfunc.asm
12559 \newline
12560
12561 \newline
12562
12563 \family default
12564 \series default
12565 Then compile and link the assembler routine to the C source file with the
12566  following command:
12567 \newline
12568
12569 \newline
12570
12571 \family sans
12572 \series bold
12573 sdcc cfunc.c asmfunc.rel
12574 \layout Subsection
12575
12576 Assembler Routine (reentrant)
12577 \layout Standard
12578
12579 In this case
12580 \begin_inset LatexCommand \index{reentrant}
12581
12582 \end_inset
12583
12584
12585 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12586
12587 \end_inset
12588
12589  the second parameter
12590 \begin_inset LatexCommand \index{function parameter}
12591
12592 \end_inset
12593
12594  onwards will be passed on the stack, the parameters are pushed from right
12595  to left i.e.
12596  after the call the leftmost parameter will be on the top of the stack.
12597  Here is an example:
12598 \layout Verse
12599
12600
12601 \family typewriter
12602 extern int asm_func(unsigned char, unsigned char);
12603 \newline
12604
12605 \newline
12606 int c_func (unsigned char i, unsigned char j) reentrant
12607 \newline
12608 {
12609 \newline
12610 \SpecialChar ~
12611 \SpecialChar ~
12612 \SpecialChar ~
12613 \SpecialChar ~
12614 return asm_func(i,j);
12615 \newline
12616 }
12617 \newline
12618
12619 \newline
12620 int main()
12621 \newline
12622 {
12623 \newline
12624 \SpecialChar ~
12625 \SpecialChar ~
12626 \SpecialChar ~
12627 \SpecialChar ~
12628 return c_func(10,9);
12629 \newline
12630 }
12631 \layout Standard
12632
12633 The corresponding assembler routine is:
12634 \layout Verse
12635
12636
12637 \family typewriter
12638 .globl _asm_func
12639 \newline
12640 _asm_func:
12641 \newline
12642 \SpecialChar ~
12643 \SpecialChar ~
12644 \SpecialChar ~
12645 \SpecialChar ~
12646 push  _bp
12647 \newline
12648 \SpecialChar ~
12649 \SpecialChar ~
12650 \SpecialChar ~
12651 \SpecialChar ~
12652 mov _bp,sp
12653 \newline
12654 \SpecialChar ~
12655 \SpecialChar ~
12656 \SpecialChar ~
12657 \SpecialChar ~
12658 mov r2,dpl
12659 \newline
12660 \SpecialChar ~
12661 \SpecialChar ~
12662 \SpecialChar ~
12663 \SpecialChar ~
12664 mov a,_bp
12665 \newline
12666 \SpecialChar ~
12667 \SpecialChar ~
12668 \SpecialChar ~
12669 \SpecialChar ~
12670 add a,#0xfd
12671 \newline
12672 \SpecialChar ~
12673 \SpecialChar ~
12674 \SpecialChar ~
12675 \SpecialChar ~
12676 mov r0,a
12677 \newline
12678 \SpecialChar ~
12679 \SpecialChar ~
12680 \SpecialChar ~
12681 \SpecialChar ~
12682 add  a,#0xfc ;?
12683 \newline
12684 \SpecialChar ~
12685 \SpecialChar ~
12686 \SpecialChar ~
12687 \SpecialChar ~
12688 mov  r1,a
12689 \newline
12690 \SpecialChar ~
12691 \SpecialChar ~
12692 \SpecialChar ~
12693 \SpecialChar ~
12694 mov  a,@r0
12695 \newline
12696 \SpecialChar ~
12697 \SpecialChar ~
12698 \SpecialChar ~
12699 \SpecialChar ~
12700 add  a,r2 ;?
12701 \newline
12702 \SpecialChar ~
12703 \SpecialChar ~
12704 \SpecialChar ~
12705 \SpecialChar ~
12706 mov  dpl,a
12707 \newline
12708 \SpecialChar ~
12709 \SpecialChar ~
12710 \SpecialChar ~
12711 \SpecialChar ~
12712 mov  dph,#0x00
12713 \newline
12714 \SpecialChar ~
12715 \SpecialChar ~
12716 \SpecialChar ~
12717 \SpecialChar ~
12718 mov  sp,_bp
12719 \newline
12720 \SpecialChar ~
12721 \SpecialChar ~
12722 \SpecialChar ~
12723 \SpecialChar ~
12724 pop  _bp
12725 \newline
12726 \SpecialChar ~
12727 \SpecialChar ~
12728 \SpecialChar ~
12729 \SpecialChar ~
12730 ret
12731 \layout Standard
12732
12733 The compiling and linking procedure remains the same, however note the extra
12734  entry & exit linkage required for the assembler code, _bp is the stack
12735  frame pointer and is used to compute the offset into the stack for parameters
12736  and local variables.
12737 \layout Section
12738
12739 int (16 bit)
12740 \begin_inset LatexCommand \index{int (16 bit)}
12741
12742 \end_inset
12743
12744  and long (32 bit)
12745 \begin_inset LatexCommand \index{long (32 bit)}
12746
12747 \end_inset
12748
12749  Support
12750 \layout Standard
12751
12752 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
12753  multiplication and modulus operations are implemented by support routines.
12754  These support routines are all developed in ANSI-C to facilitate porting
12755  to other MCUs, although some model specific assembler optimizations are
12756  used.
12757  The following files contain the described routines, all of them can be
12758  found in <installdir>/share/sdcc/lib.
12759 \newline
12760
12761 \layout Standard
12762 \align center
12763
12764 \begin_inset  Tabular
12765 <lyxtabular version="3" rows="11" columns="2">
12766 <features>
12767 <column alignment="center" valignment="top" leftline="true" width="0">
12768 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12769 <row topline="true" bottomline="true">
12770 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12771 \begin_inset Text
12772
12773 \layout Standard
12774
12775
12776 \series bold
12777 Function
12778 \end_inset
12779 </cell>
12780 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12781 \begin_inset Text
12782
12783 \layout Standard
12784
12785
12786 \series bold
12787 Description
12788 \end_inset
12789 </cell>
12790 </row>
12791 <row topline="true">
12792 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12793 \begin_inset Text
12794
12795 \layout Standard
12796
12797 _mulint.c
12798 \end_inset
12799 </cell>
12800 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12801 \begin_inset Text
12802
12803 \layout Standard
12804
12805 16 bit multiplication
12806 \end_inset
12807 </cell>
12808 </row>
12809 <row topline="true">
12810 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12811 \begin_inset Text
12812
12813 \layout Standard
12814
12815 _divsint.c
12816 \end_inset
12817 </cell>
12818 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12819 \begin_inset Text
12820
12821 \layout Standard
12822
12823  signed 16 bit division (calls _divuint)
12824 \end_inset
12825 </cell>
12826 </row>
12827 <row topline="true">
12828 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12829 \begin_inset Text
12830
12831 \layout Standard
12832
12833 _divuint.c
12834 \end_inset
12835 </cell>
12836 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12837 \begin_inset Text
12838
12839 \layout Standard
12840
12841  unsigned 16 bit division
12842 \end_inset
12843 </cell>
12844 </row>
12845 <row topline="true">
12846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12847 \begin_inset Text
12848
12849 \layout Standard
12850
12851 _modsint.c
12852 \end_inset
12853 </cell>
12854 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12855 \begin_inset Text
12856
12857 \layout Standard
12858
12859 signed 16 bit modulus (calls _moduint)
12860 \end_inset
12861 </cell>
12862 </row>
12863 <row topline="true">
12864 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12865 \begin_inset Text
12866
12867 \layout Standard
12868
12869 _moduint.c
12870 \end_inset
12871 </cell>
12872 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12873 \begin_inset Text
12874
12875 \layout Standard
12876
12877 unsigned 16 bit modulus
12878 \end_inset
12879 </cell>
12880 </row>
12881 <row topline="true">
12882 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12883 \begin_inset Text
12884
12885 \layout Standard
12886
12887 _mullong.c
12888 \end_inset
12889 </cell>
12890 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12891 \begin_inset Text
12892
12893 \layout Standard
12894
12895 32 bit multiplication
12896 \end_inset
12897 </cell>
12898 </row>
12899 <row topline="true">
12900 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12901 \begin_inset Text
12902
12903 \layout Standard
12904
12905 _divslong.c
12906 \end_inset
12907 </cell>
12908 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12909 \begin_inset Text
12910
12911 \layout Standard
12912
12913  signed 32 division (calls _divulong)
12914 \end_inset
12915 </cell>
12916 </row>
12917 <row topline="true">
12918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12919 \begin_inset Text
12920
12921 \layout Standard
12922
12923 _divulong.c
12924 \end_inset
12925 </cell>
12926 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12927 \begin_inset Text
12928
12929 \layout Standard
12930
12931 unsigned 32 division
12932 \end_inset
12933 </cell>
12934 </row>
12935 <row topline="true">
12936 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12937 \begin_inset Text
12938
12939 \layout Standard
12940
12941 _modslong.c
12942 \end_inset
12943 </cell>
12944 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12945 \begin_inset Text
12946
12947 \layout Standard
12948
12949  signed 32 bit modulus (calls _modulong)
12950 \end_inset
12951 </cell>
12952 </row>
12953 <row topline="true" bottomline="true">
12954 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12955 \begin_inset Text
12956
12957 \layout Standard
12958
12959 _modulong.c
12960 \end_inset
12961 </cell>
12962 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12963 \begin_inset Text
12964
12965 \layout Standard
12966
12967 unsigned 32 bit modulus
12968 \end_inset
12969 </cell>
12970 </row>
12971 </lyxtabular>
12972
12973 \end_inset
12974
12975
12976 \newline
12977
12978 \layout Standard
12979
12980 Since they are compiled as
12981 \emph on
12982 non-reentrant
12983 \emph default
12984
12985 \begin_inset LatexCommand \index{reentrant}
12986
12987 \end_inset
12988
12989 , interrupt
12990 \begin_inset LatexCommand \index{interrupt}
12991
12992 \end_inset
12993
12994  service routines should not do any of the above operations.
12995  If this is unavoidable then the above routines will need to be compiled
12996  with the
12997 \emph on
12998 -
12999 \begin_inset ERT
13000 status Collapsed
13001
13002 \layout Standard
13003
13004 \backslash
13005 /
13006 \end_inset
13007
13008 -stack-auto
13009 \begin_inset LatexCommand \index{-\/-stack-auto}
13010
13011 \end_inset
13012
13013
13014 \emph default
13015  option, after which the source program will have to be compiled with
13016 \emph on
13017 -
13018 \begin_inset ERT
13019 status Collapsed
13020
13021 \layout Standard
13022
13023 \backslash
13024 /
13025 \end_inset
13026
13027 -int-long-reent
13028 \begin_inset LatexCommand \index{-\/-int-long-reent}
13029
13030 \end_inset
13031
13032
13033 \emph default
13034  option.
13035  Notice that you don't have to call these routines directly.
13036  The compiler will use them automatically every time an integer operation
13037  is required.
13038 \layout Section
13039
13040 Floating Point Support
13041 \begin_inset LatexCommand \index{Floating point support}
13042
13043 \end_inset
13044
13045
13046 \layout Standard
13047
13048 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
13049  floating point support routines are derived from gcc's floatlib.c and consist
13050  of the following routines:
13051 \newline
13052
13053 \layout Standard
13054 \align center
13055
13056 \size footnotesize
13057
13058 \begin_inset  Tabular
13059 <lyxtabular version="3" rows="17" columns="2">
13060 <features>
13061 <column alignment="center" valignment="top" leftline="true" width="0">
13062 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
13063 <row topline="true" bottomline="true">
13064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13065 \begin_inset Text
13066
13067 \layout Standard
13068
13069
13070 \family roman
13071 \series medium
13072 \shape up
13073 \size normal
13074 \emph off
13075 \bar no
13076 \noun off
13077 \color none
13078 Function
13079 \end_inset
13080 </cell>
13081 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13082 \begin_inset Text
13083
13084 \layout Standard
13085
13086 Description
13087 \end_inset
13088 </cell>
13089 </row>
13090 <row topline="true">
13091 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13092 \begin_inset Text
13093
13094 \layout Standard
13095
13096
13097 \family roman
13098 \series medium
13099 \shape up
13100 \size normal
13101 \emph off
13102 \bar no
13103 \noun off
13104 \color none
13105 _fsadd.c
13106 \end_inset
13107 </cell>
13108 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13109 \begin_inset Text
13110
13111 \layout Standard
13112
13113
13114 \family roman
13115 \series medium
13116 \shape up
13117 \size normal
13118 \emph off
13119 \bar no
13120 \noun off
13121 \color none
13122 add floating point numbers
13123 \end_inset
13124 </cell>
13125 </row>
13126 <row topline="true">
13127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13128 \begin_inset Text
13129
13130 \layout Standard
13131
13132
13133 \family roman
13134 \series medium
13135 \shape up
13136 \size normal
13137 \emph off
13138 \bar no
13139 \noun off
13140 \color none
13141 _fssub.c
13142 \end_inset
13143 </cell>
13144 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13145 \begin_inset Text
13146
13147 \layout Standard
13148
13149
13150 \family roman
13151 \series medium
13152 \shape up
13153 \size normal
13154 \emph off
13155 \bar no
13156 \noun off
13157 \color none
13158 subtract floating point numbers
13159 \end_inset
13160 </cell>
13161 </row>
13162 <row topline="true">
13163 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13164 \begin_inset Text
13165
13166 \layout Standard
13167
13168
13169 \family roman
13170 \series medium
13171 \shape up
13172 \size normal
13173 \emph off
13174 \bar no
13175 \noun off
13176 \color none
13177 _fsdiv.c
13178 \end_inset
13179 </cell>
13180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13181 \begin_inset Text
13182
13183 \layout Standard
13184
13185
13186 \family roman
13187 \series medium
13188 \shape up
13189 \size normal
13190 \emph off
13191 \bar no
13192 \noun off
13193 \color none
13194 divide floating point numbers
13195 \end_inset
13196 </cell>
13197 </row>
13198 <row topline="true">
13199 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13200 \begin_inset Text
13201
13202 \layout Standard
13203
13204
13205 \family roman
13206 \series medium
13207 \shape up
13208 \size normal
13209 \emph off
13210 \bar no
13211 \noun off
13212 \color none
13213 _fsmul.c
13214 \end_inset
13215 </cell>
13216 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13217 \begin_inset Text
13218
13219 \layout Standard
13220
13221
13222 \family roman
13223 \series medium
13224 \shape up
13225 \size normal
13226 \emph off
13227 \bar no
13228 \noun off
13229 \color none
13230 multiply floating point numbers
13231 \end_inset
13232 </cell>
13233 </row>
13234 <row topline="true">
13235 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13236 \begin_inset Text
13237
13238 \layout Standard
13239
13240
13241 \family roman
13242 \series medium
13243 \shape up
13244 \size normal
13245 \emph off
13246 \bar no
13247 \noun off
13248 \color none
13249 _fs2uchar.c
13250 \end_inset
13251 </cell>
13252 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13253 \begin_inset Text
13254
13255 \layout Standard
13256
13257
13258 \family roman
13259 \series medium
13260 \shape up
13261 \size normal
13262 \emph off
13263 \bar no
13264 \noun off
13265 \color none
13266 convert floating point to unsigned char
13267 \end_inset
13268 </cell>
13269 </row>
13270 <row topline="true">
13271 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13272 \begin_inset Text
13273
13274 \layout Standard
13275
13276
13277 \family roman
13278 \series medium
13279 \shape up
13280 \size normal
13281 \emph off
13282 \bar no
13283 \noun off
13284 \color none
13285 _fs2char.c
13286 \end_inset
13287 </cell>
13288 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13289 \begin_inset Text
13290
13291 \layout Standard
13292
13293
13294 \family roman
13295 \series medium
13296 \shape up
13297 \size normal
13298 \emph off
13299 \bar no
13300 \noun off
13301 \color none
13302 convert floating point to signed char
13303 \end_inset
13304 </cell>
13305 </row>
13306 <row topline="true">
13307 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13308 \begin_inset Text
13309
13310 \layout Standard
13311
13312
13313 \family roman
13314 \series medium
13315 \shape up
13316 \size normal
13317 \emph off
13318 \bar no
13319 \noun off
13320 \color none
13321 _fs2uint.c
13322 \end_inset
13323 </cell>
13324 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13325 \begin_inset Text
13326
13327 \layout Standard
13328
13329
13330 \family roman
13331 \series medium
13332 \shape up
13333 \size normal
13334 \emph off
13335 \bar no
13336 \noun off
13337 \color none
13338 convert floating point to unsigned int
13339 \end_inset
13340 </cell>
13341 </row>
13342 <row topline="true">
13343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13344 \begin_inset Text
13345
13346 \layout Standard
13347
13348
13349 \family roman
13350 \series medium
13351 \shape up
13352 \size normal
13353 \emph off
13354 \bar no
13355 \noun off
13356 \color none
13357 _fs2int.c
13358 \end_inset
13359 </cell>
13360 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13361 \begin_inset Text
13362
13363 \layout Standard
13364
13365
13366 \family roman
13367 \series medium
13368 \shape up
13369 \size normal
13370 \emph off
13371 \bar no
13372 \noun off
13373 \color none
13374 convert floating point to signed int
13375 \end_inset
13376 </cell>
13377 </row>
13378 <row topline="true">
13379 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13380 \begin_inset Text
13381
13382 \layout Standard
13383
13384
13385 \family roman
13386 \series medium
13387 \shape up
13388 \size normal
13389 \emph off
13390 \bar no
13391 \noun off
13392 \color none
13393 _fs2ulong.
13394 \family default
13395 \series default
13396 \shape default
13397 \size default
13398 \emph default
13399 \bar default
13400 \noun default
13401 \color default
13402 c
13403 \end_inset
13404 </cell>
13405 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13406 \begin_inset Text
13407
13408 \layout Standard
13409
13410
13411 \family roman
13412 \series medium
13413 \shape up
13414 \size normal
13415 \emph off
13416 \bar no
13417 \noun off
13418 \color none
13419 convert floating point to unsigned long
13420 \end_inset
13421 </cell>
13422 </row>
13423 <row topline="true">
13424 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13425 \begin_inset Text
13426
13427 \layout Standard
13428
13429
13430 \family roman
13431 \series medium
13432 \shape up
13433 \size normal
13434 \emph off
13435 \bar no
13436 \noun off
13437 \color none
13438 _fs2long.c
13439 \end_inset
13440 </cell>
13441 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13442 \begin_inset Text
13443
13444 \layout Standard
13445
13446
13447 \family roman
13448 \series medium
13449 \shape up
13450 \size normal
13451 \emph off
13452 \bar no
13453 \noun off
13454 \color none
13455 convert floating point to signed long
13456 \end_inset
13457 </cell>
13458 </row>
13459 <row topline="true">
13460 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13461 \begin_inset Text
13462
13463 \layout Standard
13464
13465
13466 \family roman
13467 \series medium
13468 \shape up
13469 \size normal
13470 \emph off
13471 \bar no
13472 \noun off
13473 \color none
13474 _uchar2fs.c
13475 \end_inset
13476 </cell>
13477 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13478 \begin_inset Text
13479
13480 \layout Standard
13481
13482
13483 \family roman
13484 \series medium
13485 \shape up
13486 \size normal
13487 \emph off
13488 \bar no
13489 \noun off
13490 \color none
13491 convert unsigned char to floating point
13492 \end_inset
13493 </cell>
13494 </row>
13495 <row topline="true">
13496 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13497 \begin_inset Text
13498
13499 \layout Standard
13500
13501
13502 \family roman
13503 \series medium
13504 \shape up
13505 \size normal
13506 \emph off
13507 \bar no
13508 \noun off
13509 \color none
13510 _char2fs.c
13511 \end_inset
13512 </cell>
13513 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13514 \begin_inset Text
13515
13516 \layout Standard
13517
13518
13519 \family roman
13520 \series medium
13521 \shape up
13522 \size normal
13523 \emph off
13524 \bar no
13525 \noun off
13526 \color none
13527 convert char to floating point number
13528 \end_inset
13529 </cell>
13530 </row>
13531 <row topline="true">
13532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13533 \begin_inset Text
13534
13535 \layout Standard
13536
13537
13538 \family roman
13539 \series medium
13540 \shape up
13541 \size normal
13542 \emph off
13543 \bar no
13544 \noun off
13545 \color none
13546 _uint2fs.c
13547 \end_inset
13548 </cell>
13549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13550 \begin_inset Text
13551
13552 \layout Standard
13553
13554
13555 \family roman
13556 \series medium
13557 \shape up
13558 \size normal
13559 \emph off
13560 \bar no
13561 \noun off
13562 \color none
13563 convert unsigned int to floating point
13564 \end_inset
13565 </cell>
13566 </row>
13567 <row topline="true">
13568 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13569 \begin_inset Text
13570
13571 \layout Standard
13572
13573
13574 \family roman
13575 \series medium
13576 \shape up
13577 \size normal
13578 \emph off
13579 \bar no
13580 \noun off
13581 \color none
13582 _int2fs.c
13583 \end_inset
13584 </cell>
13585 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13586 \begin_inset Text
13587
13588 \layout Standard
13589
13590
13591 \family roman
13592 \series medium
13593 \shape up
13594 \size normal
13595 \emph off
13596 \bar no
13597 \noun off
13598 \color none
13599 convert int to floating point numbers
13600 \end_inset
13601 </cell>
13602 </row>
13603 <row topline="true">
13604 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13605 \begin_inset Text
13606
13607 \layout Standard
13608
13609
13610 \family roman
13611 \series medium
13612 \shape up
13613 \size normal
13614 \emph off
13615 \bar no
13616 \noun off
13617 \color none
13618 _ulong2fs.c
13619 \end_inset
13620 </cell>
13621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13622 \begin_inset Text
13623
13624 \layout Standard
13625
13626
13627 \family roman
13628 \series medium
13629 \shape up
13630 \size normal
13631 \emph off
13632 \bar no
13633 \noun off
13634 \color none
13635 convert unsigned long to floating point number
13636 \end_inset
13637 </cell>
13638 </row>
13639 <row topline="true" bottomline="true">
13640 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13641 \begin_inset Text
13642
13643 \layout Standard
13644
13645
13646 \family roman
13647 \series medium
13648 \shape up
13649 \size normal
13650 \emph off
13651 \bar no
13652 \noun off
13653 \color none
13654 _long2fs.c
13655 \end_inset
13656 </cell>
13657 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13658 \begin_inset Text
13659
13660 \layout Standard
13661
13662
13663 \family roman
13664 \series medium
13665 \shape up
13666 \size normal
13667 \emph off
13668 \bar no
13669 \noun off
13670 \color none
13671 convert long to floating point number
13672 \end_inset
13673 </cell>
13674 </row>
13675 </lyxtabular>
13676
13677 \end_inset
13678
13679
13680 \newline
13681
13682 \layout Standard
13683
13684 These support routines are developed in ANSI-C so there is room for space
13685  and speed improvement.
13686  Note if all these routines are used simultaneously the data space might
13687  overflow.
13688  For serious floating point usage it is recommended that the large model
13689  be used.
13690  Also notice that you don't have to call this routines directly.
13691  The compiler will use them automatically every time a floating point operation
13692  is required.
13693 \layout Section
13694
13695 Library Routines
13696 \begin_inset LatexCommand \index{Libraries}
13697
13698 \end_inset
13699
13700
13701 \layout Standard
13702
13703
13704 \emph on
13705 <pending: this is messy and incomplete - a little more information is in
13706  sdcc/doc/libdoc.txt
13707 \emph default
13708  >
13709 \layout Subsection
13710
13711 Compiler support routines (_gptrget, _mulint etc.)
13712 \layout Subsection
13713
13714 Stdclib functions (puts, printf, strcat etc.)
13715 \layout Subsubsection
13716
13717 <stdio.h>
13718 \layout Standard
13719
13720
13721 \begin_inset LatexCommand \index{<stdio.h>}
13722
13723 \end_inset
13724
13725 As usual on embedded systems you have to provide your own
13726 \family typewriter
13727 getchar()
13728 \begin_inset LatexCommand \index{getchar()}
13729
13730 \end_inset
13731
13732
13733 \family default
13734 and
13735 \family typewriter
13736 putchar()
13737 \begin_inset LatexCommand \index{putchar()}
13738
13739 \end_inset
13740
13741
13742 \family default
13743  routines.
13744  SDCC does not know whether the system connects to a serial line with or
13745  without handshake, LCD, keyboard or other device.
13746  You'll find examples for serial routines f.e.
13747  in sdcc/device/lib.
13748 \layout Standard
13749
13750 The default
13751 \family typewriter
13752  printf()
13753 \begin_inset LatexCommand \index{printf()}
13754
13755 \end_inset
13756
13757
13758 \family default
13759 implementation in
13760 \family typewriter
13761  printf_large.c
13762 \family default
13763  does not support float (except on ds390).
13764  To enable this recompile it with the option
13765 \emph on
13766 -
13767 \begin_inset ERT
13768 status Collapsed
13769
13770 \layout Standard
13771
13772 \backslash
13773 /
13774 \end_inset
13775
13776 DUSE_FLOATS=1
13777 \begin_inset LatexCommand \index{USE\_FLOATS}
13778
13779 \end_inset
13780
13781
13782 \emph default
13783  on the command line.
13784  Use
13785 \emph on
13786 -
13787 \begin_inset ERT
13788 status Collapsed
13789
13790 \layout Standard
13791
13792 \backslash
13793 /
13794 \end_inset
13795
13796 -model-large
13797 \begin_inset LatexCommand \index{-\/-model-large}
13798
13799 \end_inset
13800
13801
13802 \emph default
13803  for the mcs51 port, since this uses a lot of memory.
13804 \layout Standard
13805
13806 If you're short on memory you might want to use
13807 \family typewriter
13808 printf_small()
13809 \family default
13810
13811 \emph on
13812 instead
13813 \emph default
13814  of
13815 \family typewriter
13816  printf().
13817
13818 \family default
13819  For the mcs51 there is an assembly version
13820 \family typewriter
13821 printf_fast()
13822 \family default
13823  which should fit the requirements of many embedded systems (by unsetting
13824  #defines it can be customized to
13825 \emph on
13826 not
13827 \emph default
13828  support long variables and field widths).
13829 \layout Subsection
13830
13831 Math functions (sin, pow, sqrt etc.)
13832 \layout Subsection
13833
13834 Other libraries
13835 \layout Standard
13836
13837 Libraries
13838 \begin_inset LatexCommand \index{Libraries}
13839
13840 \end_inset
13841
13842  included in SDCC should have a license at least as liberal as the GNU Lesser
13843  General Public License
13844 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
13845
13846 \end_inset
13847
13848
13849 \emph on
13850 LGPL
13851 \emph default
13852 .
13853 \layout Comment
13854
13855 license statements for the libraries are missing.
13856  sdcc/device/lib/ser_ir.c
13857 \layout Comment
13858
13859 or _decdptr f.e.
13860  come with a GPL (as opposed to LGPL) License - this will not be liberal
13861  enough for many embedded programmers.
13862 \layout Standard
13863
13864 If you have ported some library or want to share experience about some code
13865  which f.e.
13866  falls into any of these categories Busses (I
13867 \begin_inset Formula $^{\textrm{2}}$
13868 \end_inset
13869
13870 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
13871  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
13872  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
13873 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
13874
13875 \end_inset
13876
13877 \SpecialChar ~
13878 would certainly like to hear about it.
13879  Programmers coding for embedded systems are not especially famous for being
13880  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
13881 e these references are very valuable.
13882  Let's help to create a climate where information is shared.
13883 \layout Section
13884
13885 Memory Models
13886 \layout Subsection
13887
13888 MCS51 Memory Models
13889 \begin_inset LatexCommand \index{Memory model}
13890
13891 \end_inset
13892
13893
13894 \begin_inset LatexCommand \index{MCS51 memory model}
13895
13896 \end_inset
13897
13898
13899 \layout Subsubsection
13900
13901 Small and Large
13902 \layout Standard
13903
13904 SDCC allows two memory models for MCS51 code,
13905 \shape slanted
13906 small
13907 \shape default
13908  and
13909 \shape slanted
13910 large
13911 \shape default
13912 .
13913  Modules compiled with different memory models should
13914 \emph on
13915 never
13916 \emph default
13917  be combined together or the results would be unpredictable.
13918  The library routines supplied with the compiler are compiled as both small
13919  and large.
13920  The compiled library modules are contained in separate directories as small
13921  and large so that you can link to either set.
13922
13923 \layout Standard
13924
13925 When the large model is used all variables declared without a storage class
13926  will be allocated into the external ram, this includes all parameters and
13927  local variables (for non-reentrant
13928 \begin_inset LatexCommand \index{reentrant}
13929
13930 \end_inset
13931
13932  functions).
13933  When the small model is used variables without storage class are allocated
13934  in the internal ram.
13935 \layout Standard
13936
13937 Judicious usage of the processor specific storage classes
13938 \begin_inset LatexCommand \index{Storage class}
13939
13940 \end_inset
13941
13942  and the 'reentrant' function type will yield much more efficient code,
13943  than using the large model.
13944  Several optimizations are disabled when the program is compiled using the
13945  large model, it is therefore recommended that the small model be used unless
13946  absolutely required.
13947 \layout Subsubsection
13948
13949 External Stack
13950 \begin_inset LatexCommand \label{sub:External-Stack}
13951
13952 \end_inset
13953
13954
13955 \begin_inset LatexCommand \index{stack}
13956
13957 \end_inset
13958
13959
13960 \begin_inset LatexCommand \index{External stack (mcs51)}
13961
13962 \end_inset
13963
13964
13965 \layout Standard
13966
13967 The external stack (-
13968 \begin_inset ERT
13969 status Collapsed
13970
13971 \layout Standard
13972
13973 \backslash
13974 /
13975 \end_inset
13976
13977 -xstack option
13978 \begin_inset LatexCommand \index{-\/-xstack}
13979
13980 \end_inset
13981
13982 ) is located in pdata
13983 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
13984
13985 \end_inset
13986
13987  memory (usually at the start of the external ram segment) and uses all
13988  unused space in pdata (max.
13989  256 bytes).
13990  When -
13991 \begin_inset ERT
13992 status Collapsed
13993
13994 \layout Standard
13995
13996 \backslash
13997 /
13998 \end_inset
13999
14000 -xstack option is used to compile the program, the parameters and local
14001  variables
14002 \begin_inset LatexCommand \index{local variables}
14003
14004 \end_inset
14005
14006  of all reentrant functions are allocated in this area.
14007  This option is provided for programs with large stack space requirements.
14008  When used with the -
14009 \begin_inset ERT
14010 status Collapsed
14011
14012 \layout Standard
14013
14014 \backslash
14015 /
14016 \end_inset
14017
14018 -stack-auto
14019 \begin_inset LatexCommand \index{-\/-stack-auto}
14020
14021 \end_inset
14022
14023  option, all parameters and local variables are allocated on the external
14024  stack (note: support libraries will need to be recompiled with the same
14025  options.
14026  There is a predefined target in the library makefile).
14027 \layout Standard
14028
14029 The compiler outputs the higher order address byte of the external ram segment
14030  into port P2
14031 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14032
14033 \end_inset
14034
14035  (see also section
14036 \begin_inset LatexCommand \ref{sub:MCS51-variants}
14037
14038 \end_inset
14039
14040 ), therefore when using the External Stack option, this port
14041 \emph on
14042 may not
14043 \emph default
14044  be used by the application program.
14045 \layout Subsection
14046
14047 DS390 Memory Model
14048 \begin_inset LatexCommand \index{Memory model}
14049
14050 \end_inset
14051
14052
14053 \begin_inset LatexCommand \index{DS390 memory model}
14054
14055 \end_inset
14056
14057
14058 \layout Standard
14059
14060 The only model supported is Flat 24
14061 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
14062
14063 \end_inset
14064
14065 .
14066  This generates code for the 24 bit contiguous addressing mode of the Dallas
14067  DS80C390 part.
14068  In this mode, up to four meg of external RAM or code space can be directly
14069  addressed.
14070  See the data sheets at www.dalsemi.com for further information on this part.
14071 \newline
14072
14073 \newline
14074 Note that the compiler does not generate any code to place the processor
14075  into 24 bitmode (although
14076 \emph on
14077 tinibios
14078 \emph default
14079  in the ds390 libraries will do that for you).
14080  If you don't use
14081 \emph on
14082 tinibios
14083 \emph default
14084
14085 \begin_inset LatexCommand \index{Tinibios (DS390)}
14086
14087 \end_inset
14088
14089 , the boot loader or similar code must ensure that the processor is in 24
14090  bit contiguous addressing mode before calling the SDCC startup code.
14091 \newline
14092
14093 \newline
14094 Like the
14095 \emph on
14096 -
14097 \begin_inset ERT
14098 status Collapsed
14099
14100 \layout Standard
14101
14102 \backslash
14103 /
14104 \end_inset
14105
14106 -model-large
14107 \emph default
14108  option, variables will by default be placed into the XDATA segment.
14109
14110 \newline
14111
14112 \newline
14113 Segments may be placed anywhere in the 4 meg address space using the usual
14114  -
14115 \begin_inset ERT
14116 status Collapsed
14117
14118 \layout Standard
14119
14120 \backslash
14121 /
14122 \end_inset
14123
14124 -*-loc options.
14125  Note that if any segments are located above 64K, the -r flag must be passed
14126  to the linker to generate the proper segment relocations, and the Intel
14127  HEX output format must be used.
14128  The -r flag can be passed to the linker by using the option
14129 \emph on
14130 -Wl-r
14131 \emph default
14132  on the SDCC command line.
14133  However, currently the linker can not handle code segments > 64k.
14134 \layout Section
14135
14136 Pragmas
14137 \begin_inset LatexCommand \index{Pragmas}
14138
14139 \end_inset
14140
14141
14142 \layout Standard
14143
14144 SDCC supports the following #pragma directives:
14145 \layout Itemize
14146
14147 save
14148 \begin_inset LatexCommand \index{\#pragma save}
14149
14150 \end_inset
14151
14152  - this will save all current options to the save/restore stack.
14153  See #pragma\SpecialChar ~
14154 restore.
14155 \layout Itemize
14156
14157 restore
14158 \begin_inset LatexCommand \index{\#pragma restore}
14159
14160 \end_inset
14161
14162  - will restore saved options from the last save.
14163  saves & restores can be nested.
14164  SDCC uses a save/restore stack: save pushes current options to the stack,
14165  restore pulls current options from the stack.
14166  See #pragma\SpecialChar ~
14167 save.
14168 \newline
14169
14170 \layout Itemize
14171
14172 callee_saves
14173 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14174
14175 \end_inset
14176
14177
14178 \begin_inset LatexCommand \index{function prologue}
14179
14180 \end_inset
14181
14182  function1[,function2[,function3...]] - The compiler by default uses a caller
14183  saves convention for register saving across function calls, however this
14184  can cause unnecessary register pushing & popping
14185 \begin_inset LatexCommand \index{push/pop}
14186
14187 \end_inset
14188
14189  when calling small functions from larger functions.
14190  This option can be used to switch off the register saving convention for
14191  the function names specified.
14192  The compiler will not save registers when calling these functions, extra
14193  code need to be manually inserted at the entry & exit for these functions
14194  to save & restore the registers used by these functions, this can SUBSTANTIALLY
14195  reduce code & improve run time performance of the generated code.
14196  In the future the compiler (with inter procedural analysis) may be able
14197  to determine the appropriate scheme to use for each function call.
14198  If -
14199 \begin_inset ERT
14200 status Collapsed
14201
14202 \layout Standard
14203
14204 \backslash
14205 /
14206 \end_inset
14207
14208 -callee-saves command line option is used, the function names specified
14209  in #pragma\SpecialChar ~
14210 callee_saves
14211 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14212
14213 \end_inset
14214
14215  is appended to the list of functions specified in the command line.
14216 \layout Itemize
14217
14218 exclude
14219 \begin_inset LatexCommand \index{\#pragma exclude}
14220
14221 \end_inset
14222
14223  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
14224  of pairs of push/pop
14225 \begin_inset LatexCommand \index{push/pop}
14226
14227 \end_inset
14228
14229  instructions in
14230 \emph on
14231 I
14232 \emph default
14233 nterrupt
14234 \begin_inset LatexCommand \index{interrupt}
14235
14236 \end_inset
14237
14238
14239 \emph on
14240 S
14241 \emph default
14242 ervice
14243 \emph on
14244 R
14245 \emph default
14246 outines.
14247  The directive should be placed immediately before the ISR function definition
14248  and it affects ALL ISR functions following it.
14249  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
14250 exclude\SpecialChar ~
14251 none
14252 \begin_inset LatexCommand \index{\#pragma exclude}
14253
14254 \end_inset
14255
14256 .
14257  See also the related keyword _naked
14258 \begin_inset LatexCommand \index{\_naked}
14259
14260 \end_inset
14261
14262 .
14263 \layout Itemize
14264
14265 less_pedantic
14266 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
14267
14268 \end_inset
14269
14270  - the compiler will not warn you anymore for obvious mistakes, you'r on
14271  your own now ;-(
14272 \layout Itemize
14273
14274 disable_warning <nnnn>
14275 \begin_inset LatexCommand \index{\#pragma disable\_warning}
14276
14277 \end_inset
14278
14279  - the compiler will not warn you anymore about warning number <nnnn>.
14280 \layout Itemize
14281
14282 nogcse
14283 \begin_inset LatexCommand \index{\#pragma nogcse}
14284
14285 \end_inset
14286
14287  - will stop global common subexpression elimination.
14288 \layout Itemize
14289
14290 noinduction
14291 \begin_inset LatexCommand \index{\#pragma noinduction}
14292
14293 \end_inset
14294
14295  - will stop loop induction optimizations.
14296 \layout Itemize
14297
14298 noinvariant
14299 \begin_inset LatexCommand \index{\#pragma noinvariant}
14300
14301 \end_inset
14302
14303  - will not do loop invariant optimizations.
14304  For more details see Loop Invariants in section
14305 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
14306
14307 \end_inset
14308
14309 .
14310 \layout Itemize
14311
14312 noiv
14313 \begin_inset LatexCommand \index{\#pragma noiv}
14314
14315 \end_inset
14316
14317  - Do not generate interrupt
14318 \begin_inset LatexCommand \index{interrupt}
14319
14320 \end_inset
14321
14322  vector table entries for all ISR functions defined after the pragma.
14323  This is useful in cases where the interrupt vector table must be defined
14324  manually, or when there is a secondary, manually defined interrupt vector
14325  table (e.g.
14326  for the autovector feature of the Cypress EZ-USB FX2).
14327  More elegantly this can be achieved by obmitting the optional interrupt
14328  number after the interrupt keyword, see section
14329 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
14330
14331 \end_inset
14332
14333 \SpecialChar ~
14334 about interrupts.
14335 \layout Itemize
14336
14337 nojtbound
14338 \begin_inset LatexCommand \index{\#pragma nojtbound}
14339
14340 \end_inset
14341
14342  - will not generate code for boundary value checking, when switch statements
14343  are turned into jump-tables (dangerous).
14344  For more details see section
14345 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
14346
14347 \end_inset
14348
14349 .
14350 \layout Itemize
14351
14352 noloopreverse
14353 \begin_inset LatexCommand \index{\#pragma noloopreverse}
14354
14355 \end_inset
14356
14357  - Will not do loop reversal optimization
14358 \layout Itemize
14359
14360 nooverlay
14361 \begin_inset LatexCommand \index{\#pragma nooverlay}
14362
14363 \end_inset
14364
14365  - the compiler will not overlay the parameters and local variables of a
14366  function.
14367 \layout Itemize
14368
14369 stackauto
14370 \begin_inset LatexCommand \index{\#pragma stackauto}
14371
14372 \end_inset
14373
14374 - See option -
14375 \begin_inset ERT
14376 status Collapsed
14377
14378 \layout Standard
14379
14380 \backslash
14381 /
14382 \end_inset
14383
14384 -stack-auto
14385 \begin_inset LatexCommand \index{-\/-stack-auto}
14386
14387 \end_inset
14388
14389  and section
14390 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
14391
14392 \end_inset
14393
14394  Parameters and Local Variables.
14395 \layout Itemize
14396
14397 opt_code_speed
14398 \begin_inset LatexCommand \index{\#pragma opt\_code\_speed}
14399
14400 \end_inset
14401
14402 - The compiler will optimize code generation towards fast code, possibly
14403  at the expense of code size.
14404 \layout Itemize
14405
14406 opt_code_size
14407 \begin_inset LatexCommand \index{\#pragma opt\_code\_size}
14408
14409 \end_inset
14410
14411 - The compiler will optimize code generation towards compact code, possibly
14412  at the expense of code speed.
14413 \layout Itemize
14414
14415 opt_code_balanced
14416 \begin_inset LatexCommand \index{\#pragma opt\_code\_balanced}
14417
14418 \end_inset
14419
14420 - The compiler will attempt to generate code that is both compact and fast,
14421  as long as meeting one goal is not a detriment to the other (this is the
14422  default).
14423
14424 \layout Standard
14425
14426 SDCPP supports the following #pragma directives:
14427 \layout Itemize
14428
14429 preproc_asm
14430 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
14431
14432 \end_inset
14433
14434  (+ | -) - switch _asm _endasm block preprocessing on / off.
14435  Default is on.
14436 \layout Standard
14437
14438 The pragma's are intended to be used to turn-on or off certain optimizations
14439  which might cause the compiler to generate extra stack / data space to
14440  store compiler generated temporary variables.
14441  This usually happens in large functions.
14442  Pragma directives should be used as shown in the following example, they
14443  are used to control options & optimizations for a given function; pragmas
14444  should be placed before and/or after a function, placing pragma's inside
14445  a function body could have unpredictable results.
14446 \layout Verse
14447
14448
14449 \family typewriter
14450 #pragma save
14451 \begin_inset LatexCommand \index{\#pragma save}
14452
14453 \end_inset
14454
14455  \SpecialChar ~
14456 \SpecialChar ~
14457 \SpecialChar ~
14458 \SpecialChar ~
14459 \SpecialChar ~
14460 \SpecialChar ~
14461 \SpecialChar ~
14462 /* save the current settings */
14463 \newline
14464 #pragma nogcse
14465 \begin_inset LatexCommand \index{\#pragma nogcse}
14466
14467 \end_inset
14468
14469  \SpecialChar ~
14470 \SpecialChar ~
14471 \SpecialChar ~
14472 \SpecialChar ~
14473 \SpecialChar ~
14474 /* turnoff global subexpression elimination */
14475 \newline
14476 #pragma noinduction
14477 \begin_inset LatexCommand \index{\#pragma noinduction}
14478
14479 \end_inset
14480
14481  /* turn off induction optimizations */
14482 \newline
14483 int foo ()
14484 \newline
14485 {
14486 \newline
14487 \SpecialChar ~
14488  \SpecialChar ~
14489  ...
14490
14491 \newline
14492 \SpecialChar ~
14493  \SpecialChar ~
14494  /* large code */
14495 \newline
14496 \SpecialChar ~
14497  \SpecialChar ~
14498  ...
14499
14500 \newline
14501 }
14502 \newline
14503 #pragma restore
14504 \begin_inset LatexCommand \index{\#pragma restore}
14505
14506 \end_inset
14507
14508  /* turn the optimizations back on */
14509 \layout Standard
14510
14511 The compiler will generate a warning message when extra space is allocated.
14512  It is strongly recommended that the save and restore pragma's be used when
14513  changing options for a function.
14514 \layout Section
14515
14516 Defines Created by the Compiler
14517 \layout Standard
14518
14519 The compiler creates the following #defines
14520 \begin_inset LatexCommand \index{\#defines}
14521
14522 \end_inset
14523
14524
14525 \begin_inset LatexCommand \index{Defines created by the compiler}
14526
14527 \end_inset
14528
14529 :
14530 \newline
14531
14532 \layout Standard
14533
14534
14535 \begin_inset  Tabular
14536 <lyxtabular version="3" rows="10" columns="2">
14537 <features>
14538 <column alignment="center" valignment="top" leftline="true" width="0">
14539 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
14540 <row topline="true" bottomline="true">
14541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14542 \begin_inset Text
14543
14544 \layout Standard
14545
14546
14547 \series bold
14548 #define
14549 \end_inset
14550 </cell>
14551 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14552 \begin_inset Text
14553
14554 \layout Standard
14555
14556
14557 \series bold
14558 Description
14559 \end_inset
14560 </cell>
14561 </row>
14562 <row topline="true">
14563 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14564 \begin_inset Text
14565
14566 \layout Standard
14567
14568 SDCC
14569 \begin_inset LatexCommand \index{SDCC}
14570
14571 \end_inset
14572
14573
14574 \end_inset
14575 </cell>
14576 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14577 \begin_inset Text
14578
14579 \layout Standard
14580
14581 this Symbol is always defined
14582 \end_inset
14583 </cell>
14584 </row>
14585 <row topline="true">
14586 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14587 \begin_inset Text
14588
14589 \layout Standard
14590
14591 SDCC_mcs51
14592 \begin_inset LatexCommand \index{SDCC\_mcs51}
14593
14594 \end_inset
14595
14596  or SDCC_ds390
14597 \begin_inset LatexCommand \index{SDCC\_ds390}
14598
14599 \end_inset
14600
14601  or SDCC_z80
14602 \begin_inset LatexCommand \index{SDCC\_z80}
14603
14604 \end_inset
14605
14606 , etc
14607 \end_inset
14608 </cell>
14609 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14610 \begin_inset Text
14611
14612 \layout Standard
14613
14614 depending on the model used (e.g.: -mds390
14615 \end_inset
14616 </cell>
14617 </row>
14618 <row topline="true">
14619 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14620 \begin_inset Text
14621
14622 \layout Standard
14623
14624 __mcs51
14625 \begin_inset LatexCommand \index{\_\_mcs51}
14626
14627 \end_inset
14628
14629 , __ds390
14630 \begin_inset LatexCommand \index{\_\_ds390}
14631
14632 \end_inset
14633
14634 , __hc08
14635 \begin_inset LatexCommand \index{\_\_hc08}
14636
14637 \end_inset
14638
14639 , __z80
14640 \begin_inset LatexCommand \index{\_\_z80}
14641
14642 \end_inset
14643
14644 , etc
14645 \end_inset
14646 </cell>
14647 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14648 \begin_inset Text
14649
14650 \layout Standard
14651
14652 depending on the model used (e.g.
14653  -mz80)
14654 \end_inset
14655 </cell>
14656 </row>
14657 <row topline="true">
14658 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14659 \begin_inset Text
14660
14661 \layout Standard
14662
14663 SDCC_STACK_AUTO
14664 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
14665
14666 \end_inset
14667
14668
14669 \end_inset
14670 </cell>
14671 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14672 \begin_inset Text
14673
14674 \layout Standard
14675
14676 when
14677 \emph on
14678 -
14679 \begin_inset ERT
14680 status Collapsed
14681
14682 \layout Standard
14683
14684 \backslash
14685 /
14686 \end_inset
14687
14688 -stack-auto
14689 \emph default
14690  option is used
14691 \end_inset
14692 </cell>
14693 </row>
14694 <row topline="true">
14695 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14696 \begin_inset Text
14697
14698 \layout Standard
14699
14700 SDCC_MODEL_SMALL
14701 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
14702
14703 \end_inset
14704
14705
14706 \end_inset
14707 </cell>
14708 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14709 \begin_inset Text
14710
14711 \layout Standard
14712
14713 when
14714 \emph on
14715 -
14716 \begin_inset ERT
14717 status Collapsed
14718
14719 \layout Standard
14720
14721 \backslash
14722 /
14723 \end_inset
14724
14725 -model-small
14726 \emph default
14727  is used
14728 \end_inset
14729 </cell>
14730 </row>
14731 <row topline="true">
14732 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14733 \begin_inset Text
14734
14735 \layout Standard
14736
14737 SDCC_MODEL_LARGE
14738 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
14739
14740 \end_inset
14741
14742
14743 \end_inset
14744 </cell>
14745 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14746 \begin_inset Text
14747
14748 \layout Standard
14749
14750 when
14751 \emph on
14752 -
14753 \begin_inset ERT
14754 status Collapsed
14755
14756 \layout Standard
14757
14758 \backslash
14759 /
14760 \end_inset
14761
14762 -model-large
14763 \emph default
14764  is used
14765 \end_inset
14766 </cell>
14767 </row>
14768 <row topline="true">
14769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14770 \begin_inset Text
14771
14772 \layout Standard
14773
14774 SDCC_USE_XSTACK
14775 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
14776
14777 \end_inset
14778
14779
14780 \end_inset
14781 </cell>
14782 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14783 \begin_inset Text
14784
14785 \layout Standard
14786
14787 when
14788 \emph on
14789 -
14790 \begin_inset ERT
14791 status Collapsed
14792
14793 \layout Standard
14794
14795 \backslash
14796 /
14797 \end_inset
14798
14799 -xstack
14800 \emph default
14801  option is used
14802 \end_inset
14803 </cell>
14804 </row>
14805 <row topline="true">
14806 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14807 \begin_inset Text
14808
14809 \layout Standard
14810
14811 SDCC_STACK_TENBIT
14812 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
14813
14814 \end_inset
14815
14816
14817 \end_inset
14818 </cell>
14819 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14820 \begin_inset Text
14821
14822 \layout Standard
14823
14824 when
14825 \emph on
14826 -mds390
14827 \emph default
14828  is used
14829 \end_inset
14830 </cell>
14831 </row>
14832 <row topline="true" bottomline="true">
14833 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14834 \begin_inset Text
14835
14836 \layout Standard
14837
14838 SDCC_MODEL_FLAT24
14839 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
14840
14841 \end_inset
14842
14843
14844 \end_inset
14845 </cell>
14846 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14847 \begin_inset Text
14848
14849 \layout Standard
14850
14851 when
14852 \emph on
14853 -mds390
14854 \emph default
14855  is used
14856 \end_inset
14857 </cell>
14858 </row>
14859 </lyxtabular>
14860
14861 \end_inset
14862
14863
14864 \layout Chapter
14865
14866 Notes on supported Processors
14867 \layout Section
14868
14869 MCS51 variants
14870 \begin_inset LatexCommand \label{sub:MCS51-variants}
14871
14872 \end_inset
14873
14874
14875 \begin_inset LatexCommand \index{MCS51 variants}
14876
14877 \end_inset
14878
14879
14880 \layout Standard
14881
14882 MCS51 processors are available from many vendors and come in many different
14883  flavours.
14884  While they might differ considerably in respect to Special Function Registers
14885  the core MCS51 is usually not modified or is kept compatible.
14886
14887 \layout Subsection
14888
14889 pdata access by SFR
14890 \layout Standard
14891
14892 With the upcome of devices with internal xdata and flash memory devices
14893  using port P2
14894 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14895
14896 \end_inset
14897
14898  as dedicated I/O port is becoming more popular.
14899  Switching the high byte for pdata
14900 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14901
14902 \end_inset
14903
14904  access which was formerly done by port P2 is then achieved by a Special
14905  Function Register
14906 \begin_inset LatexCommand \index{sfr}
14907
14908 \end_inset
14909
14910 .
14911  In well-established MCS51 tradition the address of this
14912 \emph on
14913 sfr
14914 \emph default
14915  is where the chip designers decided to put it.
14916  Needless to say that they didn't agree on a common name either.
14917  So that the startup code can correctly initialize xdata variables, you
14918  should define an sfr with the name _XPAGE
14919 \family typewriter
14920
14921 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
14922
14923 \end_inset
14924
14925
14926 \family default
14927  at the appropriate location if the default, port P2, is not used for this.
14928  Some examples are:
14929 \layout Verse
14930
14931
14932 \family typewriter
14933 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
14934 \layout Verse
14935
14936
14937 \family typewriter
14938 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
14939 \layout Verse
14940
14941
14942 \family typewriter
14943 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
14944 \layout Standard
14945
14946 For more exotic implementations further customizations may be needed.
14947  See section
14948 \begin_inset LatexCommand \ref{sub:Startup-Code}
14949
14950 \end_inset
14951
14952  for other possibilities.
14953 \layout Subsection
14954
14955 Other Features available by SFR
14956 \layout Standard
14957
14958 Some MCS51 variants offer features like Double DPTR
14959 \begin_inset LatexCommand \index{DPTR}
14960
14961 \end_inset
14962
14963 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
14964  These are currently not used for the MCS51 port.
14965  If you absolutely need them you can fall back to inline assembly or submit
14966  a patch to SDCC.
14967 \layout Section
14968
14969 DS400 port
14970 \layout Standard
14971
14972 The DS80C400 microcontroller has a rich set of peripherals.
14973  In its built-in ROM library it includes functions to access some of the
14974  features, among them is a TCP stack with IP4 and IP6 support.
14975  Library headers (currently in beta status) and other files are provided
14976  at
14977 \size footnotesize
14978
14979 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
14980
14981 \end_inset
14982
14983 .
14984
14985 \layout Section
14986
14987 The Z80 and gbz80 port
14988 \layout Standard
14989
14990 SDCC can target both the Zilog
14991 \begin_inset LatexCommand \index{Z80}
14992
14993 \end_inset
14994
14995  and the Nintendo Gameboy's Z80-like gbz80
14996 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
14997
14998 \end_inset
14999
15000 .
15001  The Z80 port is passed through the same
15002 \emph on
15003 regressions tests
15004 \begin_inset LatexCommand \index{Regression test}
15005
15006 \end_inset
15007
15008
15009 \emph default
15010  as the MCS51 and DS390 ports, so floating point support, support for long
15011  variables and bitfield support is fine.
15012  See mailing lists and forums about interrupt routines.
15013 \layout Standard
15014
15015 As always, the code is the authoritative reference - see z80/ralloc.c and
15016  z80/gen.c.
15017  The stack
15018 \begin_inset LatexCommand \index{stack}
15019
15020 \end_inset
15021
15022  frame is similar to that generated by the IAR Z80 compiler.
15023  IX is used as the base pointer, HL and IY are used as a temporary registers,
15024  and BC and DE are available for holding variables.
15025  Return values
15026 \begin_inset LatexCommand \index{return value}
15027
15028 \end_inset
15029
15030  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
15031  bytes).
15032  The gbz80 port use the same set of registers for the return values, but
15033  in a different order of significance: E (one byte), DE (two bytes), or
15034  HLDE (four bytes).
15035 \layout Section
15036
15037 The HC08 port
15038 \layout Standard
15039
15040 The port to the Motorola HC08
15041 \begin_inset LatexCommand \index{HC08}
15042
15043 \end_inset
15044
15045  family has been added in October 2003, and is still undergoing some basic
15046  development.
15047  The code generator is complete, but the register allocation is still quite
15048  unoptimized.
15049  Some of the SDCC's standard C library functions have embedded non-HC08
15050  inline assembly and so are not yet usable.
15051 \newline
15052
15053 \newline
15054
15055 \layout Section
15056
15057 The PIC14 port
15058 \layout Standard
15059
15060 The 14bit PIC
15061 \begin_inset LatexCommand \index{PIC14}
15062
15063 \end_inset
15064
15065  port still requires a major effort from the development community.
15066  However it can work for very simple code.
15067 \layout Subsection
15068
15069 C code and 14bit PIC code page
15070 \begin_inset LatexCommand \index{code page (pic14)}
15071
15072 \end_inset
15073
15074  and RAM banks
15075 \begin_inset LatexCommand \index{RAM bank (pic14)}
15076
15077 \end_inset
15078
15079
15080 \layout Standard
15081
15082 The linker organizes allocation for the code page and RAM banks.
15083  It does not have intimate knowledge of the code flow.
15084  It will put all the code section of a single asm file into a single code
15085  page.
15086  In order to make use of multiple code pages, separate asm files must be
15087  used.
15088  The compiler treats all functions of a single C file as being in the same
15089  code page unless it is non static.
15090  The compiler treats all local variables of a single C file as being in
15091  the same RAM bank unless it is an extern.
15092 \newline
15093
15094 \newline
15095 To get the best follow these guide lines:
15096 \layout Enumerate
15097
15098 make local functions static, as non static functions require code page selection
15099  overhead.
15100 \layout Enumerate
15101
15102 Make local variables static as extern variables require RAM bank selection
15103  overhead.
15104 \layout Enumerate
15105
15106 For devices that have multiple code pages it is more efficient to use the
15107  same number of files as pages, i.e.
15108  for the 16F877 use 4 separate files and i.e.
15109  for the 16F874 use 2 separate files.
15110  This way the linker can put the code for each file into different code
15111  pages and the compiler can allocate reusable variables more efficiently
15112  and there's less page selection overhead.
15113  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
15114  instruction set) use 'unsigned char' whereever possible instead of 'int'.
15115 \layout Subsection
15116
15117 Creating a device include file
15118 \layout Standard
15119
15120 For generating a device include file use the support perl script inc2h.pl
15121  kept in directory support/script.
15122 \layout Subsection
15123
15124 Interrupt code
15125 \layout Standard
15126
15127 For the interrupt function, use the keyword 'interrupt'
15128 \begin_inset LatexCommand \index{interrupt}
15129
15130 \end_inset
15131
15132  with level number of 0 (PIC14 only has 1 interrupt so this number is only
15133  there to avoid a syntax error - it ought to be fixed).
15134  E.g.:
15135 \layout Verse
15136
15137
15138 \family typewriter
15139 void Intr(void) interrupt 0
15140 \newline
15141 {
15142 \newline
15143 \SpecialChar ~
15144 \SpecialChar ~
15145 T0IF = 0; /* Clear timer interrupt */
15146 \newline
15147 }
15148 \layout Subsection
15149
15150 Linking and assembling
15151 \layout Standard
15152
15153 For assembling you can use either GPUTILS'
15154 \begin_inset LatexCommand \index{gputils (pic tools)}
15155
15156 \end_inset
15157
15158  gpasm.exe or MPLAB's mpasmwin.exe.
15159  GPUTILS is available from
15160 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
15161
15162 \end_inset
15163
15164 .
15165  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
15166  If you use MPLAB and an interrupt function then the linker script file
15167  vectors section will need to be enlarged to link with mplink.
15168 \newline
15169
15170 \newline
15171 Here is a
15172 \family typewriter
15173 Makefile
15174 \family default
15175  using GPUTILS:
15176 \layout Verse
15177
15178
15179 \family typewriter
15180 .c.o:
15181 \newline
15182 \SpecialChar ~
15183 \SpecialChar ~
15184 \SpecialChar ~
15185 \SpecialChar ~
15186 \SpecialChar ~
15187 \SpecialChar ~
15188 \SpecialChar ~
15189 \SpecialChar ~
15190 sdcc -S -V -mpic14 -p16F877 $<
15191 \newline
15192 \SpecialChar ~
15193 \SpecialChar ~
15194 \SpecialChar ~
15195 \SpecialChar ~
15196 \SpecialChar ~
15197 \SpecialChar ~
15198 \SpecialChar ~
15199 \SpecialChar ~
15200 gpasm -c $*.asm
15201 \newline
15202
15203 \newline
15204 $(PRJ).hex: $(OBJS)
15205 \newline
15206 \SpecialChar ~
15207 \SpecialChar ~
15208 \SpecialChar ~
15209 \SpecialChar ~
15210 \SpecialChar ~
15211 \SpecialChar ~
15212 \SpecialChar ~
15213 \SpecialChar ~
15214 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
15215 \layout Standard
15216
15217 Here is a
15218 \family typewriter
15219 Makefile
15220 \family default
15221  using MPLAB:
15222 \layout Verse
15223
15224
15225 \family typewriter
15226 .c.o:
15227 \newline
15228 \SpecialChar ~
15229 \SpecialChar ~
15230 \SpecialChar ~
15231 \SpecialChar ~
15232 \SpecialChar ~
15233 \SpecialChar ~
15234 \SpecialChar ~
15235 \SpecialChar ~
15236 sdcc -S -V -mpic14 -p16F877 $<
15237 \newline
15238 \SpecialChar ~
15239 \SpecialChar ~
15240 \SpecialChar ~
15241 \SpecialChar ~
15242 \SpecialChar ~
15243 \SpecialChar ~
15244 \SpecialChar ~
15245 \SpecialChar ~
15246 mpasmwin /q /o $*.asm
15247 \newline
15248
15249 \newline
15250 $(PRJ).hex: $(OBJS)
15251 \newline
15252 \SpecialChar ~
15253 \SpecialChar ~
15254 \SpecialChar ~
15255 \SpecialChar ~
15256 \SpecialChar ~
15257 \SpecialChar ~
15258 \SpecialChar ~
15259 \SpecialChar ~
15260 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
15261 \layout Standard
15262
15263 Please note that indentations within a
15264 \family typewriter
15265  Makefile
15266 \family default
15267  have to be done with a tabulator character.
15268 \layout Section
15269
15270 The PIC16
15271 \begin_inset LatexCommand \index{PIC16}
15272
15273 \end_inset
15274
15275  port
15276 \layout Standard
15277
15278 The PIC16
15279 \begin_inset LatexCommand \index{PIC16}
15280
15281 \end_inset
15282
15283  port is the portion of SDCC that is responsible to produce code for the
15284  Microchip
15285 \begin_inset LatexCommand \index{Microchip}
15286
15287 \end_inset
15288
15289 (TM) microcontrollers with 16 bit core.
15290  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
15291  Currently supported devices are:
15292 \layout Standard
15293 \align center
15294
15295 \begin_inset  Tabular
15296 <lyxtabular version="3" rows="4" columns="6">
15297 <features>
15298 <column alignment="center" valignment="top" leftline="true" width="0">
15299 <column alignment="center" valignment="top" leftline="true" width="0">
15300 <column alignment="center" valignment="top" leftline="true" width="0">
15301 <column alignment="center" valignment="top" leftline="true" width="0">
15302 <column alignment="center" valignment="top" leftline="true" width="0">
15303 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15304 <row topline="true">
15305 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15306 \begin_inset Text
15307
15308 \layout Standard
15309
15310 18F242
15311 \end_inset
15312 </cell>
15313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15314 \begin_inset Text
15315
15316 \layout Standard
15317
15318 18F248
15319 \end_inset
15320 </cell>
15321 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15322 \begin_inset Text
15323
15324 \layout Standard
15325
15326 18F252
15327 \end_inset
15328 </cell>
15329 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15330 \begin_inset Text
15331
15332 \layout Standard
15333
15334 18F258
15335 \end_inset
15336 </cell>
15337 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15338 \begin_inset Text
15339
15340 \layout Standard
15341
15342 18F442
15343 \end_inset
15344 </cell>
15345 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15346 \begin_inset Text
15347
15348 \layout Standard
15349
15350 18F448
15351 \end_inset
15352 </cell>
15353 </row>
15354 <row topline="true">
15355 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15356 \begin_inset Text
15357
15358 \layout Standard
15359
15360 18F452
15361 \end_inset
15362 </cell>
15363 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15364 \begin_inset Text
15365
15366 \layout Standard
15367
15368 18F458
15369 \end_inset
15370 </cell>
15371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15372 \begin_inset Text
15373
15374 \layout Standard
15375
15376 18F1220
15377 \end_inset
15378 </cell>
15379 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15380 \begin_inset Text
15381
15382 \layout Standard
15383
15384 18F2220
15385 \end_inset
15386 </cell>
15387 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15388 \begin_inset Text
15389
15390 \layout Standard
15391
15392 18F2550
15393 \end_inset
15394 </cell>
15395 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15396 \begin_inset Text
15397
15398 \layout Standard
15399
15400 18F4331
15401 \end_inset
15402 </cell>
15403 </row>
15404 <row topline="true">
15405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15406 \begin_inset Text
15407
15408 \layout Standard
15409
15410 18F4455
15411 \end_inset
15412 </cell>
15413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15414 \begin_inset Text
15415
15416 \layout Standard
15417
15418 18F6520
15419 \end_inset
15420 </cell>
15421 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15422 \begin_inset Text
15423
15424 \layout Standard
15425
15426 18F6620
15427 \end_inset
15428 </cell>
15429 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15430 \begin_inset Text
15431
15432 \layout Standard
15433
15434 18F6680
15435 \end_inset
15436 </cell>
15437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15438 \begin_inset Text
15439
15440 \layout Standard
15441
15442 18F6720
15443 \end_inset
15444 </cell>
15445 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15446 \begin_inset Text
15447
15448 \layout Standard
15449
15450 18F8520
15451 \end_inset
15452 </cell>
15453 </row>
15454 <row topline="true" bottomline="true">
15455 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15456 \begin_inset Text
15457
15458 \layout Standard
15459
15460 18F8620
15461 \end_inset
15462 </cell>
15463 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15464 \begin_inset Text
15465
15466 \layout Standard
15467
15468 18F8680
15469 \end_inset
15470 </cell>
15471 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15472 \begin_inset Text
15473
15474 \layout Standard
15475
15476 18F8720
15477 \end_inset
15478 </cell>
15479 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15480 \begin_inset Text
15481
15482 \layout Standard
15483
15484 \end_inset
15485 </cell>
15486 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15487 \begin_inset Text
15488
15489 \layout Standard
15490
15491 \end_inset
15492 </cell>
15493 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15494 \begin_inset Text
15495
15496 \layout Standard
15497
15498 \end_inset
15499 </cell>
15500 </row>
15501 </lyxtabular>
15502
15503 \end_inset
15504
15505
15506 \layout Subsection
15507
15508 Global Options
15509 \layout Standard
15510
15511 PIC16 port supports the standard command line arguments as supposed, with
15512  the exception of certain cases that will be mentioned in the following
15513  list:
15514 \layout List
15515 \labelwidthstring 00.00.0000
15516
15517 -
15518 \begin_inset ERT
15519 status Collapsed
15520
15521 \layout Standard
15522
15523 \backslash
15524 /
15525 \end_inset
15526
15527 -callee-saves See -
15528 \begin_inset ERT
15529 status Collapsed
15530
15531 \layout Standard
15532
15533 \backslash
15534 /
15535 \end_inset
15536
15537 -all-callee-saves
15538 \layout List
15539 \labelwidthstring 00.00.0000
15540
15541 -
15542 \begin_inset ERT
15543 status Collapsed
15544
15545 \layout Standard
15546
15547 \backslash
15548 /
15549 \end_inset
15550
15551 -all-callee-saves All function arguments are passed on stack by default.
15552
15553 \emph on
15554 There is no need to specify this in the command line.
15555 \layout List
15556 \labelwidthstring 00.00.0000
15557
15558 -
15559 \begin_inset ERT
15560 status Collapsed
15561
15562 \layout Standard
15563
15564 \backslash
15565 /
15566 \end_inset
15567
15568 -fommit-frame-pointer Frame pointer will be omitted when the function uses
15569  no local variables.
15570 \layout Subsection
15571
15572 Port Specific Options
15573 \begin_inset LatexCommand \index{Options PIC16}
15574
15575 \end_inset
15576
15577
15578 \layout Standard
15579
15580 The port specific options appear after the global options in the sdcc --help
15581  output.
15582 \layout Subsubsection
15583
15584 General Options
15585 \layout Standard
15586
15587 General options enable certain port features and optimizations.
15588 \layout List
15589 \labelwidthstring 00.00.0000
15590
15591 -
15592 \begin_inset ERT
15593 status Collapsed
15594
15595 \layout Standard
15596
15597 \backslash
15598 /
15599 \end_inset
15600
15601 -stack-model=[model] Used in conjuction with the command above.
15602  Defines the stack model to be used, valid stack models are :
15603 \begin_deeper
15604 \layout List
15605 \labelwidthstring 00.00.0000
15606
15607
15608 \emph on
15609 small
15610 \emph default
15611  Selects small stack model.
15612  8 bit stack and frame pointers.
15613  Supports 256 bytes stack size.
15614 \layout List
15615 \labelwidthstring 00.00.0000
15616
15617
15618 \emph on
15619 large
15620 \emph default
15621  Selects large stack model.
15622  16 bit stack and frame pointers.
15623  Supports 65536 bytes stack size.
15624 \end_deeper
15625 \layout List
15626 \labelwidthstring 00.00.0000
15627
15628 -
15629 \begin_inset ERT
15630 status Collapsed
15631
15632 \layout Standard
15633
15634 \backslash
15635 /
15636 \end_inset
15637
15638 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
15639  unitialized data variables with [kword].
15640  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
15641 \layout List
15642 \labelwidthstring 00.00.0000
15643
15644 -
15645 \begin_inset ERT
15646 status Collapsed
15647
15648 \layout Standard
15649
15650 \backslash
15651 /
15652 \end_inset
15653
15654 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
15655  Useful for bootloaders.
15656 \layout List
15657 \labelwidthstring 00.00.0000
15658
15659 -
15660 \begin_inset ERT
15661 status Collapsed
15662
15663 \layout Standard
15664
15665 \backslash
15666 /
15667 \end_inset
15668
15669 -asm= sets the full path and name of an external assembler to call.
15670 \layout List
15671 \labelwidthstring 00.00.0000
15672
15673 -
15674 \begin_inset ERT
15675 status Collapsed
15676
15677 \layout Standard
15678
15679 \backslash
15680 /
15681 \end_inset
15682
15683 -link= sets the full path and name of an external linker to call.
15684 \layout List
15685 \labelwidthstring 00.00.0000
15686
15687 -
15688 \begin_inset ERT
15689 status Collapsed
15690
15691 \layout Standard
15692
15693 \backslash
15694 /
15695 \end_inset
15696
15697 -mplab-comp MPLAB compatibility option.
15698  Currently only suppresses special gpasm directives.
15699 \layout Subsubsection
15700
15701 Optimization Options
15702 \layout List
15703 \labelwidthstring 00.00.0000
15704
15705 -
15706 \begin_inset ERT
15707 status Collapsed
15708
15709 \layout Standard
15710
15711 \backslash
15712 /
15713 \end_inset
15714
15715 -optimize-goto Try to use (conditional) BRA instead of GOTO
15716 \layout List
15717 \labelwidthstring 00.00.0000
15718
15719 -
15720 \begin_inset ERT
15721 status Collapsed
15722
15723 \layout Standard
15724
15725 \backslash
15726 /
15727 \end_inset
15728
15729 -optimize-cmp Try to optimize some compares.
15730 \layout List
15731 \labelwidthstring 00.00.0000
15732
15733 -
15734 \begin_inset ERT
15735 status Collapsed
15736
15737 \layout Standard
15738
15739 \backslash
15740 /
15741 \end_inset
15742
15743 -obanksel=nn Set optimization level for inserting BANKSELs.
15744 \newline
15745
15746 \begin_deeper
15747 \layout List
15748 \labelwidthstring 00.00.0000
15749
15750 0 no optimization
15751 \layout List
15752 \labelwidthstring 00.00.0000
15753
15754 1 checks previous used register and if it is the same then does not emit
15755  BANKSEL, accounts only for labels.
15756 \layout List
15757 \labelwidthstring 00.00.0000
15758
15759 2 tries to check the location of (even different) symbols and removes BANKSELs
15760  if they are in the same bank.
15761
15762 \newline
15763
15764 \emph on
15765 Important: There might be problems if the linker script has data sections
15766  across bank borders!
15767 \end_deeper
15768 \layout Subsubsection
15769
15770 Linking Options
15771 \layout List
15772 \labelwidthstring 00.00.0000
15773
15774 -
15775 \begin_inset ERT
15776 status Collapsed
15777
15778 \layout Standard
15779
15780 \backslash
15781 /
15782 \end_inset
15783
15784 -nodefaultlibs do not link default libraries when linking
15785 \layout List
15786 \labelwidthstring 00.00.0000
15787
15788 -
15789 \begin_inset ERT
15790 status Collapsed
15791
15792 \layout Standard
15793
15794 \backslash
15795 /
15796 \end_inset
15797
15798 -no-crt Don't link the default run-time modules
15799 \layout List
15800 \labelwidthstring 00.00.0000
15801
15802 -
15803 \begin_inset ERT
15804 status Collapsed
15805
15806 \layout Standard
15807
15808 \backslash
15809 /
15810 \end_inset
15811
15812 -use-crt= Use a custom run-time module instead of the defaults.
15813 \layout Subsubsection
15814
15815 Debugging Options
15816 \layout Standard
15817
15818 Debugging options enable extra debugging information in the output files.
15819 \layout List
15820 \labelwidthstring 00.00.0000
15821
15822 -
15823 \begin_inset ERT
15824 status Collapsed
15825
15826 \layout Standard
15827
15828 \backslash
15829 /
15830 \end_inset
15831
15832 -debug-xtra Similar to -
15833 \begin_inset ERT
15834 status Collapsed
15835
15836 \layout Standard
15837
15838 \backslash
15839 /
15840 \end_inset
15841
15842 -debug
15843 \begin_inset LatexCommand \index{-\/-debug}
15844
15845 \end_inset
15846
15847 , but dumps more information.
15848 \layout List
15849 \labelwidthstring 00.00.0000
15850
15851 -
15852 \begin_inset ERT
15853 status Collapsed
15854
15855 \layout Standard
15856
15857 \backslash
15858 /
15859 \end_inset
15860
15861 -debug-ralloc Force register allocator to dump <source>.d file with debugging
15862  information.
15863  <source> is the name of the file compiled.
15864 \layout List
15865 \labelwidthstring 00.00.0000
15866
15867 -
15868 \begin_inset ERT
15869 status Collapsed
15870
15871 \layout Standard
15872
15873 \backslash
15874 /
15875 \end_inset
15876
15877 -pcode-verbose Enable pcode debugging information in translation.
15878 \layout List
15879 \labelwidthstring 00.00.0000
15880
15881 -
15882 \begin_inset ERT
15883 status Collapsed
15884
15885 \layout Standard
15886
15887 \backslash
15888 /
15889 \end_inset
15890
15891 -denable-peeps Force the usage of peepholes.
15892  Use with care.
15893 \layout List
15894 \labelwidthstring 00.00.0000
15895
15896 -
15897 \begin_inset ERT
15898 status Collapsed
15899
15900 \layout Standard
15901
15902 \backslash
15903 /
15904 \end_inset
15905
15906 -gstack Trace push/pops for stack pointer overflow
15907 \layout List
15908 \labelwidthstring 00.00.0000
15909
15910 -
15911 \begin_inset ERT
15912 status Collapsed
15913
15914 \layout Standard
15915
15916 \backslash
15917 /
15918 \end_inset
15919
15920 -call-tree dump call tree in .calltree file
15921 \layout Subsection
15922
15923 Enviromental Variables
15924 \layout Standard
15925
15926 There is a number of enviromental variables that can be used when running
15927  SDCC to enable certain optimizations or force a specific program behaviour.
15928  these variables are primarily for debugging purposes so they can be enabled/dis
15929 abled at will.
15930 \layout Standard
15931
15932 Currently there is only two such variables available:
15933 \layout List
15934 \labelwidthstring 00.00.0000
15935
15936 OPTIMIZE_BITFIELD_POINTER_GET when this variable exists reading of structure
15937  bitfields is optimized by directly loading FSR0 with the address of the
15938  bitfield structure.
15939  Normally SDCC will cast the bitfield structure to a bitfield pointer and
15940  then load FSR0.
15941  This step saves data ram and code space for functions that perform heavy
15942  use of bitfields.
15943  (ie.
15944  80 bytes of code space are saved when compiling malloc.c with this option).
15945
15946 \layout List
15947 \labelwidthstring 00.00.0000
15948
15949 NO_REG_OPT do not perform pCode registers optimization.
15950  This should be used for debugging purposes.
15951  In some where bugs in the pcode optimizer are found, users can benefit
15952  from temporarily disabling the optimizer until the bug is fixed.
15953 \layout Subsection
15954
15955 Preprocessor Macros
15956 \layout Standard
15957
15958 PIC16 port defines the following preprocessor macros while translating a
15959  source.
15960 \layout Standard
15961 \align center
15962
15963 \begin_inset  Tabular
15964 <lyxtabular version="3" rows="6" columns="2">
15965 <features>
15966 <column alignment="center" valignment="top" leftline="true" width="0">
15967 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15968 <row topline="true" bottomline="true">
15969 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15970 \begin_inset Text
15971
15972 \layout Standard
15973
15974 Macro
15975 \end_inset
15976 </cell>
15977 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15978 \begin_inset Text
15979
15980 \layout Standard
15981
15982 Description
15983 \end_inset
15984 </cell>
15985 </row>
15986 <row topline="true">
15987 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15988 \begin_inset Text
15989
15990 \layout Standard
15991
15992 SDCC_pic16
15993 \end_inset
15994 </cell>
15995 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15996 \begin_inset Text
15997
15998 \layout Standard
15999
16000 Port identification
16001 \end_inset
16002 </cell>
16003 </row>
16004 <row topline="true">
16005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16006 \begin_inset Text
16007
16008 \layout Standard
16009
16010 _
16011 \begin_inset ERT
16012 status Collapsed
16013
16014 \layout Standard
16015
16016 \backslash
16017 /
16018 \end_inset
16019
16020 _pic16
16021 \end_inset
16022 </cell>
16023 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16024 \begin_inset Text
16025
16026 \layout Standard
16027
16028 Port identification (same as above)
16029 \end_inset
16030 </cell>
16031 </row>
16032 <row topline="true">
16033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16034 \begin_inset Text
16035
16036 \layout Standard
16037
16038 pic18fxxxx
16039 \end_inset
16040 </cell>
16041 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16042 \begin_inset Text
16043
16044 \layout Standard
16045
16046 MCU Identification.
16047
16048 \emph on
16049 xxxx
16050 \emph default
16051  is the microcontrol identification number, i.e.
16052  452, 6620, etc
16053 \end_inset
16054 </cell>
16055 </row>
16056 <row topline="true">
16057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16058 \begin_inset Text
16059
16060 \layout Standard
16061
16062 _
16063 \begin_inset ERT
16064 status Collapsed
16065
16066 \layout Standard
16067
16068 \backslash
16069 /
16070 \end_inset
16071
16072 _18Fxxxx
16073 \end_inset
16074 </cell>
16075 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16076 \begin_inset Text
16077
16078 \layout Standard
16079
16080 MCU Identification (same as above)
16081 \end_inset
16082 </cell>
16083 </row>
16084 <row topline="true" bottomline="true">
16085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16086 \begin_inset Text
16087
16088 \layout Standard
16089
16090 STACK_MODEL_nnn
16091 \end_inset
16092 </cell>
16093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16094 \begin_inset Text
16095
16096 \layout Standard
16097
16098 nnn = SMALL or LARGE respectively according to the stack model used
16099 \end_inset
16100 </cell>
16101 </row>
16102 </lyxtabular>
16103
16104 \end_inset
16105
16106
16107 \layout Standard
16108
16109 In addition the following macros are defined when calling assembler:
16110 \layout Standard
16111 \align center
16112
16113 \begin_inset  Tabular
16114 <lyxtabular version="3" rows="4" columns="2">
16115 <features>
16116 <column alignment="center" valignment="top" leftline="true" width="0">
16117 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16118 <row topline="true" bottomline="true">
16119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16120 \begin_inset Text
16121
16122 \layout Standard
16123
16124 Macro
16125 \end_inset
16126 </cell>
16127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16128 \begin_inset Text
16129
16130 \layout Standard
16131
16132 Description
16133 \end_inset
16134 </cell>
16135 </row>
16136 <row topline="true">
16137 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16138 \begin_inset Text
16139
16140 \layout Standard
16141
16142 __18Fxxxx
16143 \end_inset
16144 </cell>
16145 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16146 \begin_inset Text
16147
16148 \layout Standard
16149
16150 MCU Identification.
16151
16152 \emph on
16153 xxxx
16154 \emph default
16155  is the microcontrol identification number, i.e.
16156  452, 6620, etc
16157 \end_inset
16158 </cell>
16159 </row>
16160 <row topline="true">
16161 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16162 \begin_inset Text
16163
16164 \layout Standard
16165
16166 SDCC_MODEL_nnn
16167 \end_inset
16168 </cell>
16169 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16170 \begin_inset Text
16171
16172 \layout Standard
16173
16174 nnn = SMALL or LARGE respectively according to the memory model used for
16175  SDCC
16176 \end_inset
16177 </cell>
16178 </row>
16179 <row topline="true" bottomline="true">
16180 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16181 \begin_inset Text
16182
16183 \layout Standard
16184
16185 STACK_MODEL_nnn
16186 \end_inset
16187 </cell>
16188 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16189 \begin_inset Text
16190
16191 \layout Standard
16192
16193 nnn = SMALL or LARGE respectively according to the stack model used
16194 \end_inset
16195 </cell>
16196 </row>
16197 </lyxtabular>
16198
16199 \end_inset
16200
16201
16202 \layout Subsection
16203
16204 Directories
16205 \layout Standard
16206
16207 PIC16
16208 \begin_inset LatexCommand \index{PIC16}
16209
16210 \end_inset
16211
16212  port uses the following directories for searching header files and libraries.
16213 \layout Standard
16214 \align center
16215
16216 \begin_inset  Tabular
16217 <lyxtabular version="3" rows="3" columns="4">
16218 <features>
16219 <column alignment="center" valignment="top" leftline="true" width="0">
16220 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16221 <column alignment="center" valignment="top" width="0">
16222 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16223 <row topline="true" bottomline="true">
16224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16225 \begin_inset Text
16226
16227 \layout Standard
16228
16229 Directory
16230 \end_inset
16231 </cell>
16232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16233 \begin_inset Text
16234
16235 \layout Standard
16236
16237 Description
16238 \end_inset
16239 </cell>
16240 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16241 \begin_inset Text
16242
16243 \layout Standard
16244
16245 Target
16246 \end_inset
16247 </cell>
16248 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16249 \begin_inset Text
16250
16251 \layout Standard
16252
16253 Command prefix
16254 \end_inset
16255 </cell>
16256 </row>
16257 <row topline="true">
16258 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16259 \begin_inset Text
16260
16261 \layout Standard
16262
16263 PREFIX/sdcc/include/pic16
16264 \end_inset
16265 </cell>
16266 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16267 \begin_inset Text
16268
16269 \layout Standard
16270
16271 PIC16 specific headers
16272 \end_inset
16273 </cell>
16274 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16275 \begin_inset Text
16276
16277 \layout Standard
16278
16279 Compiler
16280 \end_inset
16281 </cell>
16282 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16283 \begin_inset Text
16284
16285 \layout Standard
16286
16287 -I
16288 \end_inset
16289 </cell>
16290 </row>
16291 <row topline="true" bottomline="true">
16292 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16293 \begin_inset Text
16294
16295 \layout Standard
16296
16297 PREFIX/sdcc/lib/pic16
16298 \end_inset
16299 </cell>
16300 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16301 \begin_inset Text
16302
16303 \layout Standard
16304
16305 PIC16 specific libraries
16306 \end_inset
16307 </cell>
16308 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16309 \begin_inset Text
16310
16311 \layout Standard
16312
16313 Linker
16314 \end_inset
16315 </cell>
16316 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16317 \begin_inset Text
16318
16319 \layout Standard
16320
16321 -L
16322 \end_inset
16323 </cell>
16324 </row>
16325 </lyxtabular>
16326
16327 \end_inset
16328
16329
16330 \layout Subsection
16331
16332 Pragmas
16333 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
16334
16335 \end_inset
16336
16337
16338 \layout Standard
16339
16340 PIC16 port currently supports the following pragmas:
16341 \layout List
16342 \labelwidthstring 00.00.0000
16343
16344 stack pragma stack forces the code generator to initialize the stack & frame
16345  pointers at a specific address.
16346  This is an adhoc solution for cases where no STACK directive is available
16347  in the linker script or gplink is not instructed to create a stack section.
16348 \newline
16349 The stack pragma should be used only once in a project.
16350  Multiple pragmas may result in indeterminate behaviour of the program.
16351 \begin_inset Foot
16352 collapsed false
16353
16354 \layout Standard
16355
16356 The old format (ie.
16357  #pragma stack 0x5ff) is deprecated and will cause the stack pointer to
16358  cross page boundaries (or even exceed the available data RAM) and crash
16359  the program.
16360  Make sure that stack does not cross page boundaries when using the SMALL
16361  stack model.
16362 \end_inset
16363
16364
16365 \newline
16366 The format is as follows:
16367 \layout LyX-Code
16368
16369 #pragma stack bottom_address [stack_size]
16370 \layout Standard
16371
16372
16373 \emph on
16374 bottom_address
16375 \emph default
16376  is the lower bound of the stack section.
16377  The stack pointer initially will point at address (bottom_address+stack_size-1).
16378 \layout LyX-Code
16379
16380 Example:
16381 \layout LyX-Code
16382
16383 \layout LyX-Code
16384
16385 /* initializes stack of 100 bytes at RAM address 0x200 */
16386 \layout LyX-Code
16387
16388 #pragma stack 0x200 100
16389 \layout Standard
16390
16391 If the stack_size field is omitted then a stack is created with the default
16392  size of 64.
16393  This size might be enough for most programs, but its not enough for operations
16394  with deep function nesting or excessive stack usage.
16395 \layout List
16396 \labelwidthstring 00.00.0000
16397
16398 wparam
16399 \emph on
16400 This pragma is deprecated.
16401  Its use will cause a warning message to be issued.
16402 \emph default
16403
16404 \newline
16405
16406 \layout List
16407 \labelwidthstring 00.00.0000
16408
16409 code place a function symbol at static FLASH address
16410 \layout LyX-Code
16411
16412 Example:
16413 \layout LyX-Code
16414
16415 \layout LyX-Code
16416
16417 /* place function test_func at 0x4000 */
16418 \layout LyX-Code
16419
16420 #pragma code test_func 0x4000
16421 \layout LyX-Code
16422
16423 \layout List
16424 \labelwidthstring 00.00.0000
16425
16426 library instructs the linker to use a library module.
16427 \newline
16428 Usage:
16429 \layout LyX-Code
16430
16431 #pragma library module_name
16432 \layout Standard
16433
16434
16435 \emph on
16436 module_name
16437 \emph default
16438  can be any library or object file (including its path).
16439  Note that there are four reserved keywords which have special meaning.
16440  These are:
16441 \layout Standard
16442 \align center
16443
16444 \begin_inset  Tabular
16445 <lyxtabular version="3" rows="6" columns="3">
16446 <features>
16447 <column alignment="center" valignment="top" leftline="true" width="0">
16448 <column alignment="block" valignment="top" leftline="true" width="20page%">
16449 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0">
16450 <row topline="true" bottomline="true">
16451 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16452 \begin_inset Text
16453
16454 \layout Standard
16455
16456 Keyword
16457 \end_inset
16458 </cell>
16459 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16460 \begin_inset Text
16461
16462 \layout Standard
16463
16464 Description
16465 \end_inset
16466 </cell>
16467 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16468 \begin_inset Text
16469
16470 \layout Standard
16471
16472 Module to link
16473 \end_inset
16474 </cell>
16475 </row>
16476 <row topline="true">
16477 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16478 \begin_inset Text
16479
16480 \layout Standard
16481
16482
16483 \series bold
16484 ignore
16485 \end_inset
16486 </cell>
16487 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16488 \begin_inset Text
16489
16490 \layout Standard
16491
16492 ignore all library pragmas
16493 \end_inset
16494 </cell>
16495 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16496 \begin_inset Text
16497
16498 \layout Standard
16499
16500
16501 \emph on
16502 (none)
16503 \end_inset
16504 </cell>
16505 </row>
16506 <row topline="true">
16507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16508 \begin_inset Text
16509
16510 \layout Standard
16511
16512
16513 \series bold
16514 c
16515 \end_inset
16516 </cell>
16517 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16518 \begin_inset Text
16519
16520 \layout Standard
16521
16522 link the C library
16523 \end_inset
16524 </cell>
16525 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16526 \begin_inset Text
16527
16528 \layout Standard
16529
16530
16531 \emph on
16532 libc18f
16533 \emph default
16534 .lib
16535 \end_inset
16536 </cell>
16537 </row>
16538 <row topline="true">
16539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16540 \begin_inset Text
16541
16542 \layout Standard
16543
16544
16545 \series bold
16546 math
16547 \end_inset
16548 </cell>
16549 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16550 \begin_inset Text
16551
16552 \layout Standard
16553
16554 link the Math libarary
16555 \end_inset
16556 </cell>
16557 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16558 \begin_inset Text
16559
16560 \layout Standard
16561
16562
16563 \emph on
16564 libm18f
16565 \emph default
16566 .lib
16567 \end_inset
16568 </cell>
16569 </row>
16570 <row topline="true">
16571 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16572 \begin_inset Text
16573
16574 \layout Standard
16575
16576
16577 \series bold
16578 io
16579 \end_inset
16580 </cell>
16581 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16582 \begin_inset Text
16583
16584 \layout Standard
16585
16586 link the I/O library
16587 \end_inset
16588 </cell>
16589 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16590 \begin_inset Text
16591
16592 \layout Standard
16593
16594
16595 \emph on
16596 libio18f*
16597 \emph default
16598 .lib
16599 \end_inset
16600 </cell>
16601 </row>
16602 <row topline="true" bottomline="true">
16603 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16604 \begin_inset Text
16605
16606 \layout Standard
16607
16608
16609 \series bold
16610 debug
16611 \end_inset
16612 </cell>
16613 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16614 \begin_inset Text
16615
16616 \layout Standard
16617
16618 link the debug library
16619 \end_inset
16620 </cell>
16621 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16622 \begin_inset Text
16623
16624 \layout Standard
16625
16626
16627 \emph on
16628 libdebug
16629 \emph default
16630 .lib
16631 \end_inset
16632 </cell>
16633 </row>
16634 </lyxtabular>
16635
16636 \end_inset
16637
16638
16639 \newline
16640 * is the device number, i.e.
16641  452 for PIC18F452 MCU.
16642 \layout Standard
16643
16644 This feature allows for linking with specific libraries withoug having to
16645  explicit name them in the command line.
16646  Note that the
16647 \noun on
16648 ignore
16649 \noun default
16650  keyword will reject all modules specified by the library pragma.
16651 \layout List
16652 \labelwidthstring 00.00.0000
16653
16654 udata pragma udata instructs the compiler to emit code so that linker will
16655  place a variable at a specific memory bank
16656 \layout LyX-Code
16657
16658 Example:
16659 \layout LyX-Code
16660
16661 \layout LyX-Code
16662
16663 /* places variable foo at bank2 */
16664 \layout LyX-Code
16665
16666 #pragma udata bank2 foo
16667 \layout LyX-Code
16668
16669 char foo;
16670 \layout Standard
16671
16672 In order for this pragma to work extra SECTION directives should be added
16673  in the .lkr script.
16674  In the following example a sample .lkr file is shown:
16675 \layout LyX-Code
16676
16677 \layout LyX-Code
16678
16679 // Sample linker script for the PIC18F452 processor
16680 \layout LyX-Code
16681
16682 LIBPATH .
16683 \layout LyX-Code
16684
16685 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
16686 \layout LyX-Code
16687
16688 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
16689 \layout LyX-Code
16690
16691 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
16692 \layout LyX-Code
16693
16694 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
16695 \layout LyX-Code
16696
16697 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
16698 \layout LyX-Code
16699
16700 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
16701 \layout LyX-Code
16702
16703 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
16704 \layout LyX-Code
16705
16706 \layout LyX-Code
16707
16708 DATABANK   NAME=gpr0       START=0x80           END=0xFF
16709 \layout LyX-Code
16710
16711 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
16712 \layout LyX-Code
16713
16714 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
16715 \layout LyX-Code
16716
16717 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
16718 \layout LyX-Code
16719
16720 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
16721 \layout LyX-Code
16722
16723 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
16724 \layout LyX-Code
16725
16726 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
16727 \layout LyX-Code
16728
16729 \layout LyX-Code
16730
16731 SECTION    NAME=CONFIG     ROM=config
16732 \layout LyX-Code
16733
16734 \layout LyX-Code
16735
16736 SECTION    NAME=bank0      RAM=gpr0       # these SECTION directives
16737 \layout LyX-Code
16738
16739 SECTION    NAME=bank1      RAM=gpr1       # should be added to link
16740 \layout LyX-Code
16741
16742 SECTION    NAME=bank2      RAM=gpr2       # section name 'bank?' with
16743 \layout LyX-Code
16744
16745 SECTION    NAME=bank3      RAM=gpr3       # a specific DATABANK name
16746 \layout LyX-Code
16747
16748 SECTION    NAME=bank4      RAM=gpr4
16749 \layout LyX-Code
16750
16751 SECTION    NAME=bank5      RAM=gpr5
16752 \layout Standard
16753
16754 The linker will recognise the section name set in the pragma statement and
16755  will position the variable at the memory bank set with the RAM field at
16756  the SECTION line in the linker script file.
16757 \layout Subsection
16758
16759 Header Files
16760 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
16761
16762 \end_inset
16763
16764
16765 \layout Standard
16766
16767 There is one main header file that can be included to the source files using
16768  the pic16 port.
16769  That file is the
16770 \series bold
16771 pic18fregs.h
16772 \series default
16773 .
16774  This header file contains the definitions for the processor special registers,
16775  so it is necessary if the source accesses them.
16776  It can be included by adding the following line in the beginning of the
16777  file:
16778 \layout LyX-Code
16779
16780 #include <pic18fregs.h>
16781 \layout Standard
16782
16783 The specific microcontroller is selected within the pic18fregs.h automatically,
16784  so the same source can be used with a variety of devices.
16785 \layout Subsection
16786
16787 Libraries
16788 \layout Standard
16789
16790 The libraries that PIC16
16791 \begin_inset LatexCommand \index{PIC16}
16792
16793 \end_inset
16794
16795  port depends on are the microcontroller device libraries which contain
16796  the symbol definitions for the microcontroller special function registers.
16797  These libraries have the format pic18fxxxx.lib, where
16798 \emph on
16799 xxxx
16800 \emph default
16801  is the microcontroller identification number.
16802  The specific library is selected automatically by the compiler at link
16803  stage according to the selected device.
16804 \layout Standard
16805
16806 Libraries are created with gplib which is part of the gputils package
16807 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
16808
16809 \end_inset
16810
16811 .
16812 \layout Subsubsection*
16813
16814 Building the libraries
16815 \layout Standard
16816
16817 Before using SDCC/pic16 there are some libraries that need to be compiled.
16818  This process is not done automatically by SDCC since not all users use
16819  SDCC for pic16 projects.
16820  So each user should compile the libraries separately.
16821 \layout Standard
16822
16823 The steps to compile the pic16 libraries under Linux are:
16824 \layout LyX-Code
16825
16826 cd device/lib/pic16
16827 \layout LyX-Code
16828
16829 ./configure
16830 \layout LyX-Code
16831
16832 make
16833 \layout LyX-Code
16834
16835 cd ..
16836 \layout LyX-Code
16837
16838 make model-pic16
16839 \layout LyX-Code
16840
16841 su -c 'make install'     # install the libraries, you need the root password
16842 \layout Standard
16843
16844 If you need to install the headers too, do:
16845 \layout LyX-Code
16846
16847 cd device/include
16848 \layout LyX-Code
16849
16850 su -c 'make install'     # install the headers, you need the root password
16851 \layout Standard
16852
16853 There exist a special target to build the I/O libraries.
16854  This target is not automatically build because it will build the I/O library
16855  for
16856 \emph on
16857 every
16858 \emph default
16859  supported device.
16860  This way building will take quite a lot of time.
16861  Users are advised to edit the
16862 \series bold
16863 device/lib/pic16/pics.build
16864 \series default
16865  file and then execute:
16866 \layout LyX-Code
16867
16868 make lib-io
16869 \layout Subsection
16870
16871 Memory Models
16872 \layout Standard
16873
16874 The following memory models are supported by the PIC16 port:
16875 \layout Itemize
16876
16877 small model
16878 \layout Itemize
16879
16880 large model
16881 \layout Standard
16882
16883 Memory model affects the default size of pointers within the source.
16884  The sizes are shown in the next table:
16885 \layout Standard
16886 \align center
16887
16888 \begin_inset  Tabular
16889 <lyxtabular version="3" rows="3" columns="3">
16890 <features>
16891 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16892 <column alignment="center" valignment="top" leftline="true" width="0">
16893 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16894 <row topline="true" bottomline="true">
16895 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16896 \begin_inset Text
16897
16898 \layout Standard
16899
16900 Pointer sizes according to memory model
16901 \end_inset
16902 </cell>
16903 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16904 \begin_inset Text
16905
16906 \layout Standard
16907
16908 small model
16909 \end_inset
16910 </cell>
16911 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16912 \begin_inset Text
16913
16914 \layout Standard
16915
16916 large model
16917 \end_inset
16918 </cell>
16919 </row>
16920 <row topline="true" bottomline="true">
16921 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16922 \begin_inset Text
16923
16924 \layout Standard
16925
16926 code pointers
16927 \end_inset
16928 </cell>
16929 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16930 \begin_inset Text
16931
16932 \layout Standard
16933
16934 16-bits
16935 \end_inset
16936 </cell>
16937 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16938 \begin_inset Text
16939
16940 \layout Standard
16941
16942 24-bits
16943 \end_inset
16944 </cell>
16945 </row>
16946 <row topline="true" bottomline="true">
16947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16948 \begin_inset Text
16949
16950 \layout Standard
16951
16952 data pointers
16953 \end_inset
16954 </cell>
16955 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
16956 \begin_inset Text
16957
16958 \layout Standard
16959
16960 16-bits
16961 \end_inset
16962 </cell>
16963 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16964 \begin_inset Text
16965
16966 \layout Standard
16967
16968 16-bits
16969 \end_inset
16970 </cell>
16971 </row>
16972 </lyxtabular>
16973
16974 \end_inset
16975
16976
16977 \layout Standard
16978
16979 It is advisable that all sources within a project are compiled with the
16980  same memory model.
16981  If one wants to override the default memory model, this can be done by
16982  declaring a pointer as
16983 \series bold
16984 far
16985 \series default
16986  or
16987 \series bold
16988 near
16989 \series default
16990 .
16991  Far selects large memory model's pointers, while near selects small memory
16992  model's pointers.
16993 \layout Standard
16994
16995 The standard device libraries (see
16996 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
16997
16998 \end_inset
16999
17000 ) contain no reference to pointers, so they can be used with both memory
17001  models.
17002 \layout Subsection
17003
17004 Stack
17005 \layout Standard
17006
17007 The stack implementation for the PIC16 port uses two indirect registers,
17008  FSR1 and FSR2.
17009 \layout List
17010 \labelwidthstring 00.00.0000
17011
17012 FSR1 is assigned as stack pointer
17013 \layout List
17014 \labelwidthstring 00.00.0000
17015
17016 FSR2 is assigned as frame pointer
17017 \layout Standard
17018
17019 The following stack models are supported by the PIC16 port
17020 \layout Itemize
17021
17022
17023 \noun on
17024 small
17025 \noun default
17026  model
17027 \layout Itemize
17028
17029
17030 \noun on
17031 large
17032 \noun default
17033  model
17034 \layout Standard
17035
17036
17037 \noun on
17038 Small
17039 \noun default
17040  model means that only the FSRxL byte is used to access stack and frame,
17041  while
17042 \emph on
17043 \noun on
17044 large
17045 \emph default
17046 \noun default
17047  uses both FSRxL and FSRxH registers.
17048  The following table shows the stack/frame pointers sizes according to stack
17049  model and the maximum space they can address:
17050 \layout Standard
17051 \align center
17052
17053 \begin_inset  Tabular
17054 <lyxtabular version="3" rows="3" columns="3">
17055 <features>
17056 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17057 <column alignment="center" valignment="top" leftline="true" width="0">
17058 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17059 <row topline="true" bottomline="true">
17060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17061 \begin_inset Text
17062
17063 \layout Standard
17064
17065 Stack & Frame pointer sizes according to stack model
17066 \end_inset
17067 </cell>
17068 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17069 \begin_inset Text
17070
17071 \layout Standard
17072
17073 small
17074 \end_inset
17075 </cell>
17076 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17077 \begin_inset Text
17078
17079 \layout Standard
17080
17081 large
17082 \end_inset
17083 </cell>
17084 </row>
17085 <row topline="true">
17086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17087 \begin_inset Text
17088
17089 \layout Standard
17090
17091 Stack pointer FSR1
17092 \end_inset
17093 </cell>
17094 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17095 \begin_inset Text
17096
17097 \layout Standard
17098
17099 8-bits
17100 \end_inset
17101 </cell>
17102 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17103 \begin_inset Text
17104
17105 \layout Standard
17106
17107 16-bits
17108 \end_inset
17109 </cell>
17110 </row>
17111 <row topline="true" bottomline="true">
17112 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17113 \begin_inset Text
17114
17115 \layout Standard
17116
17117 Frame pointer FSR2
17118 \end_inset
17119 </cell>
17120 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17121 \begin_inset Text
17122
17123 \layout Standard
17124
17125 8-bits
17126 \end_inset
17127 </cell>
17128 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17129 \begin_inset Text
17130
17131 \layout Standard
17132
17133 16-bits
17134 \end_inset
17135 </cell>
17136 </row>
17137 </lyxtabular>
17138
17139 \end_inset
17140
17141
17142 \layout Standard
17143
17144
17145 \noun on
17146 Large
17147 \noun default
17148 stack model is currently not working properly throughout the code generator.
17149  So its use is not advised.
17150  Also there are some other points that need special care:
17151 \newline
17152
17153 \layout Enumerate
17154
17155 Do not create stack sections with size more than one physical bank (that
17156  is 256 bytes)
17157 \layout Enumerate
17158
17159 Stack sections should no cross physical bank limits (i.e.
17160  #pragma stack 0x50 0x100)
17161 \layout Standard
17162
17163 These limitations are caused by the fact that only FSRxL is modified when
17164  using SMALL stack model, so no more than 256 bytes of stack can be used.
17165  This problem will disappear after LARGE model is fully implemented.
17166 \layout Subsection
17167
17168 Functions
17169 \layout Standard
17170
17171 In addition to the standard SDCC function keywords, PIC16 port makes available
17172  two more:
17173 \layout List
17174 \labelwidthstring 00.00.0000
17175
17176 wparam Use the WREG to pass one byte of the first function argument.
17177  This improves speed but you may not use this for functions with arguments
17178  that are called via function pointers, otherwise the first byte of the
17179  first parameter will get lost.
17180  Usage:
17181 \layout LyX-Code
17182
17183 void func_wparam(int a) wparam
17184 \layout LyX-Code
17185
17186 {
17187 \layout LyX-Code
17188
17189     /* WREG hold the lower part of a */
17190 \layout LyX-Code
17191
17192     /* the high part of a is stored in FSR2+2 (or +3 for large stack model)
17193  */
17194 \layout LyX-Code
17195
17196 ...
17197 \layout LyX-Code
17198
17199 }
17200 \layout Standard
17201
17202 This keyword replaces the deprecated wparam pragma.
17203 \layout List
17204 \labelwidthstring 00.00.0000
17205
17206 shadowregs When entering/exiting an ISR, it is possible to take advantage
17207  of the PIC18F hardware shadow registers which hold the values of WREG,
17208  STATUS and BSR registers.
17209  This can be done by adding the keyword
17210 \emph on
17211 shadowregs
17212 \emph default
17213  before the
17214 \emph on
17215 interrupt
17216 \emph default
17217  keyword in the function's header.
17218 \layout LyX-Code
17219
17220 void isr_shadow(void) shadowregs interrupt 1
17221 \layout LyX-Code
17222
17223 {
17224 \layout LyX-Code
17225
17226 ...
17227 \layout LyX-Code
17228
17229 }
17230 \layout Standard
17231
17232
17233 \emph on
17234 shadowregs
17235 \emph default
17236  instructs the code generator not to store/restore WREG, STATUS, BSR when
17237  entering/exiting the ISR.
17238 \layout Subsection
17239
17240 Function return values
17241 \layout Standard
17242
17243 Return values from functions are placed to the appropriate registers following
17244  a modified Microchip policy optimized for SDCC.
17245  The following table shows these registers:
17246 \layout Standard
17247 \align center
17248
17249 \begin_inset  Tabular
17250 <lyxtabular version="3" rows="6" columns="2">
17251 <features>
17252 <column alignment="center" valignment="top" leftline="true" width="0">
17253 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17254 <row topline="true" bottomline="true">
17255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17256 \begin_inset Text
17257
17258 \layout Standard
17259
17260 size
17261 \end_inset
17262 </cell>
17263 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17264 \begin_inset Text
17265
17266 \layout Standard
17267
17268 destination register
17269 \end_inset
17270 </cell>
17271 </row>
17272 <row topline="true">
17273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17274 \begin_inset Text
17275
17276 \layout Standard
17277
17278 8 bits
17279 \end_inset
17280 </cell>
17281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17282 \begin_inset Text
17283
17284 \layout Standard
17285
17286 WREG
17287 \end_inset
17288 </cell>
17289 </row>
17290 <row topline="true">
17291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17292 \begin_inset Text
17293
17294 \layout Standard
17295
17296 16 bits
17297 \end_inset
17298 </cell>
17299 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17300 \begin_inset Text
17301
17302 \layout Standard
17303
17304 PRODL:WREG
17305 \end_inset
17306 </cell>
17307 </row>
17308 <row topline="true">
17309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17310 \begin_inset Text
17311
17312 \layout Standard
17313
17314 24 bits
17315 \end_inset
17316 </cell>
17317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17318 \begin_inset Text
17319
17320 \layout Standard
17321
17322 PRODH:PRODL:WREG
17323 \end_inset
17324 </cell>
17325 </row>
17326 <row topline="true">
17327 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17328 \begin_inset Text
17329
17330 \layout Standard
17331
17332 32 bits
17333 \end_inset
17334 </cell>
17335 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17336 \begin_inset Text
17337
17338 \layout Standard
17339
17340 FSR0L:PRODH:PRODL:WREG
17341 \end_inset
17342 </cell>
17343 </row>
17344 <row topline="true" bottomline="true">
17345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17346 \begin_inset Text
17347
17348 \layout Standard
17349
17350 >32 bits
17351 \end_inset
17352 </cell>
17353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17354 \begin_inset Text
17355
17356 \layout Standard
17357
17358 on stack, FSR0 points to the beginning
17359 \end_inset
17360 </cell>
17361 </row>
17362 </lyxtabular>
17363
17364 \end_inset
17365
17366
17367 \layout Subsection
17368
17369 Interrupts
17370 \layout Standard
17371
17372 An interrupt servive routine (ISR) is declared using the
17373 \emph on
17374 interrupt
17375 \emph default
17376  keyword.
17377 \layout LyX-Code
17378
17379 void isr(void) interrupt
17380 \emph on
17381 n
17382 \layout LyX-Code
17383
17384 {
17385 \layout LyX-Code
17386
17387 ...
17388 \layout LyX-Code
17389
17390 }
17391 \layout Standard
17392
17393
17394 \emph on
17395 n
17396 \emph default
17397  is the interrupt number, which for PIC18F devices can be:
17398 \layout Standard
17399 \align center
17400
17401 \begin_inset  Tabular
17402 <lyxtabular version="3" rows="4" columns="3">
17403 <features>
17404 <column alignment="center" valignment="top" leftline="true" width="0">
17405 <column alignment="center" valignment="top" leftline="true" width="0">
17406 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17407 <row topline="true" bottomline="true">
17408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17409 \begin_inset Text
17410
17411 \layout Standard
17412
17413
17414 \emph on
17415 n
17416 \end_inset
17417 </cell>
17418 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17419 \begin_inset Text
17420
17421 \layout Standard
17422
17423 Interrupt Vector
17424 \end_inset
17425 </cell>
17426 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17427 \begin_inset Text
17428
17429 \layout Standard
17430
17431 Interrupt Vector Address
17432 \end_inset
17433 </cell>
17434 </row>
17435 <row topline="true">
17436 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17437 \begin_inset Text
17438
17439 \layout Standard
17440
17441 0
17442 \end_inset
17443 </cell>
17444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17445 \begin_inset Text
17446
17447 \layout Standard
17448
17449 RESET vector
17450 \end_inset
17451 </cell>
17452 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17453 \begin_inset Text
17454
17455 \layout Standard
17456
17457 0x000000
17458 \end_inset
17459 </cell>
17460 </row>
17461 <row topline="true">
17462 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17463 \begin_inset Text
17464
17465 \layout Standard
17466
17467
17468 \family roman
17469 \series medium
17470 \shape up
17471 \size normal
17472 \emph off
17473 \bar no
17474 \noun off
17475 \color none
17476 1
17477 \end_inset
17478 </cell>
17479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17480 \begin_inset Text
17481
17482 \layout Standard
17483
17484
17485 \family roman
17486 \series medium
17487 \shape up
17488 \size normal
17489 \emph off
17490 \bar no
17491 \noun off
17492 \color none
17493 HIGH priority interrupts
17494 \end_inset
17495 </cell>
17496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17497 \begin_inset Text
17498
17499 \layout Standard
17500
17501 0x000008
17502 \end_inset
17503 </cell>
17504 </row>
17505 <row topline="true" bottomline="true">
17506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17507 \begin_inset Text
17508
17509 \layout Standard
17510
17511 2
17512 \end_inset
17513 </cell>
17514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17515 \begin_inset Text
17516
17517 \layout Standard
17518
17519 LOW priority interrupts
17520 \end_inset
17521 </cell>
17522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17523 \begin_inset Text
17524
17525 \layout Standard
17526
17527 0x000018
17528 \end_inset
17529 </cell>
17530 </row>
17531 </lyxtabular>
17532
17533 \end_inset
17534
17535
17536 \layout Standard
17537
17538 When generating assembly code for ISR the code generator places a
17539 \noun on
17540 goto
17541 \noun default
17542 instruction at the
17543 \emph on
17544 Interrupt Vector Address
17545 \emph default
17546  which points at the genetated ISR.
17547  This single GOTO instruction is part of an automatically generated
17548 \emph on
17549 interrupt entry point
17550 \emph default
17551  function.
17552  The actuall ISR code is placed as normally would in the code space.
17553  Upon interrupt request, the GOTO instruction is executed which jumps to
17554  the ISR code.
17555  When declaring interrupt functions as _naked this GOTO instruction is
17556 \series bold
17557 not
17558 \series default
17559  generated.
17560  The whole interrupt functions is therefore placed at the Interrupt Vector
17561  Address of the specific interrupt.
17562  This is not a problem for the LOW priority interrupts, but it is a problem
17563  for the RESET and the HIGH priority interrupts because code may be written
17564  at the next interrupt´s vector address and cause undeterminate program
17565  behaviour if that interrupt is raised.
17566 \begin_inset Foot
17567 collapsed false
17568
17569 \layout Standard
17570
17571 This is not a problem when
17572 \layout Enumerate
17573
17574 this is a HIGH interrupt ISR and LOW interrupts are
17575 \emph on
17576 disabled
17577 \emph default
17578  or not used.
17579 \layout Enumerate
17580
17581 when the ISR is small enough not to reach the next interrupt´s vector address.
17582 \end_inset
17583
17584
17585 \layout Standard
17586
17587
17588 \emph on
17589 n
17590 \emph default
17591  is possible to be omitted.
17592  This way a function is generated similar to an ISR, but it is not assigned
17593  to any interrupt.
17594 \layout Standard
17595
17596 When entering an interrupt, currently the PIC16
17597 \begin_inset LatexCommand \index{PIC16}
17598
17599 \end_inset
17600
17601  port automatically saves the following registers:
17602 \layout Itemize
17603
17604 WREG
17605 \layout Itemize
17606
17607 STATUS
17608 \layout Itemize
17609
17610 BSR
17611 \layout Itemize
17612
17613 PROD (PRODL and PRODH)
17614 \layout Itemize
17615
17616 FSR0 (FSR0L and FSR0H)
17617 \layout Standard
17618
17619 These registers are restored upon return from the interrupt routine.
17620 \begin_inset Foot
17621 collapsed false
17622
17623 \layout Standard
17624
17625 NOTE that when the _naked attribute is specified for an interrupt routine,
17626  then NO registers are stored or restored.
17627 \end_inset
17628
17629
17630 \layout Subsection
17631
17632 Generic Pointers
17633 \layout Standard
17634
17635 Generic pointers are implemented in PIC16 port as 3-byte (24-bit) types.
17636  There are 3 types of generic pointers currently implemented data, code
17637  and eeprom pointers.
17638  They are differentiated by the value of the 7th and 6th bits of the upper
17639  byte:
17640 \layout Standard
17641 \align center
17642
17643 \begin_inset  Tabular
17644 <lyxtabular version="3" rows="5" columns="5">
17645 <features>
17646 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17647 <column alignment="center" valignment="top" width="0">
17648 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17649 <column alignment="center" valignment="top" width="0">
17650 <column alignment="left" valignment="top" rightline="true" width="0">
17651 <row topline="true" bottomline="true">
17652 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17653 \begin_inset Text
17654
17655 \layout Standard
17656
17657 pointer type
17658 \end_inset
17659 </cell>
17660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17661 \begin_inset Text
17662
17663 \layout Standard
17664
17665 7th bit
17666 \end_inset
17667 </cell>
17668 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17669 \begin_inset Text
17670
17671 \layout Standard
17672
17673 6th bit
17674 \end_inset
17675 </cell>
17676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17677 \begin_inset Text
17678
17679 \layout Standard
17680
17681 rest of the pointer
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 descrption
17690 \end_inset
17691 </cell>
17692 </row>
17693 <row topline="true" bottomline="true">
17694 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17695 \begin_inset Text
17696
17697 \layout Standard
17698
17699 data
17700 \end_inset
17701 </cell>
17702 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17703 \begin_inset Text
17704
17705 \layout Standard
17706
17707 1
17708 \end_inset
17709 </cell>
17710 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17711 \begin_inset Text
17712
17713 \layout Standard
17714
17715 0
17716 \end_inset
17717 </cell>
17718 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17719 \begin_inset Text
17720
17721 \layout Standard
17722
17723
17724 \family typewriter
17725 \shape slanted
17726 \emph on
17727 uuuuuu uuuuxxxx xxxxxxxx
17728 \end_inset
17729 </cell>
17730 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17731 \begin_inset Text
17732
17733 \layout Standard
17734
17735 a 12-bit data pointer in data RAM memory
17736 \end_inset
17737 </cell>
17738 </row>
17739 <row bottomline="true">
17740 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17741 \begin_inset Text
17742
17743 \layout Standard
17744
17745 code
17746 \end_inset
17747 </cell>
17748 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17749 \begin_inset Text
17750
17751 \layout Standard
17752
17753 0
17754 \end_inset
17755 </cell>
17756 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17757 \begin_inset Text
17758
17759 \layout Standard
17760
17761 0
17762 \end_inset
17763 </cell>
17764 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17765 \begin_inset Text
17766
17767 \layout Standard
17768
17769
17770 \family typewriter
17771 \shape slanted
17772 \emph on
17773 uxxxxx xxxxxxxx xxxxxxxx
17774 \end_inset
17775 </cell>
17776 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17777 \begin_inset Text
17778
17779 \layout Standard
17780
17781 a 21-bit code pointer in FLASH memory
17782 \end_inset
17783 </cell>
17784 </row>
17785 <row bottomline="true">
17786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17787 \begin_inset Text
17788
17789 \layout Standard
17790
17791 eeprom
17792 \end_inset
17793 </cell>
17794 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17795 \begin_inset Text
17796
17797 \layout Standard
17798
17799 0
17800 \end_inset
17801 </cell>
17802 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17803 \begin_inset Text
17804
17805 \layout Standard
17806
17807 1
17808 \end_inset
17809 </cell>
17810 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17811 \begin_inset Text
17812
17813 \layout Standard
17814
17815
17816 \family typewriter
17817 \shape slanted
17818 \emph on
17819 uuuuuu uuuuuuxx xxxxxxxx
17820 \end_inset
17821 </cell>
17822 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17823 \begin_inset Text
17824
17825 \layout Standard
17826
17827 a 10-bit eeprom pointer in EEPROM memory
17828 \end_inset
17829 </cell>
17830 </row>
17831 <row bottomline="true">
17832 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17833 \begin_inset Text
17834
17835 \layout Standard
17836
17837 (unimplemented)
17838 \end_inset
17839 </cell>
17840 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17841 \begin_inset Text
17842
17843 \layout Standard
17844
17845 1
17846 \end_inset
17847 </cell>
17848 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17849 \begin_inset Text
17850
17851 \layout Standard
17852
17853 1
17854 \end_inset
17855 </cell>
17856 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17857 \begin_inset Text
17858
17859 \layout Standard
17860
17861
17862 \family typewriter
17863 \shape slanted
17864 \emph on
17865 xxxxxx xxxxxxxx xxxxxxxx
17866 \end_inset
17867 </cell>
17868 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17869 \begin_inset Text
17870
17871 \layout Standard
17872
17873 unimplemented pointer type
17874 \end_inset
17875 </cell>
17876 </row>
17877 </lyxtabular>
17878
17879 \end_inset
17880
17881
17882 \layout Standard
17883
17884 Generic pointer are read and written with a set of library functions which
17885  read/write 1, 2, 3, 4 bytes.
17886 \layout Subsection
17887
17888 PIC16 C Libraries
17889 \layout Subsubsection
17890
17891 Standard I/O Streams
17892 \layout Standard
17893
17894 In the
17895 \emph on
17896 stdio.h
17897 \emph default
17898  the type FILE is defined as:
17899 \layout LyX-Code
17900
17901 typedef char * FILE;
17902 \layout Standard
17903
17904 This type is the stream type implemented I/O in the PIC18F devices.
17905  Also the standard input and output streams are declared in stdio.h:
17906 \layout LyX-Code
17907
17908 extern FILE * stdin;
17909 \layout LyX-Code
17910
17911 extern FILE * stdout;
17912 \layout Standard
17913
17914 The FILE type is actually a generic pointer which defines one more type
17915  of generic pointers, the
17916 \emph on
17917 stream
17918 \emph default
17919 pointer.
17920  This new type has the format:
17921 \layout Standard
17922 \align center
17923
17924 \begin_inset  Tabular
17925 <lyxtabular version="3" rows="2" columns="7">
17926 <features>
17927 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17928 <column alignment="center" valignment="top" width="0">
17929 <column alignment="center" valignment="top" leftline="true" width="0">
17930 <column alignment="center" valignment="top" leftline="true" width="0">
17931 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
17932 <column alignment="center" valignment="top" width="0">
17933 <column alignment="left" valignment="top" rightline="true" width="0">
17934 <row topline="true" bottomline="true">
17935 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17936 \begin_inset Text
17937
17938 \layout Standard
17939
17940 pointer type
17941 \end_inset
17942 </cell>
17943 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17944 \begin_inset Text
17945
17946 \layout Standard
17947
17948 <7:6>
17949 \end_inset
17950 </cell>
17951 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17952 \begin_inset Text
17953
17954 \layout Standard
17955
17956 <5>
17957 \end_inset
17958 </cell>
17959 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17960 \begin_inset Text
17961
17962 \layout Standard
17963
17964 <4>
17965 \end_inset
17966 </cell>
17967 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17968 \begin_inset Text
17969
17970 \layout Standard
17971
17972 <3:0>
17973 \end_inset
17974 </cell>
17975 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17976 \begin_inset Text
17977
17978 \layout Standard
17979
17980 rest of the pointer
17981 \end_inset
17982 </cell>
17983 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17984 \begin_inset Text
17985
17986 \layout Standard
17987
17988 descrption
17989 \end_inset
17990 </cell>
17991 </row>
17992 <row topline="true" bottomline="true">
17993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17994 \begin_inset Text
17995
17996 \layout Standard
17997
17998 stream
17999 \end_inset
18000 </cell>
18001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18002 \begin_inset Text
18003
18004 \layout Standard
18005
18006 00
18007 \end_inset
18008 </cell>
18009 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18010 \begin_inset Text
18011
18012 \layout Standard
18013
18014 1
18015 \end_inset
18016 </cell>
18017 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18018 \begin_inset Text
18019
18020 \layout Standard
18021
18022 0
18023 \end_inset
18024 </cell>
18025 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18026 \begin_inset Text
18027
18028 \layout Standard
18029
18030 nnnn
18031 \end_inset
18032 </cell>
18033 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18034 \begin_inset Text
18035
18036 \layout Standard
18037
18038
18039 \family typewriter
18040 \shape slanted
18041 \emph on
18042 uuuuuuuu uuuuuuuu
18043 \end_inset
18044 </cell>
18045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18046 \begin_inset Text
18047
18048 \layout Standard
18049
18050 upper byte high nubble is 0x2n, the rest are zeroes
18051 \end_inset
18052 </cell>
18053 </row>
18054 </lyxtabular>
18055
18056 \end_inset
18057
18058
18059 \layout Standard
18060
18061 Currently implemented there are 3 types of streams defined:
18062 \layout Standard
18063 \align center
18064
18065 \begin_inset  Tabular
18066 <lyxtabular version="3" rows="4" columns="4">
18067 <features>
18068 <column alignment="center" valignment="top" leftline="true" width="0">
18069 <column alignment="center" valignment="top" leftline="true" width="0">
18070 <column alignment="center" valignment="top" leftline="true" width="0">
18071 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18072 <row topline="true" bottomline="true">
18073 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18074 \begin_inset Text
18075
18076 \layout Standard
18077
18078 stream type
18079 \end_inset
18080 </cell>
18081 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18082 \begin_inset Text
18083
18084 \layout Standard
18085
18086 value
18087 \end_inset
18088 </cell>
18089 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18090 \begin_inset Text
18091
18092 \layout Standard
18093
18094 module
18095 \end_inset
18096 </cell>
18097 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18098 \begin_inset Text
18099
18100 \layout Standard
18101
18102 description
18103 \end_inset
18104 </cell>
18105 </row>
18106 <row topline="true">
18107 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18108 \begin_inset Text
18109
18110 \layout Standard
18111
18112 STREAM_USART
18113 \end_inset
18114 </cell>
18115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18116 \begin_inset Text
18117
18118 \layout Standard
18119
18120
18121 \family typewriter
18122 0x200000UL
18123 \end_inset
18124 </cell>
18125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18126 \begin_inset Text
18127
18128 \layout Standard
18129
18130 USART
18131 \end_inset
18132 </cell>
18133 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18134 \begin_inset Text
18135
18136 \layout Standard
18137
18138 Writes/Reads characters via the USART peripheral
18139 \end_inset
18140 </cell>
18141 </row>
18142 <row topline="true">
18143 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18144 \begin_inset Text
18145
18146 \layout Standard
18147
18148 STREAM_MSSP
18149 \end_inset
18150 </cell>
18151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18152 \begin_inset Text
18153
18154 \layout Standard
18155
18156
18157 \family typewriter
18158 0x210000UL
18159 \end_inset
18160 </cell>
18161 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18162 \begin_inset Text
18163
18164 \layout Standard
18165
18166 MSSP
18167 \end_inset
18168 </cell>
18169 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18170 \begin_inset Text
18171
18172 \layout Standard
18173
18174 Writes/Reads characters via the MSSP peripheral
18175 \end_inset
18176 </cell>
18177 </row>
18178 <row topline="true" bottomline="true">
18179 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18180 \begin_inset Text
18181
18182 \layout Standard
18183
18184 STREAM_USER
18185 \end_inset
18186 </cell>
18187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18188 \begin_inset Text
18189
18190 \layout Standard
18191
18192
18193 \family typewriter
18194 0x2f0000UL
18195 \end_inset
18196 </cell>
18197 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18198 \begin_inset Text
18199
18200 \layout Standard
18201
18202 (none)
18203 \end_inset
18204 </cell>
18205 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18206 \begin_inset Text
18207
18208 \layout Standard
18209
18210 Writes/Reads characters via used defined functions
18211 \end_inset
18212 </cell>
18213 </row>
18214 </lyxtabular>
18215
18216 \end_inset
18217
18218
18219 \layout Standard
18220
18221 The stream identifiers are declared as macros in the stdio.h header.
18222 \layout Standard
18223
18224 In the libc library there exist the functions that are used to write to
18225  each of the above streams.
18226  These are
18227 \layout List
18228 \labelwidthstring 00.00.0000
18229
18230 _
18231 \begin_inset ERT
18232 status Collapsed
18233
18234 \layout Standard
18235
18236 \backslash
18237 /
18238 \end_inset
18239
18240 _stream_usart_putchar writes a character at the USART stream
18241 \layout List
18242 \labelwidthstring 00.00.0000
18243
18244 _
18245 \begin_inset ERT
18246 status Collapsed
18247
18248 \layout Standard
18249
18250 \backslash
18251 /
18252 \end_inset
18253
18254 _stream_mssp_putchar writes a character at the MSSP stream
18255 \layout List
18256 \labelwidthstring 00.00.0000
18257
18258 putchar dummy function.
18259  This writes a character to a user specified manner.
18260 \layout Standard
18261
18262 In order to increase performance
18263 \emph on
18264 putchar
18265 \emph default
18266 is declared in stdio.h as having its parameter in WREG (it has the wparam
18267  keyword).
18268  In stdio.h exists the macro PUTCHAR(arg) that defines the putchar function
18269  in a user-friendly way.
18270
18271 \emph on
18272 arg
18273 \emph default
18274  is the name of the variable that holds the character to print.
18275  An example follows:
18276 \layout LyX-Code
18277
18278 #include <pic18fregs.h>
18279 \newline
18280 #include <stdio.h>
18281 \newline
18282
18283 \newline
18284 PUTCHAR( c )
18285 \layout LyX-Code
18286
18287 {
18288 \layout LyX-Code
18289
18290     PORTA = c;    /* dump character c to PORTA */
18291 \layout LyX-Code
18292
18293 }
18294 \newline
18295
18296 \newline
18297 void main(void)
18298 \layout LyX-Code
18299
18300 {
18301 \layout LyX-Code
18302
18303     stdout = STREAM_USER;    /* this is not necessery, since stdout points
18304 \layout LyX-Code
18305
18306                               * by default to STREAM_USER */
18307 \layout LyX-Code
18308
18309     printf (¨This is a printf test
18310 \backslash
18311 n¨);
18312 \layout LyX-Code
18313
18314 }
18315 \layout LyX-Code
18316
18317 \layout Subsubsection
18318
18319 Printing functions
18320 \layout Standard
18321
18322 PIC16 contains an implementation of the printf-family of functions.
18323  There exist the following functions:
18324 \layout LyX-Code
18325
18326 extern unsigned int sprintf(char *buf, char *fmt, ...);
18327 \layout LyX-Code
18328
18329 extern unsigned int vsprintf(char *buf, char *fmt, va_list ap);
18330 \layout LyX-Code
18331
18332 \layout LyX-Code
18333
18334 extern unsigned int printf(char *fmt, ...);
18335 \layout LyX-Code
18336
18337 extern unsigned int vprintf(char *fmt, va_lista ap);
18338 \layout LyX-Code
18339
18340 \layout LyX-Code
18341
18342 extern unsigned int fprintf(FILE *fp, char *fmt, ...);
18343 \layout LyX-Code
18344
18345 extern unsigned int vfprintf(FILE *fp, char *fmt, va_list ap);
18346 \layout Standard
18347
18348 For sprintf and vsprintf
18349 \emph on
18350 buf
18351 \emph default
18352 should normally be a data pointer where the resulting string will be placed.
18353  No range checking is done so the user should allocate the necessery buffer.
18354  For fprintf and vfprintf
18355 \emph on
18356 fp
18357 \emph default
18358  should be a stream pointer (i.e.
18359  stdout, STREAM_MSSP, etc...).
18360 \layout Subsubsection
18361
18362 Signals
18363 \layout Standard
18364
18365 The PIC18F family of microcontrollers supports a number of interrupt sources.
18366  A list of these interrupts is shown in the following table:
18367 \layout Standard
18368 \align center
18369
18370 \begin_inset  Tabular
18371 <lyxtabular version="3" rows="11" columns="4">
18372 <features>
18373 <column alignment="left" valignment="top" leftline="true" width="0">
18374 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18375 <column alignment="left" valignment="top" leftline="true" width="0">
18376 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
18377 <row topline="true" bottomline="true">
18378 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18379 \begin_inset Text
18380
18381 \layout Standard
18382
18383 signal name
18384 \end_inset
18385 </cell>
18386 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18387 \begin_inset Text
18388
18389 \layout Standard
18390
18391 description
18392 \end_inset
18393 </cell>
18394 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18395 \begin_inset Text
18396
18397 \layout Standard
18398
18399 signal name
18400 \end_inset
18401 </cell>
18402 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18403 \begin_inset Text
18404
18405 \layout Standard
18406
18407 descritpion
18408 \end_inset
18409 </cell>
18410 </row>
18411 <row topline="true">
18412 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18413 \begin_inset Text
18414
18415 \layout Standard
18416
18417 SIG_RB
18418 \end_inset
18419 </cell>
18420 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18421 \begin_inset Text
18422
18423 \layout Standard
18424
18425 PORTB change interrupt
18426 \end_inset
18427 </cell>
18428 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18429 \begin_inset Text
18430
18431 \layout Standard
18432
18433 SIG_EE
18434 \end_inset
18435 </cell>
18436 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18437 \begin_inset Text
18438
18439 \layout Standard
18440
18441 EEPROM/FLASH write complete interrupt
18442 \end_inset
18443 </cell>
18444 </row>
18445 <row topline="true">
18446 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18447 \begin_inset Text
18448
18449 \layout Standard
18450
18451 SIG_INT0
18452 \end_inset
18453 </cell>
18454 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18455 \begin_inset Text
18456
18457 \layout Standard
18458
18459 INT0 external interrupt
18460 \end_inset
18461 </cell>
18462 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18463 \begin_inset Text
18464
18465 \layout Standard
18466
18467 SIG_BCOL
18468 \end_inset
18469 </cell>
18470 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18471 \begin_inset Text
18472
18473 \layout Standard
18474
18475 Bus collision interrupt
18476 \end_inset
18477 </cell>
18478 </row>
18479 <row topline="true">
18480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18481 \begin_inset Text
18482
18483 \layout Standard
18484
18485 SIG_INT1
18486 \end_inset
18487 </cell>
18488 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18489 \begin_inset Text
18490
18491 \layout Standard
18492
18493 INT1 external interrupt
18494 \end_inset
18495 </cell>
18496 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18497 \begin_inset Text
18498
18499 \layout Standard
18500
18501 SIG_LVD
18502 \end_inset
18503 </cell>
18504 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18505 \begin_inset Text
18506
18507 \layout Standard
18508
18509 Low voltage detect interrupt
18510 \end_inset
18511 </cell>
18512 </row>
18513 <row topline="true">
18514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18515 \begin_inset Text
18516
18517 \layout Standard
18518
18519 SIG_INT2
18520 \end_inset
18521 </cell>
18522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18523 \begin_inset Text
18524
18525 \layout Standard
18526
18527 INT2 external interrupt
18528 \end_inset
18529 </cell>
18530 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18531 \begin_inset Text
18532
18533 \layout Standard
18534
18535 SIG_PSP
18536 \end_inset
18537 </cell>
18538 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18539 \begin_inset Text
18540
18541 \layout Standard
18542
18543 Parallel slave port interrupt
18544 \end_inset
18545 </cell>
18546 </row>
18547 <row topline="true">
18548 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18549 \begin_inset Text
18550
18551 \layout Standard
18552
18553 SIG_CCP1
18554 \end_inset
18555 </cell>
18556 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18557 \begin_inset Text
18558
18559 \layout Standard
18560
18561 CCP1 module interrupt
18562 \end_inset
18563 </cell>
18564 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18565 \begin_inset Text
18566
18567 \layout Standard
18568
18569 SIG_AD
18570 \end_inset
18571 </cell>
18572 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18573 \begin_inset Text
18574
18575 \layout Standard
18576
18577 AD convertion complete interrupt
18578 \end_inset
18579 </cell>
18580 </row>
18581 <row topline="true">
18582 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18583 \begin_inset Text
18584
18585 \layout Standard
18586
18587 SIG_CCP2
18588 \end_inset
18589 </cell>
18590 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18591 \begin_inset Text
18592
18593 \layout Standard
18594
18595 CCP2 module interrupt
18596 \end_inset
18597 </cell>
18598 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18599 \begin_inset Text
18600
18601 \layout Standard
18602
18603 SIG_RC
18604 \end_inset
18605 </cell>
18606 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18607 \begin_inset Text
18608
18609 \layout Standard
18610
18611 USART receive interrupt
18612 \end_inset
18613 </cell>
18614 </row>
18615 <row topline="true">
18616 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18617 \begin_inset Text
18618
18619 \layout Standard
18620
18621 SIG_TMR0
18622 \end_inset
18623 </cell>
18624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18625 \begin_inset Text
18626
18627 \layout Standard
18628
18629 TMR0 overflow interrupt
18630 \end_inset
18631 </cell>
18632 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18633 \begin_inset Text
18634
18635 \layout Standard
18636
18637 SIG_TX
18638 \end_inset
18639 </cell>
18640 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18641 \begin_inset Text
18642
18643 \layout Standard
18644
18645 USART transmit interrupt
18646 \end_inset
18647 </cell>
18648 </row>
18649 <row topline="true">
18650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18651 \begin_inset Text
18652
18653 \layout Standard
18654
18655 SIG_TMR1
18656 \end_inset
18657 </cell>
18658 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18659 \begin_inset Text
18660
18661 \layout Standard
18662
18663 TMR1 overflow interrupt
18664 \end_inset
18665 </cell>
18666 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18667 \begin_inset Text
18668
18669 \layout Standard
18670
18671 SIG_MSSP
18672 \end_inset
18673 </cell>
18674 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18675 \begin_inset Text
18676
18677 \layout Standard
18678
18679 SSP receive/transmit interrupt
18680 \end_inset
18681 </cell>
18682 </row>
18683 <row topline="true">
18684 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18685 \begin_inset Text
18686
18687 \layout Standard
18688
18689 SIG_TMR2
18690 \end_inset
18691 </cell>
18692 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18693 \begin_inset Text
18694
18695 \layout Standard
18696
18697 TMR2 matches PR2 interrupt
18698 \end_inset
18699 </cell>
18700 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18701 \begin_inset Text
18702
18703 \layout Standard
18704
18705 \end_inset
18706 </cell>
18707 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18708 \begin_inset Text
18709
18710 \layout Standard
18711
18712 \end_inset
18713 </cell>
18714 </row>
18715 <row topline="true" bottomline="true">
18716 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18717 \begin_inset Text
18718
18719 \layout Standard
18720
18721 SIG_TMR3
18722 \end_inset
18723 </cell>
18724 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18725 \begin_inset Text
18726
18727 \layout Standard
18728
18729 TMR3 overflow interrupt
18730 \end_inset
18731 </cell>
18732 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18733 \begin_inset Text
18734
18735 \layout Standard
18736
18737 \end_inset
18738 </cell>
18739 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18740 \begin_inset Text
18741
18742 \layout Standard
18743
18744 \end_inset
18745 </cell>
18746 </row>
18747 </lyxtabular>
18748
18749 \end_inset
18750
18751
18752 \layout Standard
18753
18754 The prototypes for these names are defined in the header file
18755 \emph on
18756 signal.h
18757 \emph default
18758  .
18759 \layout Standard
18760
18761 In order to simplify signal handling, a number of macros is provided:
18762 \layout List
18763 \labelwidthstring 00.00.0000
18764
18765 DEF_INTHIGH(name) begin the definition of the interrupt dispatch table for
18766  high priority interrupts.
18767
18768 \emph on
18769 name
18770 \emph default
18771  is the function name to use.
18772 \layout List
18773 \labelwidthstring 00.00.0000
18774
18775 DEF_INTLOW(name) begin the definition of the interrupt dispatch table fo
18776  low priority interrupt.
18777
18778 \emph on
18779 name
18780 \emph default
18781  is the function name to use.
18782 \layout List
18783 \labelwidthstring 00.00.0000
18784
18785 DEF_HANDLER(sig,handler) define a handler for signal
18786 \emph on
18787 sig.
18788 \layout List
18789 \labelwidthstring 00.00.0000
18790
18791 END_DEF end the declaration of the dispatch table.
18792 \layout Standard
18793
18794 Additionally there are two more macros to simplify the declaration of the
18795  signal handler:
18796 \layout List
18797 \labelwidthstring 00.00.0000
18798
18799
18800 \series medium
18801 SIGHANDLER(handler)
18802 \series default
18803 this declares the function prototype for the
18804 \emph on
18805 handler
18806 \emph default
18807  function.
18808 \layout List
18809 \labelwidthstring 00.00.0000
18810
18811 SIGHANDLERNAKED(handler) same as SIGHANDLER() but declares a naked function.
18812 \layout Standard
18813
18814 An example of using the macros above is shown below:
18815 \layout LyX-Code
18816
18817 #include <pic18fregs.h>
18818 \layout LyX-Code
18819
18820 #include <signal.h>
18821 \newline
18822
18823 \newline
18824 DEF_INTHIGH(high_int)
18825 \layout LyX-Code
18826
18827 DEF_HANDLER(SIG_TMR0, _tmr0_handler)
18828 \layout LyX-Code
18829
18830 DEF_HANDLER(SIG_BCOL, _bcol_handler)
18831 \layout LyX-Code
18832
18833 END_DEF
18834 \newline
18835
18836 \newline
18837 SIGHANDLER(_tmr0_handler)
18838 \layout LyX-Code
18839
18840 {
18841 \layout LyX-Code
18842
18843   /* action to be taken when timer 0 overflows */
18844 \layout LyX-Code
18845
18846 }
18847 \newline
18848
18849 \newline
18850 SIGHANDLERNAKED(_bcol_handler)
18851 \layout LyX-Code
18852
18853 {
18854 \layout LyX-Code
18855
18856   _asm
18857 \layout LyX-Code
18858
18859     /* action to be taken when bus collision occurs */
18860 \layout LyX-Code
18861
18862     retfie
18863 \layout LyX-Code
18864
18865  _endasm;
18866 \layout LyX-Code
18867
18868 }
18869 \layout Standard
18870
18871
18872 \series bold
18873 NOTES:
18874 \series default
18875  Special care should be taken when using the above scheme:
18876 \layout Itemize
18877
18878 do not place a colon (;) at the end of the DEF_* and END_DEF macros.
18879 \layout Itemize
18880
18881 when declaring SIGHANDLERNAKED handler never forget to use
18882 \emph on
18883 retfie
18884 \emph default
18885  for proper returning.
18886 \layout Subsection
18887
18888 PIC16 Port -- Tips
18889 \layout Standard
18890
18891 Here you can find some general tips for compiling programs with SDCC/pic16.
18892 \layout Subsubsection
18893
18894 Stack size
18895 \layout Standard
18896
18897 The default stack size (that is 64 bytes) probably is enough for many programs.
18898  One must take care that when there are many levels of function nesting,
18899  or there is excessive usage of stack, its size should be extended.
18900  An example of such a case is the printf/sprintf family of functions.
18901  If you encounter problems like not being able to print integers, then you
18902  need to set the stack size around the maximum (256 for small stack model).
18903  The following diagram shows what happens when calling printf to print an
18904  integer:
18905 \layout LyX-Code
18906
18907 printf () --> ltoa () --> ultoa () --> divschar ()
18908 \layout Standard
18909
18910 It is should be understood that stack is easily consumed when calling complicate
18911 d functions.
18912  Using command line arguments like -
18913 \begin_inset ERT
18914 status Collapsed
18915
18916 \layout Standard
18917
18918 \backslash
18919 /
18920 \end_inset
18921
18922 -fommit-frame-pointer might reduce stack usage by not creating unnecessery
18923  stack frames.
18924  Other ways to reduce stack usage may exist.
18925 \layout Chapter
18926
18927 Debugging with SDCDB
18928 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
18929
18930 \end_inset
18931
18932
18933 \begin_inset LatexCommand \index{sdcdb (debugger)}
18934
18935 \end_inset
18936
18937
18938 \layout Standard
18939
18940 SDCC is distributed with a source level debugger
18941 \begin_inset LatexCommand \index{Debugger}
18942
18943 \end_inset
18944
18945 .
18946  The debugger uses a command line interface, the command repertoire of the
18947  debugger has been kept as close to gdb
18948 \begin_inset LatexCommand \index{gdb}
18949
18950 \end_inset
18951
18952  (the GNU debugger) as possible.
18953  The configuration and build process is part of the standard compiler installati
18954 on, which also builds and installs the debugger in the target directory
18955  specified during configuration.
18956  The debugger allows you debug BOTH at the C source and at the ASM source
18957  level.
18958  Sdcdb is available on Unix platforms only.
18959 \layout Section
18960
18961 Compiling for Debugging
18962 \layout Standard
18963
18964 The -
18965 \begin_inset ERT
18966 status Collapsed
18967
18968 \layout Standard
18969
18970 \backslash
18971 /
18972 \end_inset
18973
18974 -debug
18975 \begin_inset LatexCommand \index{-\/-debug}
18976
18977 \end_inset
18978
18979  option must be specified for all files for which debug information is to
18980  be generated.
18981  The complier generates a .adb file for each of these files.
18982  The linker creates the .cdb
18983 \begin_inset LatexCommand \index{<file>.cdb}
18984
18985 \end_inset
18986
18987  file from the .adb
18988 \begin_inset LatexCommand \index{<file>.adb}
18989
18990 \end_inset
18991
18992  files and the address information.
18993  This .cdb is used by the debugger.
18994 \layout Section
18995
18996 How the Debugger Works
18997 \layout Standard
18998
18999 When the -
19000 \begin_inset ERT
19001 status Collapsed
19002
19003 \layout Standard
19004
19005 \backslash
19006 /
19007 \end_inset
19008
19009 -debug option is specified the compiler generates extra symbol information
19010  some of which are put into the assembler source and some are put into the
19011  .adb file.
19012   Then the linker creates the .cdb file from the individual .adb files with
19013  the address information for the symbols.
19014  The debugger reads the symbolic information generated by the compiler &
19015  the address information generated by the linker.
19016  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
19017  execution is controlled by the debugger.
19018  When a command is issued for the debugger, it translates it into appropriate
19019  commands for the simulator.
19020 \layout Section
19021
19022 Starting the Debugger
19023 \layout Standard
19024
19025 The debugger can be started using the following command line.
19026  (Assume the file you are debugging has the file name foo).
19027 \newline
19028
19029 \newline
19030
19031 \family sans
19032 \series bold
19033 sdcdb foo
19034 \newline
19035
19036 \family default
19037 \series default
19038
19039 \newline
19040 The debugger will look for the following files.
19041 \layout Itemize
19042
19043 foo.c - the source file.
19044 \layout Itemize
19045
19046 foo.cdb - the debugger symbol information file.
19047 \layout Itemize
19048
19049 foo.ihx - the Intel hex format
19050 \begin_inset LatexCommand \index{Intel hex format}
19051
19052 \end_inset
19053
19054  object file.
19055 \layout Section
19056
19057 Command Line Options.
19058 \layout Itemize
19059
19060 -
19061 \begin_inset ERT
19062 status Collapsed
19063
19064 \layout Standard
19065
19066 \backslash
19067 /
19068 \end_inset
19069
19070 -directory=<source file directory> this option can used to specify the directory
19071  search list.
19072  The debugger will look into the directory list specified for source, cdb
19073  & ihx files.
19074  The items in the directory list must be separated by ':', e.g.
19075  if the source files can be in the directories /home/src1 and /home/src2,
19076  the -
19077 \begin_inset ERT
19078 status Collapsed
19079
19080 \layout Standard
19081
19082 \backslash
19083 /
19084 \end_inset
19085
19086 -directory option should be -
19087 \begin_inset ERT
19088 status Collapsed
19089
19090 \layout Standard
19091
19092 \backslash
19093 /
19094 \end_inset
19095
19096 -directory=/home/src1:/home/src2.
19097  Note there can be no spaces in the option.
19098
19099 \layout Itemize
19100
19101 -cd <directory> - change to the <directory>.
19102 \layout Itemize
19103
19104 -fullname - used by GUI front ends.
19105 \layout Itemize
19106
19107 -cpu <cpu-type> - this argument is passed to the simulator please see the
19108  simulator docs for details.
19109 \layout Itemize
19110
19111 -X <Clock frequency > this options is passed to the simulator please see
19112  the simulator docs for details.
19113 \layout Itemize
19114
19115 -s <serial port file> passed to simulator see the simulator docs for details.
19116 \layout Itemize
19117
19118 -S <serial in,out> passed to simulator see the simulator docs for details.
19119 \layout Itemize
19120
19121 -k <port number> passed to simulator see the simulator docs for details.
19122 \layout Section
19123
19124 Debugger Commands.
19125 \layout Standard
19126
19127 As mentioned earlier the command interface for the debugger has been deliberatel
19128 y kept as close the GNU debugger gdb, as possible.
19129  This will help the integration with existing graphical user interfaces
19130  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
19131  If you use a graphical user interface for the debugger you can skip the
19132  next sections.
19133 \layout Subsubsection*
19134
19135 break [line | file:line | function | file:function]
19136 \layout Standard
19137
19138 Set breakpoint at specified line or function:
19139 \newline
19140
19141 \newline
19142
19143 \family sans
19144 \series bold
19145 sdcdb>break 100
19146 \newline
19147 sdcdb>break foo.c:100
19148 \newline
19149 sdcdb>break funcfoo
19150 \newline
19151 sdcdb>break foo.c:funcfoo
19152 \layout Subsubsection*
19153
19154 clear [line | file:line | function | file:function ]
19155 \layout Standard
19156
19157 Clear breakpoint at specified line or function:
19158 \newline
19159
19160 \newline
19161
19162 \family sans
19163 \series bold
19164 sdcdb>clear 100
19165 \newline
19166 sdcdb>clear foo.c:100
19167 \newline
19168 sdcdb>clear funcfoo
19169 \newline
19170 sdcdb>clear foo.c:funcfoo
19171 \layout Subsubsection*
19172
19173 continue
19174 \layout Standard
19175
19176 Continue program being debugged, after breakpoint.
19177 \layout Subsubsection*
19178
19179 finish
19180 \layout Standard
19181
19182 Execute till the end of the current function.
19183 \layout Subsubsection*
19184
19185 delete [n]
19186 \layout Standard
19187
19188 Delete breakpoint number 'n'.
19189  If used without any option clear ALL user defined break points.
19190 \layout Subsubsection*
19191
19192 info [break | stack | frame | registers ]
19193 \layout Itemize
19194
19195 info break - list all breakpoints
19196 \layout Itemize
19197
19198 info stack - show the function call stack.
19199 \layout Itemize
19200
19201 info frame - show information about the current execution frame.
19202 \layout Itemize
19203
19204 info registers - show content of all registers.
19205 \layout Subsubsection*
19206
19207 step
19208 \layout Standard
19209
19210 Step program until it reaches a different source line.
19211  Note: pressing <return> repeats the last command.
19212 \layout Subsubsection*
19213
19214 next
19215 \layout Standard
19216
19217 Step program, proceeding through subroutine calls.
19218 \layout Subsubsection*
19219
19220 run
19221 \layout Standard
19222
19223 Start debugged program.
19224 \layout Subsubsection*
19225
19226 ptype variable
19227 \layout Standard
19228
19229 Print type information of the variable.
19230 \layout Subsubsection*
19231
19232 print variable
19233 \layout Standard
19234
19235 print value of variable.
19236 \layout Subsubsection*
19237
19238 file filename
19239 \layout Standard
19240
19241 load the given file name.
19242  Note this is an alternate method of loading file for debugging.
19243 \layout Subsubsection*
19244
19245 frame
19246 \layout Standard
19247
19248 print information about current frame.
19249 \layout Subsubsection*
19250
19251 set srcmode
19252 \layout Standard
19253
19254 Toggle between C source & assembly source.
19255 \layout Subsubsection*
19256
19257 ! simulator command
19258 \layout Standard
19259
19260 Send the string following '!' to the simulator, the simulator response is
19261  displayed.
19262  Note the debugger does not interpret the command being sent to the simulator,
19263  so if a command like 'go' is sent the debugger can loose its execution
19264  context and may display incorrect values.
19265 \layout Subsubsection*
19266
19267 quit
19268 \layout Standard
19269
19270 "Watch me now.
19271  Iam going Down.
19272  My name is Bobby Brown"
19273 \layout Section
19274
19275 Interfacing with XEmacs
19276 \begin_inset LatexCommand \index{XEmacs}
19277
19278 \end_inset
19279
19280
19281 \begin_inset LatexCommand \index{Emacs}
19282
19283 \end_inset
19284
19285 .
19286 \layout Standard
19287
19288 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
19289  sdcdb.el and sdcdbsrc.el.
19290  These two files can be found in the $(prefix)/bin directory after the installat
19291 ion is complete.
19292  These files need to be loaded into XEmacs for the interface to work.
19293  This can be done at XEmacs startup time by inserting the following into
19294  your '.xemacs' file (which can be found in your HOME directory):
19295 \newline
19296
19297 \newline
19298
19299 \family typewriter
19300 (load-file sdcdbsrc.el)
19301 \family default
19302
19303 \newline
19304
19305 \newline
19306 .xemacs is a lisp file so the () around the command is REQUIRED.
19307  The files can also be loaded dynamically while XEmacs is running, set the
19308  environment variable 'EMACSLOADPATH' to the installation bin directory
19309  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
19310  To start the interface enter the following command:
19311 \newline
19312
19313 \newline
19314
19315 \family sans
19316 \series bold
19317 ESC-x sdcdbsrc
19318 \family default
19319 \series default
19320
19321 \newline
19322
19323 \newline
19324 You will prompted to enter the file name to be debugged.
19325
19326 \newline
19327
19328 \newline
19329 The command line options that are passed to the simulator directly are bound
19330  to default values in the file sdcdbsrc.el.
19331  The variables are listed below, these values maybe changed as required.
19332 \layout Itemize
19333
19334 sdcdbsrc-cpu-type '51
19335 \layout Itemize
19336
19337 sdcdbsrc-frequency '11059200
19338 \layout Itemize
19339
19340 sdcdbsrc-serial nil
19341 \layout Standard
19342
19343 The following is a list of key mapping for the debugger interface.
19344 \layout Standard
19345
19346 \SpecialChar ~
19347
19348 \family typewriter
19349
19350 \newline
19351 ;;\SpecialChar ~
19352 Current Listing ::
19353 \newline
19354 ;;key\SpecialChar ~
19355 \SpecialChar ~
19356 \SpecialChar ~
19357 \SpecialChar ~
19358 \SpecialChar ~
19359 \SpecialChar ~
19360 \SpecialChar ~
19361 \SpecialChar ~
19362 \SpecialChar ~
19363 \SpecialChar ~
19364 \SpecialChar ~
19365 \SpecialChar ~
19366 \SpecialChar ~
19367 \SpecialChar ~
19368 binding\SpecialChar ~
19369 \SpecialChar ~
19370 \SpecialChar ~
19371 \SpecialChar ~
19372 \SpecialChar ~
19373 \SpecialChar ~
19374 \SpecialChar ~
19375 \SpecialChar ~
19376 \SpecialChar ~
19377 \SpecialChar ~
19378 \SpecialChar ~
19379 \SpecialChar ~
19380 \SpecialChar ~
19381 \SpecialChar ~
19382 \SpecialChar ~
19383 \SpecialChar ~
19384 \SpecialChar ~
19385 \SpecialChar ~
19386 \SpecialChar ~
19387 \SpecialChar ~
19388 \SpecialChar ~
19389 \SpecialChar ~
19390 Comment
19391 \newline
19392 ;;---\SpecialChar ~
19393 \SpecialChar ~
19394 \SpecialChar ~
19395 \SpecialChar ~
19396 \SpecialChar ~
19397 \SpecialChar ~
19398 \SpecialChar ~
19399 \SpecialChar ~
19400 \SpecialChar ~
19401 \SpecialChar ~
19402 \SpecialChar ~
19403 \SpecialChar ~
19404 \SpecialChar ~
19405 \SpecialChar ~
19406 -------\SpecialChar ~
19407 \SpecialChar ~
19408 \SpecialChar ~
19409 \SpecialChar ~
19410 \SpecialChar ~
19411 \SpecialChar ~
19412 \SpecialChar ~
19413 \SpecialChar ~
19414 \SpecialChar ~
19415 \SpecialChar ~
19416 \SpecialChar ~
19417 \SpecialChar ~
19418 \SpecialChar ~
19419 \SpecialChar ~
19420 \SpecialChar ~
19421 \SpecialChar ~
19422 \SpecialChar ~
19423 \SpecialChar ~
19424 \SpecialChar ~
19425 \SpecialChar ~
19426 \SpecialChar ~
19427 \SpecialChar ~
19428 -------
19429 \newline
19430 ;;
19431 \newline
19432 ;;\SpecialChar ~
19433 n\SpecialChar ~
19434 \SpecialChar ~
19435 \SpecialChar ~
19436 \SpecialChar ~
19437 \SpecialChar ~
19438 \SpecialChar ~
19439 \SpecialChar ~
19440 \SpecialChar ~
19441 \SpecialChar ~
19442 \SpecialChar ~
19443 \SpecialChar ~
19444 \SpecialChar ~
19445 \SpecialChar ~
19446 \SpecialChar ~
19447 \SpecialChar ~
19448 sdcdb-next-from-src\SpecialChar ~
19449 \SpecialChar ~
19450 \SpecialChar ~
19451 \SpecialChar ~
19452 \SpecialChar ~
19453 \SpecialChar ~
19454 \SpecialChar ~
19455 \SpecialChar ~
19456 \SpecialChar ~
19457 \SpecialChar ~
19458 SDCDB next command
19459 \newline
19460 ;;\SpecialChar ~
19461 b\SpecialChar ~
19462 \SpecialChar ~
19463 \SpecialChar ~
19464 \SpecialChar ~
19465 \SpecialChar ~
19466 \SpecialChar ~
19467 \SpecialChar ~
19468 \SpecialChar ~
19469 \SpecialChar ~
19470 \SpecialChar ~
19471 \SpecialChar ~
19472 \SpecialChar ~
19473 \SpecialChar ~
19474 \SpecialChar ~
19475 \SpecialChar ~
19476 sdcdb-back-from-src\SpecialChar ~
19477 \SpecialChar ~
19478 \SpecialChar ~
19479 \SpecialChar ~
19480 \SpecialChar ~
19481 \SpecialChar ~
19482 \SpecialChar ~
19483 \SpecialChar ~
19484 \SpecialChar ~
19485 \SpecialChar ~
19486 SDCDB back command
19487 \newline
19488 ;;\SpecialChar ~
19489 c\SpecialChar ~
19490 \SpecialChar ~
19491 \SpecialChar ~
19492 \SpecialChar ~
19493 \SpecialChar ~
19494 \SpecialChar ~
19495 \SpecialChar ~
19496 \SpecialChar ~
19497 \SpecialChar ~
19498 \SpecialChar ~
19499 \SpecialChar ~
19500 \SpecialChar ~
19501 \SpecialChar ~
19502 \SpecialChar ~
19503 \SpecialChar ~
19504 sdcdb-cont-from-src\SpecialChar ~
19505 \SpecialChar ~
19506 \SpecialChar ~
19507 \SpecialChar ~
19508 \SpecialChar ~
19509 \SpecialChar ~
19510 \SpecialChar ~
19511 \SpecialChar ~
19512 \SpecialChar ~
19513 \SpecialChar ~
19514 SDCDB continue command
19515 \newline
19516 ;;\SpecialChar ~
19517 s\SpecialChar ~
19518 \SpecialChar ~
19519 \SpecialChar ~
19520 \SpecialChar ~
19521 \SpecialChar ~
19522 \SpecialChar ~
19523 \SpecialChar ~
19524 \SpecialChar ~
19525 \SpecialChar ~
19526 \SpecialChar ~
19527 \SpecialChar ~
19528 \SpecialChar ~
19529 \SpecialChar ~
19530 \SpecialChar ~
19531 \SpecialChar ~
19532 sdcdb-step-from-src\SpecialChar ~
19533 \SpecialChar ~
19534 \SpecialChar ~
19535 \SpecialChar ~
19536 \SpecialChar ~
19537 \SpecialChar ~
19538 \SpecialChar ~
19539 \SpecialChar ~
19540 \SpecialChar ~
19541 \SpecialChar ~
19542 SDCDB step command
19543 \newline
19544 ;;\SpecialChar ~
19545 ?\SpecialChar ~
19546 \SpecialChar ~
19547 \SpecialChar ~
19548 \SpecialChar ~
19549 \SpecialChar ~
19550 \SpecialChar ~
19551 \SpecialChar ~
19552 \SpecialChar ~
19553 \SpecialChar ~
19554 \SpecialChar ~
19555 \SpecialChar ~
19556 \SpecialChar ~
19557 \SpecialChar ~
19558 \SpecialChar ~
19559 \SpecialChar ~
19560 sdcdb-whatis-c-sexp\SpecialChar ~
19561 \SpecialChar ~
19562 \SpecialChar ~
19563 \SpecialChar ~
19564 \SpecialChar ~
19565 \SpecialChar ~
19566 \SpecialChar ~
19567 \SpecialChar ~
19568 \SpecialChar ~
19569 \SpecialChar ~
19570 SDCDB ptypecommand for data at
19571 \newline
19572 ;;\SpecialChar ~
19573 \SpecialChar ~
19574 \SpecialChar ~
19575 \SpecialChar ~
19576 \SpecialChar ~
19577 \SpecialChar ~
19578 \SpecialChar ~
19579 \SpecialChar ~
19580 \SpecialChar ~
19581 \SpecialChar ~
19582 \SpecialChar ~
19583 \SpecialChar ~
19584 \SpecialChar ~
19585 \SpecialChar ~
19586 \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 \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 buffer point
19620 \newline
19621 ;;\SpecialChar ~
19622 x\SpecialChar ~
19623 \SpecialChar ~
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 sdcdbsrc-delete\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 SDCDB Delete all breakpoints if no arg
19652 \newline
19653 ;;\SpecialChar ~
19654 \SpecialChar ~
19655 \SpecialChar ~
19656 \SpecialChar ~
19657 \SpecialChar ~
19658 \SpecialChar ~
19659 \SpecialChar ~
19660 \SpecialChar ~
19661 \SpecialChar ~
19662 \SpecialChar ~
19663 \SpecialChar ~
19664 \SpecialChar ~
19665 \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 \SpecialChar ~
19681 \SpecialChar ~
19682 \SpecialChar ~
19683 \SpecialChar ~
19684 \SpecialChar ~
19685 \SpecialChar ~
19686 \SpecialChar ~
19687 \SpecialChar ~
19688 \SpecialChar ~
19689 \SpecialChar ~
19690 \SpecialChar ~
19691 \SpecialChar ~
19692 \SpecialChar ~
19693 \SpecialChar ~
19694 \SpecialChar ~
19695 \SpecialChar ~
19696 \SpecialChar ~
19697 \SpecialChar ~
19698 \SpecialChar ~
19699 \SpecialChar ~
19700 given or delete arg (C-u arg x)
19701 \newline
19702 ;;\SpecialChar ~
19703 m\SpecialChar ~
19704 \SpecialChar ~
19705 \SpecialChar ~
19706 \SpecialChar ~
19707 \SpecialChar ~
19708 \SpecialChar ~
19709 \SpecialChar ~
19710 \SpecialChar ~
19711 \SpecialChar ~
19712 \SpecialChar ~
19713 \SpecialChar ~
19714 \SpecialChar ~
19715 \SpecialChar ~
19716 \SpecialChar ~
19717 \SpecialChar ~
19718 sdcdbsrc-frame\SpecialChar ~
19719 \SpecialChar ~
19720 \SpecialChar ~
19721 \SpecialChar ~
19722 \SpecialChar ~
19723 \SpecialChar ~
19724 \SpecialChar ~
19725 \SpecialChar ~
19726 \SpecialChar ~
19727 \SpecialChar ~
19728 \SpecialChar ~
19729 \SpecialChar ~
19730 \SpecialChar ~
19731 \SpecialChar ~
19732 \SpecialChar ~
19733 SDCDB Display current frame if no arg,
19734 \newline
19735 ;;\SpecialChar ~
19736 \SpecialChar ~
19737 \SpecialChar ~
19738 \SpecialChar ~
19739 \SpecialChar ~
19740 \SpecialChar ~
19741 \SpecialChar ~
19742 \SpecialChar ~
19743 \SpecialChar ~
19744 \SpecialChar ~
19745 \SpecialChar ~
19746 \SpecialChar ~
19747 \SpecialChar ~
19748 \SpecialChar ~
19749 \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 \SpecialChar ~
19765 \SpecialChar ~
19766 \SpecialChar ~
19767 \SpecialChar ~
19768 \SpecialChar ~
19769 \SpecialChar ~
19770 \SpecialChar ~
19771 \SpecialChar ~
19772 \SpecialChar ~
19773 \SpecialChar ~
19774 \SpecialChar ~
19775 \SpecialChar ~
19776 \SpecialChar ~
19777 \SpecialChar ~
19778 \SpecialChar ~
19779 \SpecialChar ~
19780 \SpecialChar ~
19781 \SpecialChar ~
19782 given or display frame arg
19783 \newline
19784 ;;\SpecialChar ~
19785 \SpecialChar ~
19786 \SpecialChar ~
19787 \SpecialChar ~
19788 \SpecialChar ~
19789 \SpecialChar ~
19790 \SpecialChar ~
19791 \SpecialChar ~
19792 \SpecialChar ~
19793 \SpecialChar ~
19794 \SpecialChar ~
19795 \SpecialChar ~
19796 \SpecialChar ~
19797 \SpecialChar ~
19798 \SpecialChar ~
19799 \SpecialChar ~
19800 \SpecialChar ~
19801 \SpecialChar ~
19802 \SpecialChar ~
19803 \SpecialChar ~
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 buffer point
19832 \newline
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 sdcdbsrc-goto-sdcdb\SpecialChar ~
19850 \SpecialChar ~
19851 \SpecialChar ~
19852 \SpecialChar ~
19853 \SpecialChar ~
19854 \SpecialChar ~
19855 \SpecialChar ~
19856 \SpecialChar ~
19857 \SpecialChar ~
19858 \SpecialChar ~
19859 Goto the SDCDB output buffer
19860 \newline
19861 ;;\SpecialChar ~
19862 p\SpecialChar ~
19863 \SpecialChar ~
19864 \SpecialChar ~
19865 \SpecialChar ~
19866 \SpecialChar ~
19867 \SpecialChar ~
19868 \SpecialChar ~
19869 \SpecialChar ~
19870 \SpecialChar ~
19871 \SpecialChar ~
19872 \SpecialChar ~
19873 \SpecialChar ~
19874 \SpecialChar ~
19875 \SpecialChar ~
19876 \SpecialChar ~
19877 sdcdb-print-c-sexp\SpecialChar ~
19878 \SpecialChar ~
19879 \SpecialChar ~
19880 \SpecialChar ~
19881 \SpecialChar ~
19882 \SpecialChar ~
19883 \SpecialChar ~
19884 \SpecialChar ~
19885 \SpecialChar ~
19886 \SpecialChar ~
19887 \SpecialChar ~
19888 SDCDB print command for data at
19889 \newline
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 \SpecialChar ~
19933 \SpecialChar ~
19934 \SpecialChar ~
19935 \SpecialChar ~
19936 \SpecialChar ~
19937 buffer point
19938 \newline
19939 ;;\SpecialChar ~
19940 g\SpecialChar ~
19941 \SpecialChar ~
19942 \SpecialChar ~
19943 \SpecialChar ~
19944 \SpecialChar ~
19945 \SpecialChar ~
19946 \SpecialChar ~
19947 \SpecialChar ~
19948 \SpecialChar ~
19949 \SpecialChar ~
19950 \SpecialChar ~
19951 \SpecialChar ~
19952 \SpecialChar ~
19953 \SpecialChar ~
19954 \SpecialChar ~
19955 sdcdbsrc-goto-sdcdb\SpecialChar ~
19956 \SpecialChar ~
19957 \SpecialChar ~
19958 \SpecialChar ~
19959 \SpecialChar ~
19960 \SpecialChar ~
19961 \SpecialChar ~
19962 \SpecialChar ~
19963 \SpecialChar ~
19964 \SpecialChar ~
19965 Goto the SDCDB output buffer
19966 \newline
19967 ;;\SpecialChar ~
19968 t\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 sdcdbsrc-mode\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 Toggles Sdcdbsrc mode (turns it off)
20000 \newline
20001 ;;
20002 \newline
20003 ;;\SpecialChar ~
20004 C-c\SpecialChar ~
20005 C-f\SpecialChar ~
20006 \SpecialChar ~
20007 \SpecialChar ~
20008 \SpecialChar ~
20009 \SpecialChar ~
20010 \SpecialChar ~
20011 \SpecialChar ~
20012 \SpecialChar ~
20013 \SpecialChar ~
20014 sdcdb-finish-from-src\SpecialChar ~
20015 \SpecialChar ~
20016 \SpecialChar ~
20017 \SpecialChar ~
20018 \SpecialChar ~
20019 \SpecialChar ~
20020 \SpecialChar ~
20021 \SpecialChar ~
20022 SDCDB finish command
20023 \newline
20024 ;;
20025 \newline
20026 ;;\SpecialChar ~
20027 C-x\SpecialChar ~
20028 SPC\SpecialChar ~
20029 \SpecialChar ~
20030 \SpecialChar ~
20031 \SpecialChar ~
20032 \SpecialChar ~
20033 \SpecialChar ~
20034 \SpecialChar ~
20035 \SpecialChar ~
20036 \SpecialChar ~
20037 sdcdb-break\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 Set break for line with point
20056 \newline
20057 ;;\SpecialChar ~
20058 ESC\SpecialChar ~
20059 t\SpecialChar ~
20060 \SpecialChar ~
20061 \SpecialChar ~
20062 \SpecialChar ~
20063 \SpecialChar ~
20064 \SpecialChar ~
20065 \SpecialChar ~
20066 \SpecialChar ~
20067 \SpecialChar ~
20068 \SpecialChar ~
20069 \SpecialChar ~
20070 sdcdbsrc-mode\SpecialChar ~
20071 \SpecialChar ~
20072 \SpecialChar ~
20073 \SpecialChar ~
20074 \SpecialChar ~
20075 \SpecialChar ~
20076 \SpecialChar ~
20077 \SpecialChar ~
20078 \SpecialChar ~
20079 \SpecialChar ~
20080 \SpecialChar ~
20081 \SpecialChar ~
20082 \SpecialChar ~
20083 \SpecialChar ~
20084 \SpecialChar ~
20085 \SpecialChar ~
20086 Toggle Sdcdbsrc mode
20087 \newline
20088 ;;\SpecialChar ~
20089 ESC\SpecialChar ~
20090 m\SpecialChar ~
20091 \SpecialChar ~
20092 \SpecialChar ~
20093 \SpecialChar ~
20094 \SpecialChar ~
20095 \SpecialChar ~
20096 \SpecialChar ~
20097 \SpecialChar ~
20098 \SpecialChar ~
20099 \SpecialChar ~
20100 \SpecialChar ~
20101 sdcdbsrc-srcmode\SpecialChar ~
20102 \SpecialChar ~
20103 \SpecialChar ~
20104 \SpecialChar ~
20105 \SpecialChar ~
20106 \SpecialChar ~
20107 \SpecialChar ~
20108 \SpecialChar ~
20109 \SpecialChar ~
20110 \SpecialChar ~
20111 \SpecialChar ~
20112 \SpecialChar ~
20113 \SpecialChar ~
20114 Toggle list mode
20115 \newline
20116 ;;
20117 \newline
20118
20119 \layout Chapter
20120 \pagebreak_top
20121 TIPS
20122 \layout Standard
20123
20124 Here are a few guidelines that will help the compiler generate more efficient
20125  code, some of the tips are specific to this compiler others are generally
20126  good programming practice.
20127 \layout Itemize
20128
20129 Use the smallest data type to represent your data-value.
20130  If it is known in advance that the value is going to be less than 256 then
20131  use an 'unsigned char' instead of a 'short' or 'int'.
20132  Please note, that ANSI C requires both signed and unsigned chars to be
20133  promoted to 'signed int' before doing any operation.
20134  This promotion can be omitted, if the result is the same.
20135  The effect of the promotion rules together with the sign-extension is often
20136  surprising:
20137 \begin_deeper
20138 \layout Verse
20139
20140
20141 \family typewriter
20142 unsigned char uc = 0xfe;
20143 \newline
20144 if (uc * uc < 0) /* this is true! */
20145 \newline
20146 {
20147 \newline
20148 \SpecialChar ~
20149 \SpecialChar ~
20150 \SpecialChar ~
20151 \SpecialChar ~
20152 ....
20153 \newline
20154 }
20155 \layout Standard
20156
20157
20158 \family typewriter
20159 uc * uc
20160 \family default
20161  is evaluated as
20162 \family typewriter
20163 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
20164 \family default
20165 .
20166
20167 \newline
20168 Another one:
20169 \layout Verse
20170
20171
20172 \family typewriter
20173 (unsigned char) -12 / (signed char) -3 = ...
20174 \layout Standard
20175
20176 No, the result is not 4:
20177 \layout Verse
20178
20179
20180 \family typewriter
20181 (int) (unsigned char) -12 / (int) (signed char) -3 =
20182 \newline
20183 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
20184 \newline
20185 (int) 0x00f4 / (int) 0xfffd =
20186 \newline
20187 (int) 0x00f4 / (int) 0xfffd =
20188 \newline
20189 (int) 244 / (int) -3 =
20190 \newline
20191 (int) -81 = (int) 0xffaf;
20192 \layout Standard
20193
20194 Don't complain, that gcc gives you a different result.
20195  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
20196  Therefore the results are different.
20197 \newline
20198 From
20199 \begin_inset Quotes sld
20200 \end_inset
20201
20202 comp.lang.c FAQ
20203 \begin_inset Quotes srd
20204 \end_inset
20205
20206 :
20207 \layout Quote
20208
20209 If well-defined overflow characteristics are important and negative values
20210  are not, or if you want to steer clear of sign-extension problems when
20211  manipulating bits or bytes, use one of the corresponding unsigned types.
20212  (Beware when mixing signed and unsigned values in expressions, though.)
20213 \newline
20214 Although character types (especially unsigned char) can be used as "tiny"
20215  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
20216 ble sign extension and increased code size.
20217 \end_deeper
20218 \layout Itemize
20219
20220 Use unsigned when it is known in advance that the value is not going to
20221  be negative.
20222  This helps especially if you are doing division or multiplication, bit-shifting
20223  or are using an array index.
20224 \layout Itemize
20225
20226 NEVER jump into a LOOP.
20227 \layout Itemize
20228
20229 Declare the variables to be local
20230 \begin_inset LatexCommand \index{local variables}
20231
20232 \end_inset
20233
20234  whenever possible, especially loop control variables (induction).
20235 \layout Itemize
20236
20237 Since the compiler does not always do implicit integral promotion, the programme
20238 r should do an explicit cast when integral promotion is required.
20239 \layout Itemize
20240
20241 Reducing the size of division, multiplication & modulus operations can reduce
20242  code size substantially.
20243  Take the following code for example.
20244 \begin_deeper
20245 \layout Verse
20246
20247
20248 \family typewriter
20249 foobar(unsigned int p1, unsigned char ch)
20250 \newline
20251 {
20252 \newline
20253 \SpecialChar ~
20254 \SpecialChar ~
20255 \SpecialChar ~
20256 \SpecialChar ~
20257 unsigned char ch1 = p1 % ch ;
20258 \newline
20259 \SpecialChar ~
20260 \SpecialChar ~
20261 \SpecialChar ~
20262 \SpecialChar ~
20263 ....
20264 \newline
20265 }
20266 \layout Standard
20267
20268 For the modulus operation the variable ch will be promoted to unsigned int
20269  first then the modulus operation will be performed (this will lead to a
20270  call to support routine _moduint()), and the result will be casted to a
20271  char.
20272  If the code is changed to
20273 \layout Verse
20274
20275
20276 \family typewriter
20277 foobar(unsigned int p1, unsigned char ch)
20278 \newline
20279 {
20280 \newline
20281 \SpecialChar ~
20282 \SpecialChar ~
20283 \SpecialChar ~
20284 \SpecialChar ~
20285 unsigned char ch1 = (unsigned char)p1 % ch ;
20286 \newline
20287 \SpecialChar ~
20288 \SpecialChar ~
20289 \SpecialChar ~
20290 \SpecialChar ~
20291 ....
20292 \newline
20293 }
20294 \layout Standard
20295
20296 It would substantially reduce the code generated (future versions of the
20297  compiler will be smart enough to detect such optimization opportunities).
20298 \end_deeper
20299 \layout Itemize
20300
20301 Have a look at the assembly listing to get a
20302 \begin_inset Quotes sld
20303 \end_inset
20304
20305 feeling
20306 \begin_inset Quotes srd
20307 \end_inset
20308
20309  for the code generation.
20310 \layout Section
20311
20312 Tools
20313 \begin_inset LatexCommand \index{Tools}
20314
20315 \end_inset
20316
20317  included in the distribution
20318 \layout Standard
20319 \align center
20320
20321 \begin_inset  Tabular
20322 <lyxtabular version="3" rows="12" columns="3">
20323 <features>
20324 <column alignment="center" valignment="top" leftline="true" width="0pt">
20325 <column alignment="center" valignment="top" leftline="true" width="0pt">
20326 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
20327 <row topline="true" bottomline="true">
20328 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20329 \begin_inset Text
20330
20331 \layout Standard
20332
20333 Name
20334 \end_inset
20335 </cell>
20336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20337 \begin_inset Text
20338
20339 \layout Standard
20340
20341 Purpose
20342 \end_inset
20343 </cell>
20344 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20345 \begin_inset Text
20346
20347 \layout Standard
20348
20349 Directory
20350 \end_inset
20351 </cell>
20352 </row>
20353 <row topline="true">
20354 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20355 \begin_inset Text
20356
20357 \layout Standard
20358
20359 uCsim
20360 \end_inset
20361 </cell>
20362 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20363 \begin_inset Text
20364
20365 \layout Standard
20366
20367 Simulator for various architectures
20368 \end_inset
20369 </cell>
20370 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20371 \begin_inset Text
20372
20373 \layout Standard
20374
20375 sdcc/sim/ucsim
20376 \end_inset
20377 </cell>
20378 </row>
20379 <row topline="true">
20380 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20381 \begin_inset Text
20382
20383 \layout Standard
20384
20385 keil2sdcc.pl
20386 \end_inset
20387 </cell>
20388 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20389 \begin_inset Text
20390
20391 \layout Standard
20392
20393 header file conversion
20394 \end_inset
20395 </cell>
20396 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20397 \begin_inset Text
20398
20399 \layout Standard
20400
20401 sdcc/support/scripts
20402 \end_inset
20403 </cell>
20404 </row>
20405 <row topline="true">
20406 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20407 \begin_inset Text
20408
20409 \layout Standard
20410
20411 mh2h.c
20412 \end_inset
20413 </cell>
20414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20415 \begin_inset Text
20416
20417 \layout Standard
20418
20419 header file conversion
20420 \end_inset
20421 </cell>
20422 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20423 \begin_inset Text
20424
20425 \layout Standard
20426
20427 sdcc/support/scripts
20428 \end_inset
20429 </cell>
20430 </row>
20431 <row topline="true">
20432 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20433 \begin_inset Text
20434
20435 \layout Standard
20436
20437 as-gbz80
20438 \end_inset
20439 </cell>
20440 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20441 \begin_inset Text
20442
20443 \layout Standard
20444
20445 Assembler
20446 \end_inset
20447 </cell>
20448 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20449 \begin_inset Text
20450
20451 \layout Standard
20452
20453
20454 \family roman
20455 \series medium
20456 \shape up
20457 \size normal
20458 \emph off
20459 \bar no
20460 \noun off
20461 \color none
20462 sdcc/bin
20463 \end_inset
20464 </cell>
20465 </row>
20466 <row topline="true">
20467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20468 \begin_inset Text
20469
20470 \layout Standard
20471
20472 as-z80
20473 \end_inset
20474 </cell>
20475 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20476 \begin_inset Text
20477
20478 \layout Standard
20479
20480 Assembler
20481 \end_inset
20482 </cell>
20483 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20484 \begin_inset Text
20485
20486 \layout Standard
20487
20488
20489 \family roman
20490 \series medium
20491 \shape up
20492 \size normal
20493 \emph off
20494 \bar no
20495 \noun off
20496 \color none
20497 sdcc/bin
20498 \end_inset
20499 </cell>
20500 </row>
20501 <row topline="true">
20502 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20503 \begin_inset Text
20504
20505 \layout Standard
20506
20507 asx8051
20508 \end_inset
20509 </cell>
20510 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20511 \begin_inset Text
20512
20513 \layout Standard
20514
20515 Assembler
20516 \end_inset
20517 </cell>
20518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20519 \begin_inset Text
20520
20521 \layout Standard
20522
20523
20524 \family roman
20525 \series medium
20526 \shape up
20527 \size normal
20528 \emph off
20529 \bar no
20530 \noun off
20531 \color none
20532 sdcc/bin
20533 \end_inset
20534 </cell>
20535 </row>
20536 <row topline="true">
20537 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20538 \begin_inset Text
20539
20540 \layout Standard
20541
20542 sdcdb
20543 \end_inset
20544 </cell>
20545 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20546 \begin_inset Text
20547
20548 \layout Standard
20549
20550 Simulator
20551 \end_inset
20552 </cell>
20553 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20554 \begin_inset Text
20555
20556 \layout Standard
20557
20558
20559 \family roman
20560 \series medium
20561 \shape up
20562 \size normal
20563 \emph off
20564 \bar no
20565 \noun off
20566 \color none
20567 sdcc/bin
20568 \end_inset
20569 </cell>
20570 </row>
20571 <row topline="true">
20572 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20573 \begin_inset Text
20574
20575 \layout Standard
20576
20577 aslink
20578 \end_inset
20579 </cell>
20580 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20581 \begin_inset Text
20582
20583 \layout Standard
20584
20585 Linker
20586 \end_inset
20587 </cell>
20588 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20589 \begin_inset Text
20590
20591 \layout Standard
20592
20593
20594 \family roman
20595 \series medium
20596 \shape up
20597 \size normal
20598 \emph off
20599 \bar no
20600 \noun off
20601 \color none
20602 sdcc/bin
20603 \end_inset
20604 </cell>
20605 </row>
20606 <row topline="true">
20607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20608 \begin_inset Text
20609
20610 \layout Standard
20611
20612 link-z80
20613 \end_inset
20614 </cell>
20615 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20616 \begin_inset Text
20617
20618 \layout Standard
20619
20620 Linker
20621 \end_inset
20622 </cell>
20623 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20624 \begin_inset Text
20625
20626 \layout Standard
20627
20628
20629 \family roman
20630 \series medium
20631 \shape up
20632 \size normal
20633 \emph off
20634 \bar no
20635 \noun off
20636 \color none
20637 sdcc/bin
20638 \end_inset
20639 </cell>
20640 </row>
20641 <row topline="true">
20642 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20643 \begin_inset Text
20644
20645 \layout Standard
20646
20647 link-gbz80
20648 \end_inset
20649 </cell>
20650 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20651 \begin_inset Text
20652
20653 \layout Standard
20654
20655 Linker
20656 \end_inset
20657 </cell>
20658 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20659 \begin_inset Text
20660
20661 \layout Standard
20662
20663
20664 \family roman
20665 \series medium
20666 \shape up
20667 \size normal
20668 \emph off
20669 \bar no
20670 \noun off
20671 \color none
20672 sdcc/bin
20673 \end_inset
20674 </cell>
20675 </row>
20676 <row topline="true" bottomline="true">
20677 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20678 \begin_inset Text
20679
20680 \layout Standard
20681
20682 packihx
20683 \end_inset
20684 </cell>
20685 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20686 \begin_inset Text
20687
20688 \layout Standard
20689
20690 ihx packer
20691 \end_inset
20692 </cell>
20693 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20694 \begin_inset Text
20695
20696 \layout Standard
20697
20698
20699 \family roman
20700 \series medium
20701 \shape up
20702 \size normal
20703 \emph off
20704 \bar no
20705 \noun off
20706 \color none
20707 sdcc/bin
20708 \end_inset
20709 </cell>
20710 </row>
20711 </lyxtabular>
20712
20713 \end_inset
20714
20715
20716 \newline
20717
20718 \layout Section
20719
20720 Documentation
20721 \begin_inset LatexCommand \index{Documentation}
20722
20723 \end_inset
20724
20725  included in the distribution
20726 \layout Standard
20727 \align center
20728
20729 \begin_inset  Tabular
20730 <lyxtabular version="3" rows="10" columns="2">
20731 <features>
20732 <column alignment="left" valignment="top" leftline="true" width="0">
20733 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
20734 <row topline="true" bottomline="true">
20735 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20736 \begin_inset Text
20737
20738 \layout Standard
20739
20740 Subject / Title
20741 \end_inset
20742 </cell>
20743 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20744 \begin_inset Text
20745
20746 \layout Standard
20747
20748 Where to get / filename
20749 \end_inset
20750 </cell>
20751 </row>
20752 <row topline="true">
20753 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20754 \begin_inset Text
20755
20756 \layout Standard
20757
20758 SDCC Compiler User Guide
20759 \end_inset
20760 </cell>
20761 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20762 \begin_inset Text
20763
20764 \layout Standard
20765
20766 You're reading it right now
20767 \end_inset
20768 </cell>
20769 </row>
20770 <row topline="true">
20771 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20772 \begin_inset Text
20773
20774 \layout Standard
20775
20776 Changelog of SDCC
20777 \end_inset
20778 </cell>
20779 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20780 \begin_inset Text
20781
20782 \layout Standard
20783
20784 sdcc/Changelog
20785 \end_inset
20786 </cell>
20787 </row>
20788 <row topline="true">
20789 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20790 \begin_inset Text
20791
20792 \layout Standard
20793
20794 ASXXXX
20795 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
20796
20797 \end_inset
20798
20799
20800 \begin_inset LatexCommand \index{Assembler documentation}
20801
20802 \end_inset
20803
20804  Assemblers and ASLINK
20805 \begin_inset LatexCommand \index{aslink}
20806
20807 \end_inset
20808
20809
20810 \begin_inset LatexCommand \index{Linker documentation}
20811
20812 \end_inset
20813
20814  Relocating Linker
20815 \end_inset
20816 </cell>
20817 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20818 \begin_inset Text
20819
20820 \layout Standard
20821
20822 sdcc/as/doc/asxhtm.html
20823 \end_inset
20824 </cell>
20825 </row>
20826 <row topline="true">
20827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20828 \begin_inset Text
20829
20830 \layout Standard
20831
20832 SDCC regression test
20833 \begin_inset LatexCommand \index{Regression test}
20834
20835 \end_inset
20836
20837
20838 \end_inset
20839 </cell>
20840 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20841 \begin_inset Text
20842
20843 \layout Standard
20844
20845 sdcc/doc/test_suite_spec.pdf
20846 \end_inset
20847 </cell>
20848 </row>
20849 <row topline="true">
20850 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20851 \begin_inset Text
20852
20853 \layout Standard
20854
20855 Various notes
20856 \end_inset
20857 </cell>
20858 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20859 \begin_inset Text
20860
20861 \layout Standard
20862
20863 sdcc/doc/*
20864 \end_inset
20865 </cell>
20866 </row>
20867 <row topline="true">
20868 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20869 \begin_inset Text
20870
20871 \layout Standard
20872
20873 Notes on debugging with sdcdb
20874 \begin_inset LatexCommand \index{sdcdb (debugger)}
20875
20876 \end_inset
20877
20878
20879 \end_inset
20880 </cell>
20881 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20882 \begin_inset Text
20883
20884 \layout Standard
20885
20886 sdcc/debugger/README
20887 \end_inset
20888 </cell>
20889 </row>
20890 <row topline="true">
20891 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20892 \begin_inset Text
20893
20894 \layout Standard
20895
20896 Software simulator for microcontrollers
20897 \end_inset
20898 </cell>
20899 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20900 \begin_inset Text
20901
20902 \layout Standard
20903
20904
20905 \family roman
20906 \series medium
20907 \shape up
20908 \size normal
20909 \emph off
20910 \bar no
20911 \noun off
20912 \color none
20913 sdcc/sim/ucsim/doc
20914 \family default
20915 \series default
20916 \shape default
20917 \size default
20918 \emph default
20919 \bar default
20920 \noun default
20921 \color default
20922 /index.html
20923 \end_inset
20924 </cell>
20925 </row>
20926 <row topline="true">
20927 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20928 \begin_inset Text
20929
20930 \layout Standard
20931
20932 Temporary notes on the pic16
20933 \begin_inset LatexCommand \index{PIC16}
20934
20935 \end_inset
20936
20937  port
20938 \end_inset
20939 </cell>
20940 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20941 \begin_inset Text
20942
20943 \layout Standard
20944
20945 sdcc/src/pic16/NOTES
20946 \end_inset
20947 </cell>
20948 </row>
20949 <row topline="true" bottomline="true">
20950 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
20951 \begin_inset Text
20952
20953 \layout Standard
20954
20955 SDCC internal documentation (debugging file format)
20956 \end_inset
20957 </cell>
20958 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
20959 \begin_inset Text
20960
20961 \layout Standard
20962
20963 sdcc/doc/
20964 \family roman
20965 \series medium
20966 \shape up
20967 \size normal
20968 \emph off
20969 \bar no
20970 \noun off
20971 \color none
20972 cdbfileformat.pd
20973 \family default
20974 \series default
20975 \shape default
20976 \size default
20977 \emph default
20978 \bar default
20979 \noun default
20980 \color default
20981 f
20982 \end_inset
20983 </cell>
20984 </row>
20985 </lyxtabular>
20986
20987 \end_inset
20988
20989
20990 \newline
20991
20992 \layout Section
20993
20994 Related open source tools
20995 \begin_inset LatexCommand \index{Related tools}
20996
20997 \end_inset
20998
20999
21000 \layout Standard
21001 \align center
21002
21003 \begin_inset  Tabular
21004 <lyxtabular version="3" rows="11" columns="3">
21005 <features>
21006 <column alignment="center" valignment="top" leftline="true" width="0pt">
21007 <column alignment="block" valignment="top" leftline="true" width="30line%">
21008 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
21009 <row topline="true" bottomline="true">
21010 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21011 \begin_inset Text
21012
21013 \layout Standard
21014
21015 Name
21016 \end_inset
21017 </cell>
21018 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21019 \begin_inset Text
21020
21021 \layout Standard
21022
21023 Purpose
21024 \end_inset
21025 </cell>
21026 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21027 \begin_inset Text
21028
21029 \layout Standard
21030
21031 Where to get
21032 \end_inset
21033 </cell>
21034 </row>
21035 <row topline="true">
21036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21037 \begin_inset Text
21038
21039 \layout Standard
21040
21041 gpsim
21042 \begin_inset LatexCommand \index{gpsim (pic simulator)}
21043
21044 \end_inset
21045
21046
21047 \end_inset
21048 </cell>
21049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21050 \begin_inset Text
21051
21052 \layout Standard
21053
21054 PIC simulator
21055 \end_inset
21056 </cell>
21057 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21058 \begin_inset Text
21059
21060 \layout Standard
21061
21062
21063 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
21064
21065 \end_inset
21066
21067
21068 \end_inset
21069 </cell>
21070 </row>
21071 <row topline="true">
21072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21073 \begin_inset Text
21074
21075 \layout Standard
21076
21077 gputils
21078 \begin_inset LatexCommand \index{gputils (pic tools)}
21079
21080 \end_inset
21081
21082
21083 \end_inset
21084 </cell>
21085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21086 \begin_inset Text
21087
21088 \layout Standard
21089
21090 GNU PIC utilities
21091 \end_inset
21092 </cell>
21093 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21094 \begin_inset Text
21095
21096 \layout Standard
21097
21098
21099 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
21100
21101 \end_inset
21102
21103
21104 \end_inset
21105 </cell>
21106 </row>
21107 <row topline="true">
21108 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21109 \begin_inset Text
21110
21111 \layout Standard
21112
21113 flP5
21114 \end_inset
21115 </cell>
21116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21117 \begin_inset Text
21118
21119 \layout Standard
21120
21121 PIC programmer
21122 \end_inset
21123 </cell>
21124 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21125 \begin_inset Text
21126
21127 \layout Standard
21128
21129
21130 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
21131
21132 \end_inset
21133
21134
21135 \end_inset
21136 </cell>
21137 </row>
21138 <row topline="true">
21139 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21140 \begin_inset Text
21141
21142 \layout Standard
21143
21144 indent
21145 \begin_inset LatexCommand \index{indent (source formatting tool)}
21146
21147 \end_inset
21148
21149
21150 \end_inset
21151 </cell>
21152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21153 \begin_inset Text
21154
21155 \layout Standard
21156
21157 Formats C source - Master of the white spaces
21158 \end_inset
21159 </cell>
21160 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21161 \begin_inset Text
21162
21163 \layout Standard
21164
21165
21166 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
21167
21168 \end_inset
21169
21170
21171 \end_inset
21172 </cell>
21173 </row>
21174 <row topline="true">
21175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21176 \begin_inset Text
21177
21178 \layout Standard
21179
21180 srecord
21181 \begin_inset LatexCommand \index{srecord (tool)}
21182
21183 \end_inset
21184
21185
21186 \end_inset
21187 </cell>
21188 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21189 \begin_inset Text
21190
21191 \layout Standard
21192
21193 Object file conversion, checksumming, ...
21194 \end_inset
21195 </cell>
21196 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21197 \begin_inset Text
21198
21199 \layout Standard
21200
21201
21202 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
21203
21204 \end_inset
21205
21206
21207 \end_inset
21208 </cell>
21209 </row>
21210 <row topline="true">
21211 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21212 \begin_inset Text
21213
21214 \layout Standard
21215
21216 objdump
21217 \begin_inset LatexCommand \index{objdump (tool)}
21218
21219 \end_inset
21220
21221
21222 \end_inset
21223 </cell>
21224 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21225 \begin_inset Text
21226
21227 \layout Standard
21228
21229 Object file conversion, ...
21230 \end_inset
21231 </cell>
21232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21233 \begin_inset Text
21234
21235 \layout Standard
21236
21237 Part of binutils (should be there anyway)
21238 \end_inset
21239 </cell>
21240 </row>
21241 <row topline="true">
21242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21243 \begin_inset Text
21244
21245 \layout Standard
21246
21247 doxygen
21248 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
21249
21250 \end_inset
21251
21252
21253 \end_inset
21254 </cell>
21255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21256 \begin_inset Text
21257
21258 \layout Standard
21259
21260 Source code documentation system
21261 \end_inset
21262 </cell>
21263 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21264 \begin_inset Text
21265
21266 \layout Standard
21267
21268
21269 \begin_inset LatexCommand \url{http://www.doxygen.org}
21270
21271 \end_inset
21272
21273
21274 \end_inset
21275 </cell>
21276 </row>
21277 <row topline="true">
21278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21279 \begin_inset Text
21280
21281 \layout Standard
21282
21283 kdevelop
21284 \end_inset
21285 </cell>
21286 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21287 \begin_inset Text
21288
21289 \layout Standard
21290
21291 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
21292 \end_inset
21293 </cell>
21294 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21295 \begin_inset Text
21296
21297 \layout Standard
21298
21299
21300 \begin_inset LatexCommand \url{http://www.kdevelop.org}
21301
21302 \end_inset
21303
21304
21305 \end_inset
21306 </cell>
21307 </row>
21308 <row topline="true">
21309 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21310 \begin_inset Text
21311
21312 \layout Standard
21313
21314 splint
21315 \begin_inset LatexCommand \index{splint (syntax checking tool)}
21316
21317 \end_inset
21318
21319
21320 \end_inset
21321 </cell>
21322 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21323 \begin_inset Text
21324
21325 \layout Standard
21326
21327 Statically checks c sources (has anyone adapted splint for SDCC?)
21328 \end_inset
21329 </cell>
21330 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21331 \begin_inset Text
21332
21333 \layout Standard
21334
21335
21336 \begin_inset LatexCommand \url{http://www.splint.org}
21337
21338 \end_inset
21339
21340
21341 \end_inset
21342 </cell>
21343 </row>
21344 <row topline="true" bottomline="true">
21345 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21346 \begin_inset Text
21347
21348 \layout Standard
21349
21350 ddd
21351 \begin_inset LatexCommand \index{ddd (debugger)}
21352
21353 \end_inset
21354
21355
21356 \end_inset
21357 </cell>
21358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21359 \begin_inset Text
21360
21361 \layout Standard
21362
21363 Debugger, serves nicely as GUI to sdcdb
21364 \begin_inset LatexCommand \index{sdcdb (debugger)}
21365
21366 \end_inset
21367
21368  (Unix only)
21369 \end_inset
21370 </cell>
21371 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21372 \begin_inset Text
21373
21374 \layout Standard
21375
21376
21377 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
21378
21379 \end_inset
21380
21381
21382 \end_inset
21383 </cell>
21384 </row>
21385 </lyxtabular>
21386
21387 \end_inset
21388
21389
21390 \newline
21391
21392 \layout Section
21393
21394 Related documentation / recommended reading
21395 \layout Standard
21396 \align center
21397
21398 \begin_inset  Tabular
21399 <lyxtabular version="3" rows="6" columns="3">
21400 <features>
21401 <column alignment="center" valignment="top" leftline="true" width="0pt">
21402 <column alignment="block" valignment="top" leftline="true" width="30line%">
21403 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
21404 <row topline="true" bottomline="true">
21405 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21406 \begin_inset Text
21407
21408 \layout Standard
21409
21410 Name
21411 \end_inset
21412 </cell>
21413 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21414 \begin_inset Text
21415
21416 \layout Standard
21417
21418 Subject / Title
21419 \end_inset
21420 </cell>
21421 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21422 \begin_inset Text
21423
21424 \layout Standard
21425
21426 Where to get
21427 \end_inset
21428 </cell>
21429 </row>
21430 <row topline="true">
21431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21432 \begin_inset Text
21433
21434 \layout Standard
21435
21436
21437 \family roman
21438 \series medium
21439 \shape up
21440 \size normal
21441 \emph off
21442 \bar no
21443 \noun off
21444 \color none
21445 c-refcard.pdf
21446 \end_inset
21447 </cell>
21448 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21449 \begin_inset Text
21450
21451 \layout Standard
21452
21453 C Reference Card
21454 \begin_inset LatexCommand \index{C Reference card}
21455
21456 \end_inset
21457
21458 , 2 pages
21459 \end_inset
21460 </cell>
21461 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21462 \begin_inset Text
21463
21464 \layout Standard
21465
21466
21467 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
21468
21469 \end_inset
21470
21471
21472 \end_inset
21473 </cell>
21474 </row>
21475 <row topline="true">
21476 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21477 \begin_inset Text
21478
21479 \layout Standard
21480
21481 c-faq
21482 \end_inset
21483 </cell>
21484 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21485 \begin_inset Text
21486
21487 \layout Standard
21488
21489 C-FAQ-list
21490 \end_inset
21491 </cell>
21492 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21493 \begin_inset Text
21494
21495 \layout Standard
21496
21497
21498 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
21499
21500 \end_inset
21501
21502
21503 \end_inset
21504 </cell>
21505 </row>
21506 <row topline="true">
21507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21508 \begin_inset Text
21509
21510 \layout Standard
21511
21512 \end_inset
21513 </cell>
21514 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21515 \begin_inset Text
21516
21517 \layout Standard
21518
21519 Latest datasheet of the target CPU
21520 \end_inset
21521 </cell>
21522 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21523 \begin_inset Text
21524
21525 \layout Standard
21526
21527 vendor
21528 \end_inset
21529 </cell>
21530 </row>
21531 <row topline="true">
21532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21533 \begin_inset Text
21534
21535 \layout Standard
21536
21537 \end_inset
21538 </cell>
21539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21540 \begin_inset Text
21541
21542 \layout Standard
21543
21544 Revision history of datasheet
21545 \end_inset
21546 </cell>
21547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21548 \begin_inset Text
21549
21550 \layout Standard
21551
21552 vendor
21553 \end_inset
21554 </cell>
21555 </row>
21556 <row topline="true" bottomline="true">
21557 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21558 \begin_inset Text
21559
21560 \layout Standard
21561
21562 S.
21563  S.
21564  Muchnick
21565 \end_inset
21566 </cell>
21567 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
21568 \begin_inset Text
21569
21570 \layout Standard
21571
21572 Advanced Compiler Design and Implementation
21573 \end_inset
21574 </cell>
21575 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
21576 \begin_inset Text
21577
21578 \layout Standard
21579
21580 bookstore (very dedicated, probably read other books first)
21581 \end_inset
21582 </cell>
21583 </row>
21584 </lyxtabular>
21585
21586 \end_inset
21587
21588
21589 \newline
21590
21591 \layout Section
21592
21593 Some Questions
21594 \layout Standard
21595
21596 Some questions answered, some pointers given - it might be time to in turn
21597  ask
21598 \emph on
21599 you
21600 \emph default
21601  some questions:
21602 \layout Itemize
21603
21604 can you solve your project with the selected microcontroller? Would you
21605  find out early or rather late that your target is too small/slow/whatever?
21606  Can you switch to a slightly better device if it doesn't fit?
21607 \layout Itemize
21608
21609 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
21610  and/or another programming language be more adequate? Would an operating
21611  system on the target device help?
21612 \layout Itemize
21613
21614 if you solved the problem, will the marketing department be happy?
21615 \layout Itemize
21616
21617 if the marketing department is happy, will customers be happy?
21618 \layout Itemize
21619
21620 if you're the project manager, marketing department and maybe even the customer
21621  in one person, have you tried to see the project from the outside?
21622 \layout Itemize
21623
21624 is the project done if you think it is done? Or is just that other interface/pro
21625 tocol/feature/configuration/option missing? How about website, manual(s),
21626  internationali(z|s)ation, packaging, labels, 2nd source for components,
21627  electromagnetic compatability/interference, documentation for production,
21628  production test software, update mechanism, patent issues?
21629 \layout Itemize
21630
21631 is your project adequately positioned in that magic triangle: fame, fortune,
21632  fun?
21633 \layout Standard
21634
21635 Maybe not all answers to these questions are known and some answers may
21636  even be
21637 \emph on
21638 no
21639 \emph default
21640 , nevertheless knowing these questions may help you to avoid burnout
21641 \begin_inset Foot
21642 collapsed false
21643
21644 \layout Standard
21645
21646 burnout is bad for electronic devices, programmers and motorcycle tyres
21647 \end_inset
21648
21649 .
21650  Chances are you didn't want to hear some of them...
21651 \layout Chapter
21652
21653 Support
21654 \begin_inset LatexCommand \index{Support}
21655
21656 \end_inset
21657
21658
21659 \layout Standard
21660
21661 SDCC has grown to be a large project.
21662  The compiler alone (without the preprocessor, assembler and linker) is
21663  well over 100,000 lines of code (blank stripped).
21664  The open source nature of this project is a key to its continued growth
21665  and support.
21666  You gain the benefit and support of many active software developers and
21667  end users.
21668  Is SDCC perfect? No, that's why we need your help.
21669  The developers take pride in fixing reported bugs.
21670  You can help by reporting the bugs and helping other SDCC users.
21671  There are lots of ways to contribute, and we encourage you to take part
21672  in making SDCC a great software package.
21673
21674 \layout Standard
21675
21676 The SDCC project is hosted on the SDCC sourceforge site at
21677 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
21678
21679 \end_inset
21680
21681 .
21682  You'll find the complete set of mailing lists
21683 \begin_inset LatexCommand \index{Mailing list(s)}
21684
21685 \end_inset
21686
21687 , forums, bug reporting system, patch submission
21688 \begin_inset LatexCommand \index{Patch submission}
21689
21690 \end_inset
21691
21692  system, download
21693 \begin_inset LatexCommand \index{download}
21694
21695 \end_inset
21696
21697  area and cvs code repository
21698 \begin_inset LatexCommand \index{cvs code repository}
21699
21700 \end_inset
21701
21702  there.
21703 \layout Section
21704
21705 Reporting Bugs
21706 \begin_inset LatexCommand \index{Bug reporting}
21707
21708 \end_inset
21709
21710
21711 \begin_inset LatexCommand \index{Reporting bugs}
21712
21713 \end_inset
21714
21715
21716 \layout Standard
21717
21718 The recommended way of reporting bugs is using the infrastructure of the
21719  sourceforge site.
21720  You can follow the status of bug reports there and have an overview about
21721  the known bugs.
21722 \layout Standard
21723
21724 Bug reports are automatically forwarded to the developer mailing list and
21725  will be fixed ASAP.
21726  When reporting a bug, it is very useful to include a small test program
21727  (the smaller the better) which reproduces the problem.
21728  If you can isolate the problem by looking at the generated assembly code,
21729  this can be very helpful.
21730  Compiling your program with the -
21731 \begin_inset ERT
21732 status Collapsed
21733
21734 \layout Standard
21735
21736 \backslash
21737 /
21738 \end_inset
21739
21740 -dumpall
21741 \begin_inset LatexCommand \index{-\/-dumpall}
21742
21743 \end_inset
21744
21745  option can sometimes be useful in locating optimization problems.
21746  When reporting a bug please maker sure you:
21747 \layout Enumerate
21748
21749 Attach the code you are compiling with SDCC.
21750
21751 \layout Enumerate
21752
21753 Specify the exact command you use to run SDCC, or attach your Makefile.
21754
21755 \layout Enumerate
21756
21757 Specify the SDCC version (type "
21758 \family sans
21759 \series bold
21760 sdcc -v
21761 \family default
21762 \series default
21763 "), your platform, and operating system.
21764
21765 \layout Enumerate
21766
21767 Provide an exact copy of any error message or incorrect output.
21768
21769 \layout Enumerate
21770
21771 Put something meaningful in the subject of your message.
21772 \layout Standard
21773
21774 Please attempt to include these 5 important parts, as applicable, in all
21775  requests for support or when reporting any problems or bugs with SDCC.
21776  Though this will make your message lengthy, it will greatly improve your
21777  chance that SDCC users and developers will be able to help you.
21778  Some SDCC developers are frustrated by bug reports without code provided
21779  that they can use to reproduce and ultimately fix the problem, so please
21780  be sure to provide sample code if you are reporting a bug!
21781 \layout Standard
21782
21783 Please have a short check that you are using a recent version of SDCC and
21784  the bug is not yet known.
21785  This is the link for reporting bugs:
21786 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
21787
21788 \end_inset
21789
21790 .
21791 \layout Section
21792
21793 Requesting Features
21794 \begin_inset LatexCommand \label{sub:Requesting-Features}
21795
21796 \end_inset
21797
21798
21799 \begin_inset LatexCommand \index{Feature request}
21800
21801 \end_inset
21802
21803
21804 \begin_inset LatexCommand \index{Requesting features}
21805
21806 \end_inset
21807
21808
21809 \layout Standard
21810
21811 Like bug reports feature requests are forwarded to the developer mailing
21812  list.
21813  This is the link for requesting features:
21814 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
21815
21816 \end_inset
21817
21818 .
21819 \layout Section
21820
21821 Submitting patches
21822 \layout Standard
21823
21824 Like bug reports contributed patches are forwarded to the developer mailing
21825  list.
21826  This is the link for submitting patches
21827 \begin_inset LatexCommand \index{Patch submission}
21828
21829 \end_inset
21830
21831 :
21832 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
21833
21834 \end_inset
21835
21836 .
21837 \layout Standard
21838
21839 You need to specify some parameters to the
21840 \family typewriter
21841 diff
21842 \family default
21843  command for the patches to be useful.
21844  If you modified more than one file a patch created f.e.
21845  with
21846 \family sans
21847 \series bold
21848
21849 \begin_inset Quotes sld
21850 \end_inset
21851
21852 diff -Naur unmodified_directory modified_directory >my_changes.patch
21853 \begin_inset Quotes srd
21854 \end_inset
21855
21856
21857 \family default
21858 \series default
21859  will be fine, otherwise
21860 \family sans
21861 \series bold
21862
21863 \begin_inset Quotes sld
21864 \end_inset
21865
21866 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
21867 \begin_inset Quotes srd
21868 \end_inset
21869
21870
21871 \series default
21872
21873 \family default
21874 will do.
21875 \layout Section
21876
21877 Getting Help
21878 \layout Standard
21879
21880 These links should take you directly to the
21881 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
21882
21883 \end_inset
21884
21885
21886 \begin_inset Foot
21887 collapsed false
21888
21889 \layout Standard
21890
21891 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
21892  automated messages (mid 2003)
21893 \end_inset
21894
21895  and the
21896 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
21897
21898 \end_inset
21899
21900 , lists
21901 \begin_inset LatexCommand \index{Mailing list(s)}
21902
21903 \end_inset
21904
21905  and forums are archived and searchable so if you are lucky someone already
21906  had a similar problem.
21907  While mails to the lists themselves are delivered promptly their web front
21908  end on sourceforge sometimes shows a severe time lag (up to several weeks),
21909  if you're seriously using SDCC please consider subscribing to the lists.
21910 \layout Section
21911
21912 ChangeLog
21913 \layout Standard
21914
21915 You can follow the status of the cvs version
21916 \begin_inset LatexCommand \index{version}
21917
21918 \end_inset
21919
21920  of SDCC by watching the Changelog
21921 \begin_inset LatexCommand \index{Changelog}
21922
21923 \end_inset
21924
21925  in the cvs-repository
21926 \newline
21927
21928 \size footnotesize
21929
21930 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
21931
21932 \end_inset
21933
21934 .
21935 \layout Section
21936
21937 Release policy
21938 \begin_inset LatexCommand \index{Release policy}
21939
21940 \end_inset
21941
21942
21943 \layout Standard
21944
21945 Historically there often were long delays between official releases and
21946  the sourceforge download area tends to get not updated at all.
21947  Excuses in the past might have referred to problems with live range analysis,
21948  but as this was fixed a while ago, the current problem is that another
21949  excuse has to be found.
21950  Kidding aside, we have to get better there! On the other hand there are
21951  daily snapshots available at
21952 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
21953
21954 \end_inset
21955
21956 , and you can always build the very last version (hopefully with many bugs
21957  fixed, and features added) from the source code available at
21958 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
21959
21960 \end_inset
21961
21962 .
21963 \layout Section
21964
21965 Examples
21966 \begin_inset LatexCommand \index{Examples}
21967
21968 \end_inset
21969
21970
21971 \layout Standard
21972
21973 You'll find some small examples in the directory
21974 \emph on
21975 sdcc/device/examples/.
21976
21977 \emph default
21978 More examples and libraries are available at
21979 \emph on
21980  The SDCC Open Knowledge Resource
21981 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
21982
21983 \end_inset
21984
21985
21986 \emph default
21987 web site or at
21988 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
21989
21990 \end_inset
21991
21992 .
21993 \layout Comment
21994
21995 I did insert a reference to Paul's web site here although it seems rather
21996  dedicated to a specific 8032 board (I think it's okay because it f.e.
21997  shows LCD/Harddisc interface and has a free 8051 monitor.
21998  Independent 8032 board vendors face hard competition of heavily subsidized
21999  development boards anyway).
22000 \layout Comment
22001
22002 Maybe we should include some links to real world applications.
22003  Preferably pointer to pointers (one for each architecture) so this stays
22004  manageable here?
22005 \layout Section
22006
22007 Quality control
22008 \begin_inset LatexCommand \index{Quality control}
22009
22010 \end_inset
22011
22012
22013 \layout Standard
22014
22015 The compiler is passed through nightly compile and build checks.
22016  The so called
22017 \shape italic
22018 regression tests
22019 \shape default
22020
22021 \begin_inset LatexCommand \index{Regression test}
22022
22023 \end_inset
22024
22025  check that SDCC itself compiles flawlessly on several platforms and checks
22026  the quality of the code generated by SDCC by running the code through simulator
22027 s.
22028  There is a separate document
22029 \shape italic
22030 test_suite.pdf
22031 \begin_inset LatexCommand \index{Test suite}
22032
22033 \end_inset
22034
22035
22036 \shape default
22037  about this.
22038 \layout Standard
22039
22040 You'll find the test code in the directory
22041 \shape italic
22042 sdcc/support/regression
22043 \shape default
22044 .
22045  You can run these tests manually by running
22046 \family sans
22047 make
22048 \family default
22049  in this directory (or f.e.
22050
22051 \family sans
22052 \series bold
22053
22054 \begin_inset Quotes sld
22055 \end_inset
22056
22057 make test-mcs51
22058 \begin_inset Quotes srd
22059 \end_inset
22060
22061
22062 \family default
22063 \series default
22064  if you don't want to run the complete tests).
22065  The test code might also be interesting if you want to look for examples
22066 \begin_inset LatexCommand \index{Examples}
22067
22068 \end_inset
22069
22070  checking corner cases of SDCC or if you plan to submit patches
22071 \begin_inset LatexCommand \index{Patch submission}
22072
22073 \end_inset
22074
22075 .
22076 \layout Standard
22077
22078 The pic port uses a different set of regression tests, you'll find them
22079  in the directory
22080 \shape italic
22081 sdcc/src/regression
22082 \shape default
22083 .
22084 \layout Chapter
22085 \pagebreak_top
22086 SDCC Technical Data
22087 \layout Section
22088
22089 Optimizations
22090 \begin_inset LatexCommand \index{Optimizations}
22091
22092 \end_inset
22093
22094
22095 \layout Standard
22096
22097 SDCC performs a host of standard optimizations in addition to some MCU specific
22098  optimizations.
22099
22100 \layout Subsection
22101
22102 Sub-expression Elimination
22103 \begin_inset LatexCommand \index{Subexpression elimination}
22104
22105 \end_inset
22106
22107
22108 \layout Standard
22109
22110 The compiler does local and
22111 \emph on
22112 g
22113 \emph default
22114 lobal
22115 \emph on
22116 c
22117 \emph default
22118 ommon
22119 \emph on
22120 s
22121 \emph default
22122 ubexpression
22123 \emph on
22124 e
22125 \emph default
22126 limination, e.g.:
22127 \layout Verse
22128
22129
22130 \family typewriter
22131 i = x + y + 1;
22132 \newline
22133 j = x + y;
22134 \layout Standard
22135
22136 will be translated to
22137 \layout Verse
22138
22139
22140 \family typewriter
22141 iTemp = x + y;
22142 \newline
22143 i = iTemp + 1;
22144 \newline
22145 j = iTemp;
22146 \layout Standard
22147
22148 Some subexpressions are not as obvious as the above example, e.g.:
22149 \layout Verse
22150
22151
22152 \family typewriter
22153 a->b[i].c = 10;
22154 \newline
22155 a->b[i].d = 11;
22156 \layout Standard
22157
22158 In this case the address arithmetic a->b[i] will be computed only once;
22159  the equivalent code in C would be.
22160 \layout Verse
22161
22162
22163 \family typewriter
22164 iTemp = a->b[i];
22165 \newline
22166 iTemp.c = 10;
22167 \newline
22168 iTemp.d = 11;
22169 \layout Standard
22170
22171 The compiler will try to keep these temporary variables in registers.
22172 \layout Subsection
22173
22174 Dead-Code Elimination
22175 \begin_inset LatexCommand \index{Dead-code elimination}
22176
22177 \end_inset
22178
22179
22180 \layout Verse
22181
22182
22183 \family typewriter
22184 int global;
22185 \newline
22186
22187 \newline
22188 void f () {
22189 \newline
22190 \SpecialChar ~
22191 \SpecialChar ~
22192 int i;
22193 \newline
22194 \SpecialChar ~
22195 \SpecialChar ~
22196 i = 1; \SpecialChar ~
22197 \SpecialChar ~
22198 \SpecialChar ~
22199 \SpecialChar ~
22200 \SpecialChar ~
22201 /* dead store */
22202 \newline
22203 \SpecialChar ~
22204 \SpecialChar ~
22205 global = 1;\SpecialChar ~
22206 /* dead store */
22207 \newline
22208 \SpecialChar ~
22209 \SpecialChar ~
22210 global = 2;
22211 \newline
22212 \SpecialChar ~
22213 \SpecialChar ~
22214 return;
22215 \newline
22216 \SpecialChar ~
22217 \SpecialChar ~
22218 global = 3;\SpecialChar ~
22219 /* unreachable */
22220 \newline
22221 }
22222 \layout Standard
22223
22224 will be changed to
22225 \layout Verse
22226
22227
22228 \family typewriter
22229 int global;
22230 \newline
22231
22232 \newline
22233 void f () {
22234 \newline
22235 \SpecialChar ~
22236 \SpecialChar ~
22237 global = 2;
22238 \newline
22239 }
22240 \layout Subsection
22241
22242 Copy-Propagation
22243 \begin_inset LatexCommand \index{Copy propagation}
22244
22245 \end_inset
22246
22247
22248 \layout Verse
22249
22250
22251 \family typewriter
22252 int f() {
22253 \newline
22254 \SpecialChar ~
22255 \SpecialChar ~
22256 int i, j;
22257 \newline
22258 \SpecialChar ~
22259 \SpecialChar ~
22260 i = 10;
22261 \newline
22262 \SpecialChar ~
22263 \SpecialChar ~
22264 j = i;
22265 \newline
22266 \SpecialChar ~
22267 \SpecialChar ~
22268 return j;
22269 \newline
22270 }
22271 \layout Standard
22272
22273 will be changed to
22274 \layout Verse
22275
22276
22277 \family typewriter
22278 int f() {
22279 \newline
22280 \SpecialChar ~
22281 \SpecialChar ~
22282 int i, j;
22283 \newline
22284 \SpecialChar ~
22285 \SpecialChar ~
22286 i = 10;
22287 \newline
22288 \SpecialChar ~
22289 \SpecialChar ~
22290 j = 10;
22291 \newline
22292 \SpecialChar ~
22293 \SpecialChar ~
22294 return 10;
22295 \newline
22296 }
22297 \layout Standard
22298
22299 Note: the dead stores created by this copy propagation will be eliminated
22300  by dead-code elimination.
22301 \layout Subsection
22302
22303 Loop Optimizations
22304 \begin_inset LatexCommand \index{Loop optimization}
22305
22306 \end_inset
22307
22308
22309 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
22310
22311 \end_inset
22312
22313
22314 \layout Standard
22315
22316 Two types of loop optimizations are done by SDCC
22317 \emph on
22318 loop invariant
22319 \emph default
22320  lifting and
22321 \emph on
22322  strength reduction
22323 \emph default
22324  of loop induction variables.
22325  In addition to the strength reduction the optimizer marks the induction
22326  variables and the register allocator tries to keep the induction variables
22327  in registers for the duration of the loop.
22328  Because of this preference of the register allocator
22329 \begin_inset LatexCommand \index{Register allocation}
22330
22331 \end_inset
22332
22333 , loop induction optimization causes an increase in register pressure, which
22334  may cause unwanted spilling of other temporary variables into the stack
22335 \begin_inset LatexCommand \index{stack}
22336
22337 \end_inset
22338
22339  / data space.
22340  The compiler will generate a warning message when it is forced to allocate
22341  extra space either on the stack or data space.
22342  If this extra space allocation is undesirable then induction optimization
22343  can be eliminated either for the entire source file (with -
22344 \begin_inset ERT
22345 status Collapsed
22346
22347 \layout Standard
22348
22349 \backslash
22350 /
22351 \end_inset
22352
22353 -noinduction option) or for a given function only using #pragma\SpecialChar ~
22354 noinduction
22355 \begin_inset LatexCommand \index{\#pragma noinduction}
22356
22357 \end_inset
22358
22359 .
22360 \newline
22361
22362 \newline
22363 Loop Invariant:
22364 \layout Verse
22365
22366
22367 \family typewriter
22368 for (i = 0 ; i < 100 ; i ++)
22369 \newline
22370 \SpecialChar ~
22371 \SpecialChar ~
22372 \SpecialChar ~
22373 \SpecialChar ~
22374 f += k + l;
22375 \layout Standard
22376
22377 changed to
22378 \layout Verse
22379
22380
22381 \family typewriter
22382 itemp = k + l;
22383 \newline
22384 for (i = 0; i < 100; i++)
22385 \newline
22386 \SpecialChar ~
22387 \SpecialChar ~
22388 \SpecialChar ~
22389 \SpecialChar ~
22390 f += itemp;
22391 \layout Standard
22392
22393 As mentioned previously some loop invariants are not as apparent, all static
22394  address computations are also moved out of the loop.
22395 \newline
22396
22397 \newline
22398 Strength Reduction
22399 \begin_inset LatexCommand \index{Strength reduction}
22400
22401 \end_inset
22402
22403 , this optimization substitutes an expression by a cheaper expression:
22404 \layout Verse
22405
22406
22407 \family typewriter
22408 for (i=0;i < 100; i++)
22409 \newline
22410 \SpecialChar ~
22411 \SpecialChar ~
22412 \SpecialChar ~
22413 \SpecialChar ~
22414 ar[i*5] = i*3;
22415 \layout Standard
22416
22417 changed to
22418 \layout Verse
22419
22420
22421 \family typewriter
22422 itemp1 = 0;
22423 \newline
22424 itemp2 = 0;
22425 \newline
22426 for (i=0;i< 100;i++) {
22427 \newline
22428 \SpecialChar ~
22429 \SpecialChar ~
22430 \SpecialChar ~
22431 \SpecialChar ~
22432 ar[itemp1] = itemp2;
22433 \newline
22434 \SpecialChar ~
22435 \SpecialChar ~
22436 \SpecialChar ~
22437 \SpecialChar ~
22438 itemp1 += 5;
22439 \newline
22440 \SpecialChar ~
22441 \SpecialChar ~
22442 \SpecialChar ~
22443 \SpecialChar ~
22444 itemp2 += 3;
22445 \newline
22446 }
22447 \layout Standard
22448
22449 The more expensive multiplication
22450 \begin_inset LatexCommand \index{Multiplication}
22451
22452 \end_inset
22453
22454  is changed to a less expensive addition.
22455 \layout Subsection
22456
22457 Loop Reversing
22458 \begin_inset LatexCommand \index{Loop reversing}
22459
22460 \end_inset
22461
22462
22463 \layout Standard
22464
22465 This optimization is done to reduce the overhead of checking loop boundaries
22466  for every iteration.
22467  Some simple loops can be reversed and implemented using a
22468 \begin_inset Quotes eld
22469 \end_inset
22470
22471 decrement and jump if not zero
22472 \begin_inset Quotes erd
22473 \end_inset
22474
22475  instruction.
22476  SDCC checks for the following criterion to determine if a loop is reversible
22477  (note: more sophisticated compilers use data-dependency analysis to make
22478  this determination, SDCC uses a more simple minded analysis).
22479 \layout Itemize
22480
22481 The 'for' loop is of the form
22482 \newline
22483
22484 \newline
22485
22486 \family typewriter
22487 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
22488  += 1])
22489 \newline
22490 \SpecialChar ~
22491 \SpecialChar ~
22492 \SpecialChar ~
22493 \SpecialChar ~
22494 <for body>
22495 \layout Itemize
22496
22497 The <for body> does not contain
22498 \begin_inset Quotes eld
22499 \end_inset
22500
22501 continue
22502 \begin_inset Quotes erd
22503 \end_inset
22504
22505  or 'break
22506 \begin_inset Quotes erd
22507 \end_inset
22508
22509 .
22510 \layout Itemize
22511
22512 All goto's are contained within the loop.
22513 \layout Itemize
22514
22515 No function calls within the loop.
22516 \layout Itemize
22517
22518 The loop control variable <sym> is not assigned any value within the loop
22519 \layout Itemize
22520
22521 The loop control variable does NOT participate in any arithmetic operation
22522  within the loop.
22523 \layout Itemize
22524
22525 There are NO switch statements in the loop.
22526 \layout Subsection
22527
22528 Algebraic Simplifications
22529 \layout Standard
22530
22531 SDCC does numerous algebraic simplifications, the following is a small sub-set
22532  of these optimizations.
22533 \layout Verse
22534
22535
22536 \family typewriter
22537 i = j + 0;\SpecialChar ~
22538 \SpecialChar ~
22539 \SpecialChar ~
22540 \SpecialChar ~
22541  /* changed to: */\SpecialChar ~
22542 \SpecialChar ~
22543 \SpecialChar ~
22544 \SpecialChar ~
22545  i = j;
22546 \newline
22547 i /= 2;\SpecialChar ~
22548 \SpecialChar ~
22549 \SpecialChar ~
22550 \SpecialChar ~
22551 \SpecialChar ~
22552 \SpecialChar ~
22553 \SpecialChar ~
22554  /* changed to: */\SpecialChar ~
22555 \SpecialChar ~
22556 \SpecialChar ~
22557 \SpecialChar ~
22558  i >>= 1;
22559 \newline
22560 i = j - j;\SpecialChar ~
22561 \SpecialChar ~
22562 \SpecialChar ~
22563 \SpecialChar ~
22564  /* changed to: */\SpecialChar ~
22565 \SpecialChar ~
22566 \SpecialChar ~
22567 \SpecialChar ~
22568  i = 0;
22569 \newline
22570 i = j / 1;\SpecialChar ~
22571 \SpecialChar ~
22572 \SpecialChar ~
22573 \SpecialChar ~
22574  /* changed to: */\SpecialChar ~
22575 \SpecialChar ~
22576 \SpecialChar ~
22577 \SpecialChar ~
22578  i = j;
22579 \layout Standard
22580
22581 Note the subexpressions
22582 \begin_inset LatexCommand \index{Subexpression}
22583
22584 \end_inset
22585
22586  given above are generally introduced by macro expansions or as a result
22587  of copy/constant propagation.
22588 \layout Subsection
22589
22590 'switch' Statements
22591 \begin_inset LatexCommand \label{sub:'switch'-Statements}
22592
22593 \end_inset
22594
22595
22596 \begin_inset LatexCommand \index{switch statement}
22597
22598 \end_inset
22599
22600
22601 \layout Standard
22602
22603 SDCC can optimize switch statements to jump tables
22604 \begin_inset LatexCommand \index{jump tables}
22605
22606 \end_inset
22607
22608 .
22609  It makes the decision based on an estimate of the generated code size.
22610  SDCC is quite liberal in the requirements for jump table generation:
22611 \layout Itemize
22612
22613 The labels need not be in order, and the starting number need not be one
22614  or zero, the case labels are in numerical sequence or not too many case
22615  labels are missing.
22616 \begin_deeper
22617 \layout Verse
22618
22619
22620 \family typewriter
22621 switch(i) {\SpecialChar ~
22622 \SpecialChar ~
22623 \SpecialChar ~
22624 \SpecialChar ~
22625 \SpecialChar ~
22626 \SpecialChar ~
22627 \SpecialChar ~
22628 \SpecialChar ~
22629 \SpecialChar ~
22630 \SpecialChar ~
22631 \SpecialChar ~
22632 \SpecialChar ~
22633 \SpecialChar ~
22634 \SpecialChar ~
22635 \SpecialChar ~
22636 \SpecialChar ~
22637 \SpecialChar ~
22638 \SpecialChar ~
22639 \SpecialChar ~
22640 \SpecialChar ~
22641 \SpecialChar ~
22642 \SpecialChar ~
22643 \SpecialChar ~
22644 \SpecialChar ~
22645 \SpecialChar ~
22646 \SpecialChar ~
22647 switch (i) {
22648 \newline
22649 \SpecialChar ~
22650 \SpecialChar ~
22651 \SpecialChar ~
22652 case 4: ...\SpecialChar ~
22653 \SpecialChar ~
22654 \SpecialChar ~
22655 \SpecialChar ~
22656 \SpecialChar ~
22657 \SpecialChar ~
22658 \SpecialChar ~
22659 \SpecialChar ~
22660 \SpecialChar ~
22661 \SpecialChar ~
22662 \SpecialChar ~
22663 \SpecialChar ~
22664 \SpecialChar ~
22665 \SpecialChar ~
22666 \SpecialChar ~
22667 \SpecialChar ~
22668 \SpecialChar ~
22669 \SpecialChar ~
22670 \SpecialChar ~
22671 \SpecialChar ~
22672 \SpecialChar ~
22673 \SpecialChar ~
22674 \SpecialChar ~
22675 \SpecialChar ~
22676 \SpecialChar ~
22677 \SpecialChar ~
22678 case 0: ...
22679
22680 \newline
22681 \SpecialChar ~
22682 \SpecialChar ~
22683 \SpecialChar ~
22684 case 5: ...\SpecialChar ~
22685 \SpecialChar ~
22686 \SpecialChar ~
22687 \SpecialChar ~
22688 \SpecialChar ~
22689 \SpecialChar ~
22690 \SpecialChar ~
22691 \SpecialChar ~
22692 \SpecialChar ~
22693 \SpecialChar ~
22694 \SpecialChar ~
22695 \SpecialChar ~
22696 \SpecialChar ~
22697 \SpecialChar ~
22698 \SpecialChar ~
22699 \SpecialChar ~
22700 \SpecialChar ~
22701 \SpecialChar ~
22702 \SpecialChar ~
22703 \SpecialChar ~
22704 \SpecialChar ~
22705 \SpecialChar ~
22706 \SpecialChar ~
22707 \SpecialChar ~
22708 \SpecialChar ~
22709 \SpecialChar ~
22710 case 1: ...
22711
22712 \newline
22713 \SpecialChar ~
22714 \SpecialChar ~
22715 \SpecialChar ~
22716 case 3: ...\SpecialChar ~
22717 \SpecialChar ~
22718 \SpecialChar ~
22719 \SpecialChar ~
22720 \SpecialChar ~
22721 \SpecialChar ~
22722 \SpecialChar ~
22723 \SpecialChar ~
22724 \SpecialChar ~
22725 \SpecialChar ~
22726 \SpecialChar ~
22727 \SpecialChar ~
22728 \SpecialChar ~
22729 \SpecialChar ~
22730 \SpecialChar ~
22731 \SpecialChar ~
22732 \SpecialChar ~
22733 \SpecialChar ~
22734 \SpecialChar ~
22735 \SpecialChar ~
22736 \SpecialChar ~
22737 \SpecialChar ~
22738 \SpecialChar ~
22739 \SpecialChar ~
22740 \SpecialChar ~
22741 \SpecialChar ~
22742
22743 \newline
22744 \SpecialChar ~
22745 \SpecialChar ~
22746 \SpecialChar ~
22747 case 6: ...\SpecialChar ~
22748 \SpecialChar ~
22749 \SpecialChar ~
22750 \SpecialChar ~
22751 \SpecialChar ~
22752 \SpecialChar ~
22753 \SpecialChar ~
22754 \SpecialChar ~
22755 \SpecialChar ~
22756 \SpecialChar ~
22757 \SpecialChar ~
22758 \SpecialChar ~
22759 \SpecialChar ~
22760 \SpecialChar ~
22761 \SpecialChar ~
22762 \SpecialChar ~
22763 \SpecialChar ~
22764 \SpecialChar ~
22765 \SpecialChar ~
22766 \SpecialChar ~
22767 \SpecialChar ~
22768 \SpecialChar ~
22769 \SpecialChar ~
22770 \SpecialChar ~
22771 \SpecialChar ~
22772 \SpecialChar ~
22773 case 3: ...
22774
22775 \newline
22776 \SpecialChar ~
22777 \SpecialChar ~
22778 \SpecialChar ~
22779 case 7: ...\SpecialChar ~
22780 \SpecialChar ~
22781 \SpecialChar ~
22782 \SpecialChar ~
22783 \SpecialChar ~
22784 \SpecialChar ~
22785 \SpecialChar ~
22786 \SpecialChar ~
22787 \SpecialChar ~
22788 \SpecialChar ~
22789 \SpecialChar ~
22790 \SpecialChar ~
22791 \SpecialChar ~
22792 \SpecialChar ~
22793 \SpecialChar ~
22794 \SpecialChar ~
22795 \SpecialChar ~
22796 \SpecialChar ~
22797 \SpecialChar ~
22798 \SpecialChar ~
22799 \SpecialChar ~
22800 \SpecialChar ~
22801 \SpecialChar ~
22802 \SpecialChar ~
22803 \SpecialChar ~
22804 \SpecialChar ~
22805 case 4: ...
22806
22807 \newline
22808 \SpecialChar ~
22809 \SpecialChar ~
22810 \SpecialChar ~
22811 case 8: ...\SpecialChar ~
22812 \SpecialChar ~
22813 \SpecialChar ~
22814 \SpecialChar ~
22815 \SpecialChar ~
22816 \SpecialChar ~
22817 \SpecialChar ~
22818 \SpecialChar ~
22819 \SpecialChar ~
22820 \SpecialChar ~
22821 \SpecialChar ~
22822 \SpecialChar ~
22823 \SpecialChar ~
22824 \SpecialChar ~
22825 \SpecialChar ~
22826 \SpecialChar ~
22827 \SpecialChar ~
22828 \SpecialChar ~
22829 \SpecialChar ~
22830 \SpecialChar ~
22831 \SpecialChar ~
22832 \SpecialChar ~
22833 \SpecialChar ~
22834 \SpecialChar ~
22835 \SpecialChar ~
22836 \SpecialChar ~
22837 case 5: ...
22838
22839 \newline
22840 \SpecialChar ~
22841 \SpecialChar ~
22842 \SpecialChar ~
22843 case 9: ...\SpecialChar ~
22844 \SpecialChar ~
22845 \SpecialChar ~
22846 \SpecialChar ~
22847 \SpecialChar ~
22848 \SpecialChar ~
22849 \SpecialChar ~
22850 \SpecialChar ~
22851 \SpecialChar ~
22852 \SpecialChar ~
22853 \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 case 6: ...
22870
22871 \newline
22872 \SpecialChar ~
22873 \SpecialChar ~
22874 \SpecialChar ~
22875 case 10: ...\SpecialChar ~
22876 \SpecialChar ~
22877 \SpecialChar ~
22878 \SpecialChar ~
22879 \SpecialChar ~
22880 \SpecialChar ~
22881 \SpecialChar ~
22882 \SpecialChar ~
22883 \SpecialChar ~
22884 \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 case 7: ...
22901
22902 \newline
22903 \SpecialChar ~
22904 \SpecialChar ~
22905 \SpecialChar ~
22906 case 11: ...\SpecialChar ~
22907 \SpecialChar ~
22908 \SpecialChar ~
22909 \SpecialChar ~
22910 \SpecialChar ~
22911 \SpecialChar ~
22912 \SpecialChar ~
22913 \SpecialChar ~
22914 \SpecialChar ~
22915 \SpecialChar ~
22916 \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 case 8: ...
22932
22933 \newline
22934 }\SpecialChar ~
22935 \SpecialChar ~
22936 \SpecialChar ~
22937 \SpecialChar ~
22938 \SpecialChar ~
22939 \SpecialChar ~
22940 \SpecialChar ~
22941 \SpecialChar ~
22942 \SpecialChar ~
22943 \SpecialChar ~
22944 \SpecialChar ~
22945 \SpecialChar ~
22946 \SpecialChar ~
22947 \SpecialChar ~
22948 \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 }
22971 \layout Standard
22972
22973 Both the above switch statements will be implemented using a jump-table.
22974  The example to the right side is slightly more efficient as the check for
22975  the lower boundary of the jump-table is not needed.
22976 \end_deeper
22977 \layout Itemize
22978
22979 The number of case labels is not larger than supported by the target architectur
22980 e.
22981 \layout Itemize
22982
22983 If the case labels are not in numerical sequence ('gaps' between cases)
22984  SDCC checks whether a jump table with additionally inserted dummy cases
22985  is still attractive.
22986
22987 \layout Itemize
22988
22989 If the starting number is not zero and a check for the lower boundary of
22990  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
22991  ...
22992  .
22993 \layout Standard
22994
22995 Switch statements which have large gaps in the numeric sequence or those
22996  that have too many case labels can be split into more than one switch statement
22997  for efficient code generation, e.g.:
22998 \layout Verse
22999
23000
23001 \family typewriter
23002 switch (i) {
23003 \newline
23004 \SpecialChar ~
23005 \SpecialChar ~
23006 case 1: ...
23007
23008 \newline
23009 \SpecialChar ~
23010 \SpecialChar ~
23011 case 2: ...
23012
23013 \newline
23014 \SpecialChar ~
23015 \SpecialChar ~
23016 case 3: ...
23017
23018 \newline
23019 \SpecialChar ~
23020 \SpecialChar ~
23021 case 4: ...
23022
23023 \newline
23024 \SpecialChar ~
23025 \SpecialChar ~
23026 case 5: ...
23027
23028 \newline
23029 \SpecialChar ~
23030 \SpecialChar ~
23031 case 6: ...
23032
23033 \newline
23034 \SpecialChar ~
23035 \SpecialChar ~
23036 case 7: ...
23037
23038 \newline
23039 \SpecialChar ~
23040 \SpecialChar ~
23041 case 101: ...
23042
23043 \newline
23044 \SpecialChar ~
23045 \SpecialChar ~
23046 case 102: ...
23047
23048 \newline
23049 \SpecialChar ~
23050 \SpecialChar ~
23051 case 103: ...
23052
23053 \newline
23054 \SpecialChar ~
23055 \SpecialChar ~
23056 case 104: ...
23057
23058 \newline
23059 \SpecialChar ~
23060 \SpecialChar ~
23061 case 105: ...
23062
23063 \newline
23064 \SpecialChar ~
23065 \SpecialChar ~
23066 case 106: ...
23067
23068 \newline
23069 \SpecialChar ~
23070 \SpecialChar ~
23071 case 107: ...
23072
23073 \newline
23074 }
23075 \layout Standard
23076
23077 If the above switch statement is broken down into two switch statements
23078 \layout Verse
23079
23080
23081 \family typewriter
23082 switch (i) {
23083 \newline
23084 \SpecialChar ~
23085 \SpecialChar ~
23086 case 1: ...
23087
23088 \newline
23089 \SpecialChar ~
23090 \SpecialChar ~
23091 case 2: ...
23092
23093 \newline
23094 \SpecialChar ~
23095 \SpecialChar ~
23096 case 3: ...
23097
23098 \newline
23099 \SpecialChar ~
23100 \SpecialChar ~
23101 case 4: ...
23102
23103 \newline
23104 \SpecialChar ~
23105 \SpecialChar ~
23106 case 5: ...
23107
23108 \newline
23109 \SpecialChar ~
23110 \SpecialChar ~
23111 case 6: ...
23112
23113 \newline
23114 \SpecialChar ~
23115 \SpecialChar ~
23116 case 7: ...
23117
23118 \newline
23119 }
23120 \layout Standard
23121
23122 and
23123 \layout Verse
23124
23125
23126 \family typewriter
23127 switch (i) {
23128 \newline
23129 \SpecialChar ~
23130 \SpecialChar ~
23131 case 101: ...
23132
23133 \newline
23134 \SpecialChar ~
23135 \SpecialChar ~
23136 case 102: ...
23137
23138 \newline
23139 \SpecialChar ~
23140 \SpecialChar ~
23141 case 103: ...
23142
23143 \newline
23144 \SpecialChar ~
23145 \SpecialChar ~
23146 case 104: ...
23147
23148 \newline
23149 \SpecialChar ~
23150 \SpecialChar ~
23151 case 105: ...
23152
23153 \newline
23154 \SpecialChar ~
23155 \SpecialChar ~
23156 case 106: ...
23157
23158 \newline
23159 \SpecialChar ~
23160 \SpecialChar ~
23161 case 107: ...
23162
23163 \newline
23164 }
23165 \layout Standard
23166
23167 then both the switch statements will be implemented using jump-tables whereas
23168  the unmodified switch statement will not be.
23169 \layout Comment
23170
23171 There might be reasons which SDCC cannot know about to either favour or
23172  not favour jump tables.
23173  If the target system has to be as quick for the last switch case as for
23174  the first (pro jump table), or if the switch argument is known to be zero
23175  in the majority of the cases (contra jump table).
23176 \layout Standard
23177
23178 The pragma nojtbound
23179 \begin_inset LatexCommand \index{\#pragma nojtbound}
23180
23181 \end_inset
23182
23183  can be used to turn off checking the
23184 \emph on
23185 j
23186 \emph default
23187 ump
23188 \emph on
23189 t
23190 \emph default
23191 able
23192 \emph on
23193 bound
23194 \emph default
23195 aries.
23196  It has no effect if a default label is supplied.
23197  Use of this pragma is dangerous: if the switch argument is not matched
23198  by a case statement the processor will happily jump into Nirvana.
23199 \layout Subsection
23200
23201 Bit-shifting Operations
23202 \begin_inset LatexCommand \index{Bit shifting}
23203
23204 \end_inset
23205
23206 .
23207 \layout Standard
23208
23209 Bit shifting is one of the most frequently used operation in embedded programmin
23210 g.
23211  SDCC tries to implement bit-shift operations in the most efficient way
23212  possible, e.g.:
23213 \layout Verse
23214
23215
23216 \family typewriter
23217 unsigned char i;
23218 \newline
23219 ...
23220
23221 \newline
23222 i >>= 4;
23223 \newline
23224 ...
23225 \layout Standard
23226
23227 generates the following code:
23228 \layout Verse
23229
23230
23231 \family typewriter
23232 mov\SpecialChar ~
23233  a,_i
23234 \newline
23235 swap a
23236 \newline
23237 anl\SpecialChar ~
23238  a,#0x0f
23239 \newline
23240 mov\SpecialChar ~
23241  _i,a
23242 \layout Standard
23243
23244 In general SDCC will never setup a loop if the shift count is known.
23245  Another example:
23246 \layout Verse
23247
23248
23249 \family typewriter
23250 unsigned int i;
23251 \newline
23252 ...
23253
23254 \newline
23255 i >>= 9;
23256 \newline
23257 ...
23258 \layout Standard
23259
23260 will generate:
23261 \layout Verse
23262
23263
23264 \family typewriter
23265 mov\SpecialChar ~
23266 \SpecialChar ~
23267 a,(_i + 1)
23268 \newline
23269 mov\SpecialChar ~
23270 \SpecialChar ~
23271 (_i + 1),#0x00
23272 \newline
23273 clr\SpecialChar ~
23274 \SpecialChar ~
23275 c
23276 \newline
23277 rrc\SpecialChar ~
23278 \SpecialChar ~
23279 a
23280 \newline
23281 mov\SpecialChar ~
23282 \SpecialChar ~
23283 _i,a
23284 \layout Subsection
23285
23286 Bit-rotation
23287 \begin_inset LatexCommand \index{Bit rotation}
23288
23289 \end_inset
23290
23291
23292 \layout Standard
23293
23294 A special case of the bit-shift operation is bit rotation
23295 \begin_inset LatexCommand \index{rotating bits}
23296
23297 \end_inset
23298
23299 , SDCC recognizes the following expression to be a left bit-rotation:
23300 \layout Verse
23301
23302
23303 \family typewriter
23304 \series bold
23305 unsigned
23306 \series default
23307 \SpecialChar ~
23308 \SpecialChar ~
23309 char i;\SpecialChar ~
23310 \SpecialChar ~
23311 \SpecialChar ~
23312 \SpecialChar ~
23313 \SpecialChar ~
23314 \SpecialChar ~
23315 \SpecialChar ~
23316 \SpecialChar ~
23317 \SpecialChar ~
23318 \SpecialChar ~
23319 \SpecialChar ~
23320 /* unsigned is needed for rotation */
23321 \newline
23322 ...
23323
23324 \newline
23325 i = ((i << 1) | (i >> 7));
23326 \family default
23327
23328 \newline
23329
23330 \family typewriter
23331 ...
23332 \layout Standard
23333
23334 will generate the following code:
23335 \layout Verse
23336
23337
23338 \family typewriter
23339 mov\SpecialChar ~
23340 \SpecialChar ~
23341 a,_i
23342 \newline
23343 rl\SpecialChar ~
23344 \SpecialChar ~
23345 \SpecialChar ~
23346 a
23347 \newline
23348 mov\SpecialChar ~
23349 \SpecialChar ~
23350 _i,a
23351 \layout Standard
23352
23353 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
23354 ns of this case will also be recognized as bit-rotation, i.e.:
23355 \layout Verse
23356
23357
23358 \family typewriter
23359 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
23360 \layout Subsection
23361
23362 Nibble and Byte Swapping
23363 \layout Standard
23364
23365 Other special cases of the bit-shift operations are nibble or byte swapping
23366 \begin_inset LatexCommand \index{swapping nibbles/bytes}
23367
23368 \end_inset
23369
23370 , SDCC recognizes the following expressions:
23371 \layout Verse
23372
23373
23374 \family typewriter
23375 \series bold
23376 unsigned
23377 \series default
23378 \SpecialChar ~
23379 \SpecialChar ~
23380 char i;
23381 \newline
23382
23383 \series bold
23384 unsigned
23385 \series default
23386 \SpecialChar ~
23387 \SpecialChar ~
23388 int j;
23389 \newline
23390 ...
23391
23392 \newline
23393 i = ((i << 4) | (i >> 4));
23394 \family default
23395
23396 \newline
23397
23398 \family typewriter
23399 j = ((j << 8) | (j >> 8));
23400 \layout Standard
23401
23402 and generates a swap instruction for the nibble swapping
23403 \begin_inset LatexCommand \index{Nibble swapping}
23404
23405 \end_inset
23406
23407  or move instructions for the byte swapping
23408 \begin_inset LatexCommand \index{Byte swapping}
23409
23410 \end_inset
23411
23412 .
23413  The
23414 \begin_inset Quotes sld
23415 \end_inset
23416
23417 j
23418 \begin_inset Quotes srd
23419 \end_inset
23420
23421  example can be used to convert from little to big-endian or vice versa.
23422  If you want to change the endianness of a
23423 \emph on
23424 signed
23425 \emph default
23426  integer you have to cast to
23427 \family typewriter
23428 (unsigned int)
23429 \family default
23430  first.
23431 \layout Standard
23432
23433 Note that SDCC stores numbers in little-endian
23434 \begin_inset Foot
23435 collapsed false
23436
23437 \layout Standard
23438
23439 Usually 8-bit processors don't care much about endianness.
23440  This is not the case for the standard 8051 which only has an instruction
23441  to increment its
23442 \emph on
23443 dptr
23444 \emph default
23445
23446 \begin_inset LatexCommand \index{DPTR}
23447
23448 \end_inset
23449
23450 -datapointer
23451 \emph on
23452
23453 \emph default
23454 so little-endian is the more efficient byte order.
23455 \end_inset
23456
23457
23458 \begin_inset LatexCommand \index{little-endian}
23459
23460 \end_inset
23461
23462
23463 \begin_inset LatexCommand \index{Endianness}
23464
23465 \end_inset
23466
23467  format (i.e.
23468  lowest order first).
23469 \layout Subsection
23470
23471 Highest Order Bit
23472 \begin_inset LatexCommand \index{Highest Order Bit}
23473
23474 \end_inset
23475
23476
23477 \layout Standard
23478
23479 It is frequently required to obtain the highest order bit of an integral
23480  type (long, int, short or char types).
23481  SDCC recognizes the following expression to yield the highest order bit
23482  and generates optimized code for it, e.g.:
23483 \layout Verse
23484
23485
23486 \family typewriter
23487 unsigned int gint;
23488 \newline
23489
23490 \newline
23491 foo () {
23492 \newline
23493 \SpecialChar ~
23494 \SpecialChar ~
23495 unsigned char hob;
23496 \newline
23497 \SpecialChar ~
23498 \SpecialChar ~
23499 ...
23500
23501 \newline
23502 \SpecialChar ~
23503 \SpecialChar ~
23504 hob = (gint >> 15) & 1;
23505 \newline
23506 \SpecialChar ~
23507 \SpecialChar ~
23508 ..
23509
23510 \newline
23511 }
23512 \layout Standard
23513
23514 will generate the following code:
23515 \layout Verse
23516
23517
23518 \family typewriter
23519 \SpecialChar ~
23520 \SpecialChar ~
23521 \SpecialChar ~
23522 \SpecialChar ~
23523 \SpecialChar ~
23524 \SpecialChar ~
23525 \SpecialChar ~
23526 \SpecialChar ~
23527 \SpecialChar ~
23528 \SpecialChar ~
23529 \SpecialChar ~
23530 \SpecialChar ~
23531 \SpecialChar ~
23532 \SpecialChar ~
23533 \SpecialChar ~
23534 \SpecialChar ~
23535 \SpecialChar ~
23536 \SpecialChar ~
23537 \SpecialChar ~
23538 \SpecialChar ~
23539 \SpecialChar ~
23540 \SpecialChar ~
23541 \SpecialChar ~
23542 \SpecialChar ~
23543 \SpecialChar ~
23544  61 ;\SpecialChar ~
23545  hob.c 7
23546 \newline
23547 000A E5*01\SpecialChar ~
23548 \SpecialChar ~
23549 \SpecialChar ~
23550 \SpecialChar ~
23551 \SpecialChar ~
23552 \SpecialChar ~
23553 \SpecialChar ~
23554 \SpecialChar ~
23555 \SpecialChar ~
23556 \SpecialChar ~
23557 \SpecialChar ~
23558 \SpecialChar ~
23559 \SpecialChar ~
23560 \SpecialChar ~
23561 \SpecialChar ~
23562  62\SpecialChar ~
23563 \SpecialChar ~
23564 \SpecialChar ~
23565 \SpecialChar ~
23566 \SpecialChar ~
23567 \SpecialChar ~
23568 \SpecialChar ~
23569 \SpecialChar ~
23570  mov\SpecialChar ~
23571 \SpecialChar ~
23572  a,(_gint + 1)
23573 \newline
23574 000C 23\SpecialChar ~
23575 \SpecialChar ~
23576 \SpecialChar ~
23577 \SpecialChar ~
23578 \SpecialChar ~
23579 \SpecialChar ~
23580 \SpecialChar ~
23581 \SpecialChar ~
23582 \SpecialChar ~
23583 \SpecialChar ~
23584 \SpecialChar ~
23585 \SpecialChar ~
23586 \SpecialChar ~
23587 \SpecialChar ~
23588 \SpecialChar ~
23589 \SpecialChar ~
23590 \SpecialChar ~
23591 \SpecialChar ~
23592  63\SpecialChar ~
23593 \SpecialChar ~
23594 \SpecialChar ~
23595 \SpecialChar ~
23596 \SpecialChar ~
23597 \SpecialChar ~
23598 \SpecialChar ~
23599 \SpecialChar ~
23600  rl\SpecialChar ~
23601 \SpecialChar ~
23602 \SpecialChar ~
23603  a
23604 \newline
23605 000D 54 01\SpecialChar ~
23606 \SpecialChar ~
23607 \SpecialChar ~
23608 \SpecialChar ~
23609 \SpecialChar ~
23610 \SpecialChar ~
23611 \SpecialChar ~
23612 \SpecialChar ~
23613 \SpecialChar ~
23614 \SpecialChar ~
23615 \SpecialChar ~
23616 \SpecialChar ~
23617 \SpecialChar ~
23618 \SpecialChar ~
23619 \SpecialChar ~
23620  64\SpecialChar ~
23621 \SpecialChar ~
23622 \SpecialChar ~
23623 \SpecialChar ~
23624 \SpecialChar ~
23625 \SpecialChar ~
23626 \SpecialChar ~
23627 \SpecialChar ~
23628  anl\SpecialChar ~
23629 \SpecialChar ~
23630  a,#0x01
23631 \newline
23632 000F F5*02\SpecialChar ~
23633 \SpecialChar ~
23634 \SpecialChar ~
23635 \SpecialChar ~
23636 \SpecialChar ~
23637 \SpecialChar ~
23638 \SpecialChar ~
23639 \SpecialChar ~
23640 \SpecialChar ~
23641 \SpecialChar ~
23642 \SpecialChar ~
23643 \SpecialChar ~
23644 \SpecialChar ~
23645 \SpecialChar ~
23646 \SpecialChar ~
23647  65\SpecialChar ~
23648 \SpecialChar ~
23649 \SpecialChar ~
23650 \SpecialChar ~
23651 \SpecialChar ~
23652 \SpecialChar ~
23653 \SpecialChar ~
23654 \SpecialChar ~
23655  mov\SpecialChar ~
23656 \SpecialChar ~
23657  _foo_hob_1_1,a
23658 \layout Standard
23659
23660 Variations of this case however will
23661 \emph on
23662 not
23663 \emph default
23664  be recognized.
23665  It is a standard C expression, so I heartily recommend this be the only
23666  way to get the highest order bit, (it is portable).
23667  Of course it will be recognized even if it is embedded in other expressions,
23668  e.g.:
23669 \layout Verse
23670
23671
23672 \family typewriter
23673 xyz = gint + ((gint >> 15) & 1);
23674 \layout Standard
23675
23676 will still be recognized.
23677 \layout Subsection
23678
23679 Peephole Optimizer
23680 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
23681
23682 \end_inset
23683
23684
23685 \begin_inset LatexCommand \index{Peephole optimizer}
23686
23687 \end_inset
23688
23689
23690 \layout Standard
23691
23692 The compiler uses a rule based, pattern matching and re-writing mechanism
23693  for peep-hole optimization.
23694  It is inspired by
23695 \emph on
23696 copt
23697 \emph default
23698  a peep-hole optimizer by Christopher W.
23699  Fraser (cwfraser@microsoft.com).
23700  A default set of rules are compiled into the compiler, additional rules
23701  may be added with the
23702 \emph on
23703 -
23704 \begin_inset ERT
23705 status Collapsed
23706
23707 \layout Standard
23708
23709 \backslash
23710 /
23711 \end_inset
23712
23713 -peep-file
23714 \begin_inset LatexCommand \index{-\/-peep-file}
23715
23716 \end_inset
23717
23718  <filename>
23719 \emph default
23720  option.
23721  The rule language is best illustrated with examples.
23722 \layout Verse
23723
23724
23725 \family typewriter
23726 replace {
23727 \newline
23728 \SpecialChar ~
23729 \SpecialChar ~
23730 mov %1,a
23731 \newline
23732 \SpecialChar ~
23733 \SpecialChar ~
23734 mov a,%1
23735 \newline
23736 } by {
23737 \newline
23738 \SpecialChar ~
23739 \SpecialChar ~
23740 mov %1,a
23741 \newline
23742 }
23743 \layout Standard
23744
23745 The above rule will change the following assembly
23746 \begin_inset LatexCommand \index{Assembler routines}
23747
23748 \end_inset
23749
23750  sequence:
23751 \layout Verse
23752
23753
23754 \family typewriter
23755 mov r1,a
23756 \newline
23757 mov a,r1
23758 \layout Standard
23759
23760 to
23761 \layout Verse
23762
23763
23764 \family typewriter
23765 mov r1,a
23766 \layout Standard
23767
23768 Note: All occurrences of a
23769 \emph on
23770 %n
23771 \emph default
23772  (pattern variable) must denote the same string.
23773  With the above rule, the assembly sequence:
23774 \layout Verse
23775
23776
23777 \family typewriter
23778 mov r1,a
23779 \newline
23780 mov a,r2
23781 \layout Standard
23782
23783 will remain unmodified.
23784 \newline
23785
23786 \newline
23787 Other special case optimizations may be added by the user (via
23788 \emph on
23789 -
23790 \begin_inset ERT
23791 status Collapsed
23792
23793 \layout Standard
23794
23795 \backslash
23796 /
23797 \end_inset
23798
23799 -peep-file option
23800 \emph default
23801 ).
23802  E.g.
23803  some variants of the 8051 MCU
23804 \begin_inset LatexCommand \index{MCS51 variants}
23805
23806 \end_inset
23807
23808  allow only
23809 \family typewriter
23810 ajmp
23811 \family default
23812  and
23813 \family typewriter
23814 acall
23815 \family default
23816 .
23817  The following two rules will change all
23818 \family typewriter
23819 ljmp
23820 \family default
23821  and
23822 \family typewriter
23823 lcall
23824 \family default
23825  to
23826 \family typewriter
23827 ajmp
23828 \family default
23829  and
23830 \family typewriter
23831 acall
23832 \layout Verse
23833
23834
23835 \family typewriter
23836 replace { lcall %1 } by { acall %1 }
23837 \newline
23838 replace { ljmp %1 } by { ajmp %1 }
23839 \layout Standard
23840
23841 The
23842 \emph on
23843 inline-assembler code
23844 \emph default
23845  is also passed through the peep hole optimizer, thus the peephole optimizer
23846  can also be used as an assembly level macro expander.
23847  The rules themselves are MCU dependent whereas the rule language infra-structur
23848 e is MCU independent.
23849  Peephole optimization rules for other MCU can be easily programmed using
23850  the rule language.
23851 \newline
23852
23853 \newline
23854 The syntax for a rule is as follows:
23855 \layout Verse
23856
23857
23858 \family typewriter
23859 rule := replace [ restart ] '{' <assembly sequence> '
23860 \backslash
23861 n'
23862 \newline
23863 \SpecialChar ~
23864  \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  '}' by '{' '
23878 \backslash
23879 n'
23880 \newline
23881 \SpecialChar ~
23882  \SpecialChar ~
23883  \SpecialChar ~
23884  \SpecialChar ~
23885  \SpecialChar ~
23886  \SpecialChar ~
23887  \SpecialChar ~
23888  \SpecialChar ~
23889  \SpecialChar ~
23890  \SpecialChar ~
23891  \SpecialChar ~
23892  \SpecialChar ~
23893  \SpecialChar ~
23894  \SpecialChar ~
23895  \SpecialChar ~
23896  \SpecialChar ~
23897  <assembly sequence> '
23898 \backslash
23899 n'
23900 \newline
23901 \SpecialChar ~
23902  \SpecialChar ~
23903  \SpecialChar ~
23904  \SpecialChar ~
23905  \SpecialChar ~
23906  \SpecialChar ~
23907  \SpecialChar ~
23908  \SpecialChar ~
23909  \SpecialChar ~
23910  \SpecialChar ~
23911  \SpecialChar ~
23912  \SpecialChar ~
23913  \SpecialChar ~
23914  \SpecialChar ~
23915  '}' [if <functionName> ] '
23916 \backslash
23917 n'
23918 \layout Standard
23919
23920 <assembly sequence> := assembly instruction (each instruction including
23921  labels must be on a separate line).
23922 \newline
23923
23924 \newline
23925 The optimizer will apply to the rules one by one from the top in the sequence
23926  of their appearance, it will terminate when all rules are exhausted.
23927  If the 'restart' option is specified, then the optimizer will start matching
23928  the rules again from the top, this option for a rule is expensive (performance)
23929 , it is intended to be used in situations where a transformation will trigger
23930  the same rule again.
23931  An example of this (not a good one, it has side effects) is the following
23932  rule:
23933 \layout Verse
23934
23935
23936 \family typewriter
23937 replace restart {
23938 \newline
23939 \SpecialChar ~
23940 \SpecialChar ~
23941 pop %1
23942 \newline
23943 \SpecialChar ~
23944 \SpecialChar ~
23945 push %1 } by {
23946 \newline
23947 \SpecialChar ~
23948 \SpecialChar ~
23949 ; nop
23950 \newline
23951 }
23952 \layout Standard
23953
23954 Note that the replace pattern cannot be a blank, but can be a comment line.
23955  Without the 'restart' option only the innermost 'pop' 'push' pair would
23956  be eliminated, i.e.:
23957 \layout Verse
23958
23959
23960 \family typewriter
23961 pop ar1
23962 \newline
23963 pop ar2
23964 \newline
23965 push ar2
23966 \newline
23967 push ar1
23968 \layout Standard
23969
23970 would result in:
23971 \layout Verse
23972
23973
23974 \family typewriter
23975 pop ar1
23976 \newline
23977 ; nop
23978 \newline
23979 push ar1
23980 \layout Standard
23981
23982
23983 \emph on
23984 with
23985 \emph default
23986  the restart option the rule will be applied again to the resulting code
23987  and then all the pop-push pairs will be eliminated to yield:
23988 \layout Verse
23989
23990
23991 \family typewriter
23992 ; nop
23993 \newline
23994 ; nop
23995 \layout Standard
23996
23997 A conditional function can be attached to a rule.
23998  Attaching rules are somewhat more involved, let me illustrate this with
23999  an example.
24000 \layout Verse
24001
24002
24003 \family typewriter
24004 replace {
24005 \newline
24006 \SpecialChar ~
24007  \SpecialChar ~
24008  \SpecialChar ~
24009 ljmp %5
24010 \newline
24011 %2:
24012 \newline
24013 } by {
24014 \newline
24015 \SpecialChar ~
24016  \SpecialChar ~
24017  \SpecialChar ~
24018 sjmp %5
24019 \newline
24020 %2:
24021 \newline
24022 } if labelInRange
24023 \layout Standard
24024
24025 The optimizer does a look-up of a function name table defined in function
24026
24027 \emph on
24028 callFuncByName
24029 \emph default
24030  in the source file SDCCpeeph.c, with the name
24031 \emph on
24032 labelInRange
24033 \emph default
24034 .
24035  If it finds a corresponding entry the function is called.
24036  Note there can be no parameters specified for these functions, in this
24037  case the use of
24038 \emph on
24039 %5
24040 \emph default
24041  is crucial, since the function
24042 \emph on
24043 labelInRange
24044 \emph default
24045  expects to find the label in that particular variable (the hash table containin
24046 g the variable bindings is passed as a parameter).
24047  If you want to code more such functions, take a close look at the function
24048  labelInRange and the calling mechanism in source file SDCCpeeph.c.
24049  Currently implemented are
24050 \emph on
24051 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
24052  24bitMode, portIsDS390, 24bitModeAndPortDS390
24053 \emph default
24054 and
24055 \emph on
24056  notVolatile
24057 \emph default
24058 .
24059 \layout Standard
24060
24061 I know this whole thing is a little kludgey, but maybe some day we will
24062  have some better means.
24063  If you are looking at this file, you will see the default rules that are
24064  compiled into the compiler, you can add your own rules in the default set
24065  there if you get tired of specifying the -
24066 \begin_inset ERT
24067 status Collapsed
24068
24069 \layout Standard
24070
24071 \backslash
24072 /
24073 \end_inset
24074
24075 -peep-file option.
24076 \layout Section
24077
24078 ANSI-Compliance
24079 \begin_inset LatexCommand \index{ANSI-compliance}
24080
24081 \end_inset
24082
24083
24084 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
24085
24086 \end_inset
24087
24088
24089 \layout Standard
24090
24091 Deviations from the compliance:
24092 \layout Itemize
24093
24094 functions are not always reentrant
24095 \begin_inset LatexCommand \index{reentrant}
24096
24097 \end_inset
24098
24099 .
24100 \layout Itemize
24101
24102 structures cannot be assigned values directly, cannot be passed as function
24103  parameters or assigned to each other and cannot be a return value from
24104  a function, e.g.:
24105 \begin_deeper
24106 \layout Verse
24107
24108
24109 \family typewriter
24110 struct s { ...
24111  };
24112 \newline
24113 struct s s1, s2;
24114 \newline
24115 foo()
24116 \newline
24117 {
24118 \newline
24119 \SpecialChar ~
24120 \SpecialChar ~
24121 \SpecialChar ~
24122 \SpecialChar ~
24123 ...
24124
24125 \newline
24126 \SpecialChar ~
24127 \SpecialChar ~
24128 \SpecialChar ~
24129 \SpecialChar ~
24130 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
24131 \newline
24132 \SpecialChar ~
24133 \SpecialChar ~
24134 \SpecialChar ~
24135 \SpecialChar ~
24136 ...
24137
24138 \newline
24139 }
24140 \newline
24141 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
24142  */
24143 \newline
24144 {
24145 \newline
24146 \SpecialChar ~
24147 \SpecialChar ~
24148 \SpecialChar ~
24149 \SpecialChar ~
24150 struct s rets;
24151 \newline
24152 \SpecialChar ~
24153 \SpecialChar ~
24154 \SpecialChar ~
24155 \SpecialChar ~
24156 ...
24157
24158 \newline
24159 \SpecialChar ~
24160 \SpecialChar ~
24161 \SpecialChar ~
24162 \SpecialChar ~
24163 return rets;/* is invalid in SDCC although allowed in ANSI */
24164 \newline
24165 }
24166 \end_deeper
24167 \layout Itemize
24168
24169 'long long
24170 \begin_inset LatexCommand \index{long long (not supported)}
24171
24172 \end_inset
24173
24174 ' (64 bit integers
24175 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
24176
24177 \end_inset
24178
24179 ) not supported.
24180 \layout Itemize
24181
24182 'double
24183 \begin_inset LatexCommand \index{double (not supported)}
24184
24185 \end_inset
24186
24187 ' precision floating point
24188 \begin_inset LatexCommand \index{Floating point support}
24189
24190 \end_inset
24191
24192 not supported.
24193 \layout Itemize
24194
24195 No support for setjmp
24196 \begin_inset LatexCommand \index{setjmp (not supported)}
24197
24198 \end_inset
24199
24200  and longjmp
24201 \begin_inset LatexCommand \index{longjmp (not supported)}
24202
24203 \end_inset
24204
24205  (for now).
24206 \layout Itemize
24207
24208 Old K&R style
24209 \begin_inset LatexCommand \index{K\&R style}
24210
24211 \end_inset
24212
24213  function declarations are NOT allowed.
24214 \begin_deeper
24215 \layout Verse
24216
24217
24218 \family typewriter
24219 foo(i,j) /* this old style of function declarations */
24220 \newline
24221 int i,j; /* are valid in ANSI but not valid in SDCC */
24222 \newline
24223 {
24224 \newline
24225 \SpecialChar ~
24226 \SpecialChar ~
24227 \SpecialChar ~
24228 \SpecialChar ~
24229 ...
24230
24231 \newline
24232 }
24233 \end_deeper
24234 \layout Section
24235
24236 Cyclomatic Complexity
24237 \begin_inset LatexCommand \index{Cyclomatic complexity}
24238
24239 \end_inset
24240
24241
24242 \layout Standard
24243
24244 Cyclomatic complexity of a function is defined as the number of independent
24245  paths the program can take during execution of the function.
24246  This is an important number since it defines the number test cases you
24247  have to generate to validate the function.
24248  The accepted industry standard for complexity number is 10, if the cyclomatic
24249  complexity reported by SDCC exceeds 10 you should think about simplification
24250  of the function logic.
24251  Note that the complexity level is not related to the number of lines of
24252  code in a function.
24253  Large functions can have low complexity, and small functions can have large
24254  complexity levels.
24255
24256 \newline
24257
24258 \newline
24259 SDCC uses the following formula to compute the complexity:
24260 \newline
24261
24262 \layout Standard
24263
24264 complexity = (number of edges in control flow graph) - (number of nodes
24265  in control flow graph) + 2;
24266 \newline
24267
24268 \newline
24269 Having said that the industry standard is 10, you should be aware that in
24270  some cases it be may unavoidable to have a complexity level of less than
24271  10.
24272  For example if you have switch statement with more than 10 case labels,
24273  each case label adds one to the complexity level.
24274  The complexity level is by no means an absolute measure of the algorithmic
24275  complexity of the function, it does however provide a good starting point
24276  for which functions you might look at for further optimization.
24277 \layout Section
24278
24279 Retargetting for other Processors
24280 \layout Standard
24281
24282 The issues for retargetting the compiler are far too numerous to be covered
24283  by this document.
24284  What follows is a brief description of each of the seven phases of the
24285  compiler and its MCU dependency.
24286 \layout Itemize
24287
24288 Parsing the source and building the annotated parse tree.
24289  This phase is largely MCU independent (except for the language extensions).
24290  Syntax & semantic checks are also done in this phase, along with some initial
24291  optimizations like back patching labels and the pattern matching optimizations
24292  like bit-rotation etc.
24293 \layout Itemize
24294
24295 The second phase involves generating an intermediate code which can be easy
24296  manipulated during the later phases.
24297  This phase is entirely MCU independent.
24298  The intermediate code generation assumes the target machine has unlimited
24299  number of registers, and designates them with the name iTemp.
24300  The compiler can be made to dump a human readable form of the code generated
24301  by using the -
24302 \begin_inset ERT
24303 status Collapsed
24304
24305 \layout Standard
24306
24307 \backslash
24308 /
24309 \end_inset
24310
24311 -dumpraw option.
24312 \layout Itemize
24313
24314 This phase does the bulk of the standard optimizations and is also MCU independe
24315 nt.
24316  This phase can be broken down into several sub-phases:
24317 \newline
24318
24319 \newline
24320 Break down intermediate code (iCode) into basic blocks.
24321 \newline
24322 Do control flow & data flow analysis on the basic blocks.
24323 \newline
24324 Do local common subexpression elimination, then global subexpression elimination
24325 \newline
24326 Dead code elimination
24327 \newline
24328 Loop optimizations
24329 \newline
24330 If loop optimizations caused any changes then do 'global subexpression eliminati
24331 on' and 'dead code elimination' again.
24332 \layout Itemize
24333
24334 This phase determines the live-ranges; by live range I mean those iTemp
24335  variables defined by the compiler that still survive after all the optimization
24336 s.
24337  Live range analysis
24338 \begin_inset LatexCommand \index{Live range analysis}
24339
24340 \end_inset
24341
24342  is essential for register allocation, since these computation determines
24343  which of these iTemps will be assigned to registers, and for how long.
24344 \layout Itemize
24345
24346 Phase five is register allocation.
24347  There are two parts to this process.
24348 \newline
24349
24350 \newline
24351 The first part I call 'register packing' (for lack of a better term).
24352  In this case several MCU specific expression folding is done to reduce
24353  register pressure.
24354 \newline
24355
24356 \newline
24357 The second part is more MCU independent and deals with allocating registers
24358  to the remaining live ranges.
24359  A lot of MCU specific code does creep into this phase because of the limited
24360  number of index registers available in the 8051.
24361 \layout Itemize
24362
24363 The Code generation phase is (unhappily), entirely MCU dependent and very
24364  little (if any at all) of this code can be reused for other MCU.
24365  However the scheme for allocating a homogenized assembler operand for each
24366  iCode operand may be reused.
24367 \layout Itemize
24368
24369 As mentioned in the optimization section the peep-hole optimizer is rule
24370  based system, which can reprogrammed for other MCUs.
24371 \layout Chapter
24372
24373 Compiler internals
24374 \begin_inset LatexCommand \index{Compiler internals}
24375
24376 \end_inset
24377
24378
24379 \layout Section
24380
24381 The anatomy of the compiler
24382 \begin_inset LatexCommand \label{sub:The-anatomy-of}
24383
24384 \end_inset
24385
24386
24387 \layout Standard
24388
24389
24390 \shape italic
24391 This is an excerpt from an article published in Circuit Cellar Magazine
24392  in august 2000.
24393  It's a little outdated (the compiler is much more efficient now and user/develo
24394 per friendly), but pretty well exposes the guts of it all.
24395 \shape default
24396
24397 \newline
24398
24399 \newline
24400 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
24401  It is fairly easy to retarget for other 8-bit MCU.
24402  Here we take a look at some of the internals of the compiler.
24403
24404 \layout Paragraph*
24405
24406 Parsing
24407 \begin_inset LatexCommand \index{Parsing}
24408
24409 \end_inset
24410
24411
24412 \layout Standard
24413
24414 Parsing the input source file and creating an AST (Annotated Syntax Tree
24415 \begin_inset LatexCommand \index{Annotated syntax tree}
24416
24417 \end_inset
24418
24419 ).
24420  This phase also involves propagating types (annotating each node of the
24421  parse tree with type information) and semantic analysis.
24422  There are some MCU specific parsing rules.
24423  For example the storage classes, the extended storage classes are MCU specific
24424  while there may be a xdata storage class for 8051 there is no such storage
24425  class for z80 or Atmel AVR.
24426  SDCC allows MCU specific storage class extensions, i.e.
24427  xdata will be treated as a storage class specifier when parsing 8051 C
24428  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
24429  C code.
24430 \layout Paragraph*
24431
24432 Generating iCode
24433 \begin_inset LatexCommand \index{iCode}
24434
24435 \end_inset
24436
24437
24438 \layout Standard
24439
24440 Intermediate code generation.
24441  In this phase the AST is broken down into three-operand form (iCode).
24442  These three operand forms are represented as doubly linked lists.
24443  ICode is the term given to the intermediate form generated by the compiler.
24444  ICode example section shows some examples of iCode generated for some simple
24445  C source functions.
24446 \layout Paragraph*
24447
24448 Optimizations
24449 \begin_inset LatexCommand \index{Optimizations}
24450
24451 \end_inset
24452
24453 .
24454 \layout Standard
24455
24456 Bulk of the target independent optimizations is performed in this phase.
24457  The optimizations include constant propagation, common sub-expression eliminati
24458 on, loop invariant code movement, strength reduction of loop induction variables
24459  and dead-code elimination.
24460 \layout Paragraph*
24461
24462 Live range analysis
24463 \begin_inset LatexCommand \index{Live range analysis}
24464
24465 \end_inset
24466
24467
24468 \layout Standard
24469
24470 During intermediate code generation phase, the compiler assumes the target
24471  machine has infinite number of registers and generates a lot of temporary
24472  variables.
24473  The live range computation determines the lifetime of each of these compiler-ge
24474 nerated temporaries.
24475  A picture speaks a thousand words.
24476  ICode example sections show the live range annotations for each of the
24477  operand.
24478  It is important to note here, each iCode is assigned a number in the order
24479  of its execution in the function.
24480  The live ranges are computed in terms of these numbers.
24481  The from number is the number of the iCode which first defines the operand
24482  and the to number signifies the iCode which uses this operand last.
24483 \layout Paragraph*
24484
24485 Register Allocation
24486 \begin_inset LatexCommand \index{Register allocation}
24487
24488 \end_inset
24489
24490
24491 \layout Standard
24492
24493 The register allocation determines the type and number of registers needed
24494  by each operand.
24495  In most MCUs only a few registers can be used for indirect addressing.
24496  In case of 8051 for example the registers R0 & R1 can be used to indirectly
24497  address the internal ram and DPTR to indirectly address the external ram.
24498  The compiler will try to allocate the appropriate register to pointer variables
24499  if it can.
24500  ICode example section shows the operands annotated with the registers assigned
24501  to them.
24502  The compiler will try to keep operands in registers as much as possible;
24503  there are several schemes the compiler uses to do achieve this.
24504  When the compiler runs out of registers the compiler will check to see
24505  if there are any live operands which is not used or defined in the current
24506  basic block being processed, if there are any found then it will push that
24507  operand and use the registers in this block, the operand will then be popped
24508  at the end of the basic block.
24509
24510 \layout Standard
24511
24512 There are other MCU specific considerations in this phase.
24513  Some MCUs have an accumulator; very short-lived operands could be assigned
24514  to the accumulator instead of a general-purpose register.
24515 \layout Paragraph*
24516
24517 Code generation
24518 \layout Standard
24519
24520 Figure II gives a table of iCode operations supported by the compiler.
24521  The code generation involves translating these operations into corresponding
24522  assembly code for the processor.
24523  This sounds overly simple but that is the essence of code generation.
24524  Some of the iCode operations are generated on a MCU specific manner for
24525  example, the z80 port does not use registers to pass parameters so the
24526  SEND and RECV iCode operations will not be generated, and it also does
24527  not support JUMPTABLES.
24528
24529 \newline
24530
24531 \series bold
24532 \shape italic
24533 \color red
24534 <Where is Figure II?>
24535 \layout Comment
24536
24537 In the original article Figure II was announced to be downloadable on
24538 \shape italic
24539 Circuit Cellar
24540 \shape default
24541 's web site.
24542  Unfortunately it never seemed to have shown up there, so: where is Figure
24543  II?
24544 \layout Paragraph*
24545
24546 ICode Example
24547 \begin_inset LatexCommand \index{iCode}
24548
24549 \end_inset
24550
24551
24552 \layout Standard
24553
24554 This section shows some details of iCode.
24555  The example C code does not do anything useful; it is used as an example
24556  to illustrate the intermediate code generated by the compiler.
24557 \layout Verse
24558
24559
24560 \family typewriter
24561 1.\SpecialChar ~
24562 xdata int * p;
24563 \newline
24564 2.\SpecialChar ~
24565 int gint;
24566 \newline
24567 3.\SpecialChar ~
24568 /* This function does nothing useful.
24569  It is used
24570 \newline
24571 4.\SpecialChar ~
24572 \SpecialChar ~
24573 \SpecialChar ~
24574 \SpecialChar ~
24575 for the purpose of explaining iCode */
24576 \newline
24577 5.\SpecialChar ~
24578 short function (data int *x)
24579 \newline
24580 6.\SpecialChar ~
24581 {
24582 \newline
24583 7.\SpecialChar ~
24584 \SpecialChar ~
24585 \SpecialChar ~
24586 short i=10; \SpecialChar ~
24587 \SpecialChar ~
24588 /* dead initialization eliminated */
24589 \newline
24590 8.\SpecialChar ~
24591 \SpecialChar ~
24592 \SpecialChar ~
24593 short sum=10; /* dead initialization eliminated */
24594 \newline
24595 9.\SpecialChar ~
24596 \SpecialChar ~
24597 \SpecialChar ~
24598 short mul;
24599 \newline
24600 10.\SpecialChar ~
24601 \SpecialChar ~
24602 int j ;
24603 \newline
24604 11.\SpecialChar ~
24605 \SpecialChar ~
24606 while (*x) *x++ = *p++;
24607 \newline
24608 12.\SpecialChar ~
24609 \SpecialChar ~
24610 \SpecialChar ~
24611 \SpecialChar ~
24612 sum = 0 ;
24613 \newline
24614 13.\SpecialChar ~
24615 \SpecialChar ~
24616 mul = 0;
24617 \newline
24618 14.\SpecialChar ~
24619 \SpecialChar ~
24620 /* compiler detects i,j to be induction variables */
24621 \newline
24622 15.\SpecialChar ~
24623 \SpecialChar ~
24624 for (i = 0, j = 10 ; i < 10 ; i++, j
24625 \family default
24626 -
24627 \begin_inset ERT
24628 status Collapsed
24629
24630 \layout Standard
24631
24632 \backslash
24633 /
24634 \end_inset
24635
24636 -
24637 \family typewriter
24638 ) {
24639 \newline
24640 16.\SpecialChar ~
24641 \SpecialChar ~
24642 \SpecialChar ~
24643 \SpecialChar ~
24644 sum += i;
24645 \newline
24646 17.\SpecialChar ~
24647 \SpecialChar ~
24648 \SpecialChar ~
24649 \SpecialChar ~
24650 mul += i * 3; \SpecialChar ~
24651 \SpecialChar ~
24652 /* this multiplication remains */
24653 \newline
24654 18.\SpecialChar ~
24655 \SpecialChar ~
24656 \SpecialChar ~
24657 \SpecialChar ~
24658 gint += j * 3;\SpecialChar ~
24659 \SpecialChar ~
24660 /* this multiplication changed to addition */
24661 \newline
24662 19.\SpecialChar ~
24663 \SpecialChar ~
24664 }
24665 \newline
24666 20.\SpecialChar ~
24667 \SpecialChar ~
24668 return sum+mul;
24669 \newline
24670 21.\SpecialChar ~
24671 }
24672 \layout Standard
24673
24674 In addition to the operands each iCode contains information about the filename
24675  and line it corresponds to in the source file.
24676  The first field in the listing should be interpreted as follows:
24677 \newline
24678
24679 \shape italic
24680 \size footnotesize
24681 Filename(linenumber: iCode Execution sequence number : ICode hash table
24682  key : loop depth of the iCode).
24683 \shape default
24684 \size default
24685
24686 \newline
24687 Then follows the human readable form of the ICode operation.
24688  Each operand of this triplet form can be of three basic types a) compiler
24689  generated temporary b) user defined variable c) a constant value.
24690  Note that local variables and parameters are replaced by compiler generated
24691  temporaries.
24692  Live ranges
24693 \begin_inset LatexCommand \index{Live range analysis}
24694
24695 \end_inset
24696
24697  are computed only for temporaries (i.e.
24698  live ranges are not computed for global variables).
24699  Registers
24700 \begin_inset LatexCommand \index{Register allocation}
24701
24702 \end_inset
24703
24704  are allocated for temporaries only.
24705  Operands are formatted in the following manner:
24706 \newline
24707
24708 \shape italic
24709 \size footnotesize
24710 Operand Name [lr live-from : live-to ] { type information } [ registers
24711  allocated ].
24712 \shape default
24713 \size default
24714
24715 \newline
24716 As mentioned earlier the live ranges are computed in terms of the execution
24717  sequence number of the iCodes, for example
24718 \newline
24719 the iTemp0 is live from (i.e.
24720  first defined in iCode with execution sequence number 3, and is last used
24721  in the iCode with sequence number 5).
24722  For induction variables such as iTemp21 the live range computation extends
24723  the lifetime from the start to the end of the loop.
24724 \newline
24725 The register allocator used the live range information to allocate registers,
24726  the same registers may be used for different temporaries if their live
24727  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
24728  iTemp17 since their live ranges do not overlap.
24729  In addition the allocator also takes into consideration the type and usage
24730  of a temporary, for example itemp6 is a pointer to near space and is used
24731  as to fetch data from (i.e.
24732  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
24733  Some short lived temporaries are allocated to special registers which have
24734  meaning to the code generator e.g.
24735  iTemp13 is allocated to a pseudo register CC which tells the back end that
24736  the temporary is used only for a conditional jump the code generation makes
24737  use of this information to optimize a compare and jump ICode.
24738 \newline
24739 There are several loop optimizations
24740 \begin_inset LatexCommand \index{Loop optimization}
24741
24742 \end_inset
24743
24744  performed by the compiler.
24745  It can detect induction variables iTemp21(i) and iTemp23(j).
24746  Also note the compiler does selective strength reduction
24747 \begin_inset LatexCommand \index{Strength reduction}
24748
24749 \end_inset
24750
24751 , i.e.
24752  the multiplication of an induction variable in line 18 (gint = j * 3) is
24753  changed to addition, a new temporary iTemp17 is allocated and assigned
24754  a initial value, a constant 3 is then added for each iteration of the loop.
24755  The compiler does not change the multiplication
24756 \begin_inset LatexCommand \index{Multiplication}
24757
24758 \end_inset
24759
24760  in line 17 however since the processor does support an 8 * 8 bit multiplication.
24761 \newline
24762 Note the dead code elimination
24763 \begin_inset LatexCommand \index{Dead-code elimination}
24764
24765 \end_inset
24766
24767  optimization eliminated the dead assignments in line 7 & 8 to I and sum
24768  respectively.
24769 \newline
24770
24771 \layout Standard
24772
24773
24774 \size footnotesize
24775 Sample.c (5:1:0:0) _entry($9) :
24776 \layout Standard
24777
24778
24779 \size footnotesize
24780 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
24781 \layout Standard
24782
24783
24784 \size footnotesize
24785 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
24786 \layout Standard
24787
24788
24789 \size footnotesize
24790 Sample.c(11:4:53:0) preHeaderLbl0($11) :
24791 \layout Standard
24792
24793
24794 \size footnotesize
24795 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
24796  * int}[r2]
24797 \layout Standard
24798
24799
24800 \size footnotesize
24801 Sample.c(11:6:5:1) _whilecontinue_0($1) :
24802 \layout Standard
24803
24804
24805 \size footnotesize
24806 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
24807  int}[r0]]
24808 \layout Standard
24809
24810
24811 \size footnotesize
24812 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
24813 \layout Standard
24814
24815
24816 \size footnotesize
24817 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
24818  * int}
24819 \layout Standard
24820
24821
24822 \size footnotesize
24823 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
24824  {short}
24825 \layout Standard
24826
24827
24828 \size footnotesize
24829 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
24830  * int}[DPTR]]
24831 \layout Standard
24832
24833
24834 \size footnotesize
24835 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
24836 }[r2 r3]
24837 \layout Standard
24838
24839
24840 \size footnotesize
24841 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
24842  * int}[r0] + 0x2 {short}
24843 \layout Standard
24844
24845
24846 \size footnotesize
24847 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
24848 \layout Standard
24849
24850
24851 \size footnotesize
24852 Sample.c(11:17:21:0)_whilebreak_0($3) :
24853 \layout Standard
24854
24855
24856 \size footnotesize
24857 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
24858 \layout Standard
24859
24860
24861 \size footnotesize
24862 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
24863 \layout Standard
24864
24865
24866 \size footnotesize
24867 Sample.c(15:20:54:0)preHeaderLbl1($13) :
24868 \layout Standard
24869
24870
24871 \size footnotesize
24872 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
24873 \layout Standard
24874
24875
24876 \size footnotesize
24877 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
24878 \layout Standard
24879
24880
24881 \size footnotesize
24882 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
24883 \layout Standard
24884
24885
24886 \size footnotesize
24887 Sample.c(15:24:26:1)_forcond_0($4) :
24888 \layout Standard
24889
24890
24891 \size footnotesize
24892 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
24893  < 0xa {short}
24894 \layout Standard
24895
24896
24897 \size footnotesize
24898 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
24899 \layout Standard
24900
24901
24902 \size footnotesize
24903 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
24904  + ITemp21 [lr21:38]{short}[r4]
24905 \layout Standard
24906
24907
24908 \size footnotesize
24909 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
24910  * 0x3 {short}
24911 \layout Standard
24912
24913
24914 \size footnotesize
24915 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
24916  + iTemp15 [lr29:30]{short}[r1]
24917 \layout Standard
24918
24919
24920 \size footnotesize
24921 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
24922  r0]- 0x3 {short}
24923 \layout Standard
24924
24925
24926 \size footnotesize
24927 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
24928 int}[r7 r0]
24929 \layout Standard
24930
24931
24932 \size footnotesize
24933 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
24934  + 0x1 {short}
24935 \layout Standard
24936
24937
24938 \size footnotesize
24939 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
24940  r6]- 0x1 {short}
24941 \layout Standard
24942
24943
24944 \size footnotesize
24945 Sample.c(19:38:47:1) goto _forcond_0($4)
24946 \layout Standard
24947
24948
24949 \size footnotesize
24950 Sample.c(19:39:48:0)_forbreak_0($7) :
24951 \layout Standard
24952
24953
24954 \size footnotesize
24955 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
24956  + ITemp11 [lr19:40]{short}[r3]
24957 \layout Standard
24958
24959
24960 \size footnotesize
24961 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
24962 \layout Standard
24963
24964
24965 \size footnotesize
24966 Sample.c(20:42:51:0)_return($8) :
24967 \layout Standard
24968
24969
24970 \size footnotesize
24971 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
24972 \size default
24973
24974 \newline
24975
24976 \newline
24977 Finally the code generated for this function:
24978 \newline
24979
24980 \layout Standard
24981
24982
24983 \size footnotesize
24984 .area DSEG (DATA)
24985 \layout Standard
24986
24987
24988 \size footnotesize
24989 _p::
24990 \layout Standard
24991
24992
24993 \size footnotesize
24994 \SpecialChar ~
24995 \SpecialChar ~
24996 .ds 2
24997 \layout Standard
24998
24999
25000 \size footnotesize
25001 _gint::
25002 \layout Standard
25003
25004
25005 \size footnotesize
25006 \SpecialChar ~
25007 \SpecialChar ~
25008 .ds 2
25009 \layout Standard
25010
25011
25012 \size footnotesize
25013 ; sample.c 5
25014 \layout Standard
25015
25016
25017 \size footnotesize
25018 ; ----------------------------------------------
25019 \layout Standard
25020
25021
25022 \size footnotesize
25023 ; function function
25024 \layout Standard
25025
25026
25027 \size footnotesize
25028 ; ----------------------------------------------
25029 \layout Standard
25030
25031
25032 \size footnotesize
25033 _function:
25034 \layout Standard
25035
25036
25037 \size footnotesize
25038 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
25039 \layout Standard
25040
25041
25042 \size footnotesize
25043 \SpecialChar ~
25044 \SpecialChar ~
25045 mov r2,dpl
25046 \layout Standard
25047
25048
25049 \size footnotesize
25050 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
25051 \layout Standard
25052
25053
25054 \size footnotesize
25055 \SpecialChar ~
25056 \SpecialChar ~
25057 mov ar0,r2
25058 \layout Standard
25059
25060
25061 \size footnotesize
25062 ;_whilecontinue_0($1) :
25063 \layout Standard
25064
25065
25066 \size footnotesize
25067 00101$:
25068 \layout Standard
25069
25070
25071 \size footnotesize
25072 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
25073 \layout Standard
25074
25075
25076 \size footnotesize
25077 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
25078 \layout Standard
25079
25080
25081 \size footnotesize
25082 \SpecialChar ~
25083 \SpecialChar ~
25084 mov ar2,@r0
25085 \layout Standard
25086
25087
25088 \size footnotesize
25089 \SpecialChar ~
25090 \SpecialChar ~
25091 inc r0
25092 \layout Standard
25093
25094
25095 \size footnotesize
25096 \SpecialChar ~
25097 \SpecialChar ~
25098 mov ar3,@r0
25099 \layout Standard
25100
25101
25102 \size footnotesize
25103 \SpecialChar ~
25104 \SpecialChar ~
25105 dec r0
25106 \layout Standard
25107
25108
25109 \size footnotesize
25110 \SpecialChar ~
25111 \SpecialChar ~
25112 mov a,r2
25113 \layout Standard
25114
25115
25116 \size footnotesize
25117 \SpecialChar ~
25118 \SpecialChar ~
25119 orl a,r3
25120 \layout Standard
25121
25122
25123 \size footnotesize
25124 \SpecialChar ~
25125 \SpecialChar ~
25126 jz 00103$
25127 \layout Standard
25128
25129
25130 \size footnotesize
25131 00114$:
25132 \layout Standard
25133
25134
25135 \size footnotesize
25136 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
25137 \layout Standard
25138
25139
25140 \size footnotesize
25141 \SpecialChar ~
25142 \SpecialChar ~
25143 mov dpl,_p
25144 \layout Standard
25145
25146
25147 \size footnotesize
25148 \SpecialChar ~
25149 \SpecialChar ~
25150 mov dph,(_p + 1)
25151 \layout Standard
25152
25153
25154 \size footnotesize
25155 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
25156 \layout Standard
25157
25158
25159 \size footnotesize
25160 \SpecialChar ~
25161 \SpecialChar ~
25162 mov a,#0x02
25163 \layout Standard
25164
25165
25166 \size footnotesize
25167 \SpecialChar ~
25168 \SpecialChar ~
25169 add a,_p
25170 \layout Standard
25171
25172
25173 \size footnotesize
25174 \SpecialChar ~
25175 \SpecialChar ~
25176 mov _p,a
25177 \layout Standard
25178
25179
25180 \size footnotesize
25181 \SpecialChar ~
25182 \SpecialChar ~
25183 clr a
25184 \layout Standard
25185
25186
25187 \size footnotesize
25188 \SpecialChar ~
25189 \SpecialChar ~
25190 addc a,(_p + 1)
25191 \layout Standard
25192
25193
25194 \size footnotesize
25195 \SpecialChar ~
25196 \SpecialChar ~
25197 mov (_p + 1),a
25198 \layout Standard
25199
25200
25201 \size footnotesize
25202 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
25203 \layout Standard
25204
25205
25206 \size footnotesize
25207 \SpecialChar ~
25208 \SpecialChar ~
25209 movx a,@dptr
25210 \layout Standard
25211
25212
25213 \size footnotesize
25214 \SpecialChar ~
25215 \SpecialChar ~
25216 mov r2,a
25217 \layout Standard
25218
25219
25220 \size footnotesize
25221 \SpecialChar ~
25222 \SpecialChar ~
25223 inc dptr
25224 \layout Standard
25225
25226
25227 \size footnotesize
25228 \SpecialChar ~
25229 \SpecialChar ~
25230 movx a,@dptr
25231 \layout Standard
25232
25233
25234 \size footnotesize
25235 \SpecialChar ~
25236 \SpecialChar ~
25237 mov r3,a
25238 \layout Standard
25239
25240
25241 \size footnotesize
25242 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
25243 \layout Standard
25244
25245
25246 \size footnotesize
25247 \SpecialChar ~
25248 \SpecialChar ~
25249 mov @r0,ar2
25250 \layout Standard
25251
25252
25253 \size footnotesize
25254 \SpecialChar ~
25255 \SpecialChar ~
25256 inc r0
25257 \layout Standard
25258
25259
25260 \size footnotesize
25261 \SpecialChar ~
25262 \SpecialChar ~
25263 mov @r0,ar3
25264 \layout Standard
25265
25266
25267 \size footnotesize
25268 ; iTemp6 [lr5:16]{_near * int}[r0] =
25269 \layout Standard
25270
25271
25272 \size footnotesize
25273 ; iTemp6 [lr5:16]{_near * int}[r0] +
25274 \layout Standard
25275
25276
25277 \size footnotesize
25278 ; 0x2 {short}
25279 \layout Standard
25280
25281
25282 \size footnotesize
25283 \SpecialChar ~
25284 \SpecialChar ~
25285 inc r0
25286 \layout Standard
25287
25288
25289 \size footnotesize
25290 ; goto _whilecontinue_0($1)
25291 \layout Standard
25292
25293
25294 \size footnotesize
25295 \SpecialChar ~
25296 \SpecialChar ~
25297 sjmp 00101$
25298 \layout Standard
25299
25300
25301 \size footnotesize
25302 ; _whilebreak_0($3) :
25303 \layout Standard
25304
25305
25306 \size footnotesize
25307 00103$:
25308 \layout Standard
25309
25310
25311 \size footnotesize
25312 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
25313 \layout Standard
25314
25315
25316 \size footnotesize
25317 \SpecialChar ~
25318 \SpecialChar ~
25319 mov r2,#0x00
25320 \layout Standard
25321
25322
25323 \size footnotesize
25324 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
25325 \layout Standard
25326
25327
25328 \size footnotesize
25329 \SpecialChar ~
25330 \SpecialChar ~
25331 mov r3,#0x00
25332 \layout Standard
25333
25334
25335 \size footnotesize
25336 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
25337 \layout Standard
25338
25339
25340 \size footnotesize
25341 \SpecialChar ~
25342 \SpecialChar ~
25343 mov r4,#0x00
25344 \layout Standard
25345
25346
25347 \size footnotesize
25348 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
25349 \layout Standard
25350
25351
25352 \size footnotesize
25353 \SpecialChar ~
25354 \SpecialChar ~
25355 mov r5,#0x0A
25356 \layout Standard
25357
25358
25359 \size footnotesize
25360 \SpecialChar ~
25361 \SpecialChar ~
25362 mov r6,#0x00
25363 \layout Standard
25364
25365
25366 \size footnotesize
25367 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
25368 \layout Standard
25369
25370
25371 \size footnotesize
25372 \SpecialChar ~
25373 \SpecialChar ~
25374 mov r7,#0x1E
25375 \layout Standard
25376
25377
25378 \size footnotesize
25379 \SpecialChar ~
25380 \SpecialChar ~
25381 mov r0,#0x00
25382 \layout Standard
25383
25384
25385 \size footnotesize
25386 ; _forcond_0($4) :
25387 \layout Standard
25388
25389
25390 \size footnotesize
25391 00104$:
25392 \layout Standard
25393
25394
25395 \size footnotesize
25396 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
25397 \layout Standard
25398
25399
25400 \size footnotesize
25401 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
25402 \layout Standard
25403
25404
25405 \size footnotesize
25406 \SpecialChar ~
25407 \SpecialChar ~
25408 clr c
25409 \layout Standard
25410
25411
25412 \size footnotesize
25413 \SpecialChar ~
25414 \SpecialChar ~
25415 mov a,r4
25416 \layout Standard
25417
25418
25419 \size footnotesize
25420 \SpecialChar ~
25421 \SpecialChar ~
25422 xrl a,#0x80
25423 \layout Standard
25424
25425
25426 \size footnotesize
25427 \SpecialChar ~
25428 \SpecialChar ~
25429 subb a,#0x8a
25430 \layout Standard
25431
25432
25433 \size footnotesize
25434 \SpecialChar ~
25435 \SpecialChar ~
25436 jnc 00107$
25437 \layout Standard
25438
25439
25440 \size footnotesize
25441 00115$:
25442 \layout Standard
25443
25444
25445 \size footnotesize
25446 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
25447 \layout Standard
25448
25449
25450 \size footnotesize
25451 ; iTemp21 [lr21:38]{short}[r4]
25452 \layout Standard
25453
25454
25455 \size footnotesize
25456 \SpecialChar ~
25457 \SpecialChar ~
25458 mov a,r4
25459 \layout Standard
25460
25461
25462 \size footnotesize
25463 \SpecialChar ~
25464 \SpecialChar ~
25465 add a,r2
25466 \layout Standard
25467
25468
25469 \size footnotesize
25470 \SpecialChar ~
25471 \SpecialChar ~
25472 mov r2,a
25473 \layout Standard
25474
25475
25476 \size footnotesize
25477 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
25478 \layout Standard
25479
25480
25481 \size footnotesize
25482 \SpecialChar ~
25483 \SpecialChar ~
25484 mov b,#0x03
25485 \layout Standard
25486
25487
25488 \size footnotesize
25489 \SpecialChar ~
25490 \SpecialChar ~
25491 mov a,r4
25492 \layout Standard
25493
25494
25495 \size footnotesize
25496 \SpecialChar ~
25497 \SpecialChar ~
25498 mul ab
25499 \layout Standard
25500
25501
25502 \size footnotesize
25503 \SpecialChar ~
25504 \SpecialChar ~
25505 mov r1,a
25506 \layout Standard
25507
25508
25509 \size footnotesize
25510 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
25511 \layout Standard
25512
25513
25514 \size footnotesize
25515 ; iTemp15 [lr29:30]{short}[r1]
25516 \layout Standard
25517
25518
25519 \size footnotesize
25520 \SpecialChar ~
25521 \SpecialChar ~
25522 add a,r3
25523 \layout Standard
25524
25525
25526 \size footnotesize
25527 \SpecialChar ~
25528 \SpecialChar ~
25529 mov r3,a
25530 \layout Standard
25531
25532
25533 \size footnotesize
25534 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
25535 \layout Standard
25536
25537
25538 \size footnotesize
25539 \SpecialChar ~
25540 \SpecialChar ~
25541 mov a,r7
25542 \layout Standard
25543
25544
25545 \size footnotesize
25546 \SpecialChar ~
25547 \SpecialChar ~
25548 add a,#0xfd
25549 \layout Standard
25550
25551
25552 \size footnotesize
25553 \SpecialChar ~
25554 \SpecialChar ~
25555 mov r7,a
25556 \layout Standard
25557
25558
25559 \size footnotesize
25560 \SpecialChar ~
25561 \SpecialChar ~
25562 mov a,r0
25563 \layout Standard
25564
25565
25566 \size footnotesize
25567 \SpecialChar ~
25568 \SpecialChar ~
25569 addc a,#0xff
25570 \layout Standard
25571
25572
25573 \size footnotesize
25574 \SpecialChar ~
25575 \SpecialChar ~
25576 mov r0,a
25577 \layout Standard
25578
25579
25580 \size footnotesize
25581 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
25582 \layout Standard
25583
25584
25585 \size footnotesize
25586 \SpecialChar ~
25587 \SpecialChar ~
25588 mov a,r7
25589 \layout Standard
25590
25591
25592 \size footnotesize
25593 \SpecialChar ~
25594 \SpecialChar ~
25595 add a,_gint
25596 \layout Standard
25597
25598
25599 \size footnotesize
25600 \SpecialChar ~
25601 \SpecialChar ~
25602 mov _gint,a
25603 \layout Standard
25604
25605
25606 \size footnotesize
25607 \SpecialChar ~
25608 \SpecialChar ~
25609 mov a,r0
25610 \layout Standard
25611
25612
25613 \size footnotesize
25614 \SpecialChar ~
25615 \SpecialChar ~
25616 addc a,(_gint + 1)
25617 \layout Standard
25618
25619
25620 \size footnotesize
25621 \SpecialChar ~
25622 \SpecialChar ~
25623 mov (_gint + 1),a
25624 \layout Standard
25625
25626
25627 \size footnotesize
25628 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
25629 \layout Standard
25630
25631
25632 \size footnotesize
25633 \SpecialChar ~
25634 \SpecialChar ~
25635 inc r4
25636 \layout Standard
25637
25638
25639 \size footnotesize
25640 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
25641 \layout Standard
25642
25643
25644 \size footnotesize
25645 \SpecialChar ~
25646 \SpecialChar ~
25647 dec r5
25648 \layout Standard
25649
25650
25651 \size footnotesize
25652 \SpecialChar ~
25653 \SpecialChar ~
25654 cjne r5,#0xff,00104$
25655 \layout Standard
25656
25657
25658 \size footnotesize
25659 \SpecialChar ~
25660 \SpecialChar ~
25661 dec r6
25662 \layout Standard
25663
25664
25665 \size footnotesize
25666 ; goto _forcond_0($4)
25667 \layout Standard
25668
25669
25670 \size footnotesize
25671 \SpecialChar ~
25672 \SpecialChar ~
25673 sjmp 00104$
25674 \layout Standard
25675
25676
25677 \size footnotesize
25678 ; _forbreak_0($7) :
25679 \layout Standard
25680
25681
25682 \size footnotesize
25683 00107$:
25684 \layout Standard
25685
25686
25687 \size footnotesize
25688 ; ret iTemp24 [lr40:41]{short}
25689 \layout Standard
25690
25691
25692 \size footnotesize
25693 \SpecialChar ~
25694 \SpecialChar ~
25695 mov a,r3
25696 \layout Standard
25697
25698
25699 \size footnotesize
25700 \SpecialChar ~
25701 \SpecialChar ~
25702 add a,r2
25703 \layout Standard
25704
25705
25706 \size footnotesize
25707 \SpecialChar ~
25708 \SpecialChar ~
25709 mov dpl,a
25710 \layout Standard
25711
25712
25713 \size footnotesize
25714 ; _return($8) :
25715 \layout Standard
25716
25717
25718 \size footnotesize
25719 00108$:
25720 \layout Standard
25721
25722
25723 \size footnotesize
25724 \SpecialChar ~
25725 \SpecialChar ~
25726 ret
25727 \newline
25728
25729 \layout Section
25730
25731 A few words about basic block successors, predecessors and dominators
25732 \layout Standard
25733
25734 Successors are basic blocks
25735 \begin_inset LatexCommand \index{Basic blocks}
25736
25737 \end_inset
25738
25739  that might execute after this basic block.
25740 \newline
25741 Predecessors are basic blocks that might execute before reaching this basic
25742  block.
25743 \newline
25744 Dominators are basic blocks that WILL execute before reaching this basic
25745  block.
25746 \newline
25747
25748 \layout Standard
25749
25750 [basic block 1]
25751 \layout Standard
25752
25753 if (something)
25754 \layout Standard
25755
25756 \SpecialChar ~
25757 \SpecialChar ~
25758 \SpecialChar ~
25759 \SpecialChar ~
25760 [basic block 2]
25761 \layout Standard
25762
25763 else
25764 \layout Standard
25765
25766 \SpecialChar ~
25767 \SpecialChar ~
25768 \SpecialChar ~
25769 \SpecialChar ~
25770 [basic block 3]
25771 \layout Standard
25772
25773 [basic block 4]
25774 \newline
25775
25776 \layout Standard
25777
25778 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
25779 \layout Standard
25780
25781 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
25782 \layout Standard
25783
25784 c) domVect of [BB4] = BB1 ...
25785  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
25786  was executed.
25787 \layout Chapter
25788
25789 Acknowledgments
25790 \layout Standard
25791
25792
25793 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
25794
25795 \end_inset
25796
25797
25798 \newline
25799
25800 \newline
25801
25802 \emph on
25803 Thanks to all the other volunteer developers who have helped with coding,
25804  testing, web-page creation, distribution sets, etc.
25805  You know who you are :-)
25806 \emph default
25807
25808 \newline
25809
25810 \layout Standard
25811
25812 This document was initially written by Sandeep Dutta
25813 \layout Standard
25814
25815 All product names mentioned herein may be trademarks
25816 \begin_inset LatexCommand \index{Trademarks}
25817
25818 \end_inset
25819
25820  of their respective companies.
25821
25822 \layout Section*
25823
25824 Alphabetical index
25825 \layout Standard
25826
25827 To avoid confusion, the installation and building options for SDCC itself
25828  (chapter 2) are not part of the index.
25829 \layout Standard
25830
25831
25832 \begin_inset LatexCommand \printindex{}
25833
25834 \end_inset
25835
25836
25837 \the_end