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 \usepackage[
   7   pdftitle={SDCC Compiler User Guide},
   8   pdfauthor={SDCC development team},
   9   pdfsubject={installation, user manual},
  10   pdfkeywords={8032, 8051, ansi, c, compiler, CPU, DS390,
  11                embedded, GPL, HC08, manual, mcs51, PIC, Z80},
  12   colorlinks=true,
  13   linkcolor=blue] {hyperref}
  14 %
  15 \sloppy
  16 \tolerance=500
  17 \emergencystretch=30pt
  18 %
  19 \date{}
  20 \end_preamble
  21 \language english
  22 \inputencoding default
  23 \fontscheme pslatex
  24 \graphics default
  25 \paperfontsize default
  26 \spacing single
  27 \papersize letterpaper
  28 \paperpackage a4
  29 \use_geometry 1
  30 \use_amsmath 0
  31 \use_natbib 0
  32 \use_numerical_citations 0
  33 \paperorientation portrait
  34 \leftmargin 30mm
  35 \topmargin 20mm
  36 \rightmargin 25mm
  37 \bottommargin 20mm
  38 \secnumdepth 3
  39 \tocdepth 3
  40 \paragraph_separation indent
  41 \defskip medskip
  42 \quotes_language swedish
  43 \quotes_times 2
  44 \papercolumns 1
  45 \papersides 1
  46 \paperpagestyle fancy
  47
  48 \layout Comment
  49
  50 Please note: double dashed longoptions (e.g.
  51  --version) are written this way: -
  52 \begin_inset ERT
  53 status Collapsed
  54
  55 \layout Standard
  56
  57 \backslash
  58 /
  59 \end_inset
  60
  61 -
  62 \layout Comment
  63
  64 Two resp.
  65  three consecutive dashes simply result in a long resp.
  66  extra long dash.
  67 \layout Comment
  68
  69 Architecture specific stuff (like memory models, code examples) should maybe
  70  later go
  71 \layout Comment
  72
  73 into seperate sections/chapters/appendices (it is hard to document PIC or
  74  Z80 in
  75 \layout Comment
  76
  77 a 8051 centered document) - for now simply add.
  78 \layout Title
  79
  80 SDCC Compiler User Guide
  81 \layout Date
  82
  83
  84 \size normal
  85 SDCC 2.4.0
  86 \size footnotesize
  87
  88 \newline
  89 $Date$
  90 \newline
  91 $Revision$
  92 \layout Comment
  93
  94 The above strings enclosed in $ are automatically updated by cvs
  95 \layout Standard
  96
  97
  98 \begin_inset LatexCommand \tableofcontents{}
  99
 100 \end_inset
 101
 102
 103 \layout Chapter
 104
 105 Introduction
 106 \layout Section
 107
 108 About SDCC
 109 \layout Standard
 110
 111
 112 \series bold
 113 SDCC
 114 \series default
 115  (
 116 \emph on
 117 S
 118 \emph default
 119 mall
 120 \emph on
 121 D
 122 \emph default
 123 evice
 124 \emph on
 125 C
 126 \emph default
 127
 128 \emph on
 129 C
 130 \emph default
 131 ompiler) is a Freeware, retargettable, optimizing ANSI-C compiler by
 132 \series bold
 133 Sandeep Dutta
 134 \series default
 135  designed for 8 bit Microprocessors.
 136  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 137  8051, 8052
 138 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 139
 140 \end_inset
 141
 142 , etc.), Dallas DS80C390 variants, Motorola HC08 and Zilog Z80 based MCUs.
 143  It can be retargetted for other microprocessors, support for Microchip
 144  PIC, Atmel AVR is under development.
 145  The entire source code for the compiler is distributed under GPL.
 146  SDCC uses ASXXXX & ASLINK, a Freeware, retargettable assembler & linker.
 147  SDCC has extensive language extensions suitable for utilizing various microcont
 148 rollers and underlying hardware effectively.
 149
 150 \newline
 151
 152 \newline
 153 In addition to the MCU specific optimizations SDCC also does a host of standard
 154  optimizations like:
 155 \layout Itemize
 156
 157 global sub expression elimination,
 158 \layout Itemize
 159
 160 loop optimizations (loop invariant, strength reduction of induction variables
 161  and loop reversing),
 162 \layout Itemize
 163
 164 constant folding & propagation,
 165 \layout Itemize
 166
 167 copy propagation,
 168 \layout Itemize
 169
 170 dead code elimination
 171 \layout Itemize
 172
 173 jump tables for
 174 \emph on
 175 switch
 176 \emph default
 177  statements.
 178 \layout Standard
 179
 180 For the back-end SDCC uses a global register allocation scheme which should
 181  be well suited for other 8 bit MCUs.
 182
 183 \newline
 184
 185 \newline
 186 The peep hole optimizer uses a rule based substitution mechanism which is
 187  MCU independent.
 188
 189 \newline
 190
 191 \newline
 192 Supported data-types are:
 193 \layout Itemize
 194
 195 char (8 bits, 1 byte),
 196 \layout Itemize
 197
 198 short and int (16 bits, 2 bytes),
 199 \layout Itemize
 200
 201 long (32 bit, 4 bytes)
 202 \layout Itemize
 203
 204 float (4 byte IEEE).
 205
 206 \layout Standard
 207
 208 The compiler also allows
 209 \emph on
 210 inline assembler code
 211 \emph default
 212  to be embedded anywhere in a function.
 213  In addition, routines developed in assembly can also be called.
 214 \newline
 215
 216 \newline
 217 SDCC also provides an option (-
 218 \begin_inset ERT
 219 status Collapsed
 220
 221 \layout Standard
 222
 223 \backslash
 224 /
 225 \end_inset
 226
 227 -cyclomatic) to report the relative complexity of a function.
 228  These functions can then be further optimized, or hand coded in assembly
 229  if needed.
 230
 231 \newline
 232
 233 \newline
 234 SDCC also comes with a companion source level debugger SDCDB, the debugger
 235  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 236
 237 \newline
 238
 239 \newline
 240 The latest version can be downloaded from
 241 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 242
 243 \end_inset
 244
 245 .
 246
 247 \series bold
 248
 249 \series default
 250 \emph on
 251 Please note: the compiler will probably always be some steps ahead of this
 252  documentation
 253 \series bold
 254 \emph default
 255
 256 \begin_inset LatexCommand \index{Status of documentation}
 257
 258 \end_inset
 259
 260
 261 \begin_inset Foot
 262 collapsed false
 263
 264 \layout Standard
 265
 266 Obviously this has pros and cons
 267 \end_inset
 268
 269 .
 270 \layout Section
 271
 272 Open Source
 273 \layout Standard
 274
 275 All packages used in this compiler system are
 276 \emph on
 277 opensource
 278 \emph default
 279  and
 280 \emph on
 281 freeware
 282 \emph default
 283 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 284  etc) is distributed with the package.
 285  This documentation is maintained using a freeware word processor (LyX).
 286 \newline
 287 This program is free software; you can redistribute it and/or modify it
 288  under the terms of the GNU General Public License
 289 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 290
 291 \end_inset
 292
 293  as published by the Free Software Foundation; either version 2, or (at
 294  your option) any later version.
 295  This program is distributed in the hope that it will be useful, but WITHOUT
 296  ANY WARRANTY; without even the implied warranty
 297 \begin_inset LatexCommand \index{warranty}
 298
 299 \end_inset
 300
 301  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 302  See the GNU General Public License for more details.
 303  You should have received a copy of the GNU General Public License along
 304  with this program; if not, write to the Free Software Foundation, 59 Temple
 305  Place - Suite 330, Boston, MA 02111-1307, USA.
 306  In other words, you are welcome to use, share and improve this program.
 307  You are forbidden to forbid anyone else to use, share and improve what
 308  you give them.
 309  Help stamp out software-hoarding!
 310 \layout Section
 311
 312 Typographic conventions
 313 \begin_inset LatexCommand \index{Typographic conventions}
 314
 315 \end_inset
 316
 317
 318 \layout Standard
 319
 320 Throughout this manual, we will use the following convention.
 321  Commands you have to type in are printed in
 322 \family sans
 323 \series bold
 324 "sans serif"
 325 \series default
 326 .
 327
 328 \family default
 329  Code samples are printed in
 330 \family typewriter
 331 typewriter font.
 332
 333 \family default
 334  Interesting items and new terms are printed in
 335 \emph on
 336 italic.
 337 \layout Section
 338
 339 Compatibility with previous versions
 340 \layout Standard
 341
 342 This version has numerous bug fixes compared with the previous version.
 343  But we also introduced some incompatibilities with older versions.
 344  Not just for the fun of it, but to make the compiler more stable, efficient
 345  and ANSI compliant
 346 \begin_inset LatexCommand \index{ANSI-compliance}
 347
 348 \end_inset
 349
 350  (see section
 351 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 352
 353 \end_inset
 354
 355  for ANSI-Compliance).
 356
 357 \newline
 358
 359 \layout Itemize
 360
 361 short is now equivalent to int (16 bits), it used to be equivalent to char
 362  (8 bits) which is not ANSI compliant
 363 \layout Itemize
 364
 365 the default directory for gcc-builds where include, library and documentation
 366  files are stored is now in /usr/local/share
 367 \layout Itemize
 368
 369 char type parameters to vararg functions are casted to int unless explicitly
 370  casted, e.g.:
 371 \newline
 372
 373 \family typewriter
 374 \SpecialChar ~
 375 \SpecialChar ~
 376 char a=3;
 377 \newline
 378 \SpecialChar ~
 379 \SpecialChar ~
 380 printf ("%d %c
 381 \backslash
 382 n", a, (char)a);
 383 \family default
 384
 385 \newline
 386  will push a as an int and as a char resp.
 387 \layout Itemize
 388
 389 option -
 390 \begin_inset ERT
 391 status Collapsed
 392
 393 \layout Standard
 394
 395 \backslash
 396 /
 397 \end_inset
 398
 399 -regextend has been removed
 400 \layout Itemize
 401
 402 option -
 403 \begin_inset ERT
 404 status Collapsed
 405
 406 \layout Standard
 407
 408 \backslash
 409 /
 410 \end_inset
 411
 412 -noregparms has been removed
 413 \layout Itemize
 414
 415 option -
 416 \begin_inset ERT
 417 status Collapsed
 418
 419 \layout Standard
 420
 421 \backslash
 422 /
 423 \end_inset
 424
 425 -stack-after-data has been removed
 426 \layout Standard
 427
 428
 429 \emph on
 430 <pending: more incompatibilities?>
 431 \layout Section
 432
 433 System Requirements
 434 \layout Standard
 435
 436 What do you need before you start installation of SDCC? A computer, and
 437  a desire to compute.
 438  The preferred method of installation is to compile SDCC from source using
 439  GNU gcc and make.
 440  For Windows some pre-compiled binary distributions are available for your
 441  convenience.
 442  You should have some experience with command line tools and compiler use.
 443 \layout Section
 444
 445 Other Resources
 446 \layout Standard
 447
 448 The SDCC home page at
 449 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 450
 451 \end_inset
 452
 453  is a great place to find distribution sets.
 454  You can also find links to the user mailing lists that offer help or discuss
 455  SDCC with other SDCC users.
 456  Web links to other SDCC related sites can also be found here.
 457  This document can be found in the DOC directory of the source package as
 458  a text or HTML file.
 459  Some of the other tools (simulator and assembler) included with SDCC contain
 460  their own documentation and can be found in the source distribution.
 461  If you want the latest unreleased software, the complete source package
 462  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 463 \layout Section
 464
 465 Wishes for the future
 466 \layout Standard
 467
 468 There are (and always will be) some things that could be done.
 469  Here are some I can think of:
 470 \newline
 471
 472 \layout Standard
 473
 474
 475 \family typewriter
 476 char KernelFunction3(char p) at 0x340;
 477 \newline
 478
 479 \layout Standard
 480
 481
 482 \family typewriter
 483 code banking
 484 \begin_inset LatexCommand \index{code banking (not supported)}
 485
 486 \end_inset
 487
 488  support for mcs51
 489 \newline
 490
 491 \newline
 492
 493 \family default
 494 If you can think of some more, please see the section
 495 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 496
 497 \end_inset
 498
 499  about filing feature requests
 500 \begin_inset LatexCommand \index{Requesting features}
 501
 502 \end_inset
 503
 504
 505 \begin_inset LatexCommand \index{Feature request}
 506
 507 \end_inset
 508
 509 .
 510 \newline
 511
 512 \layout Chapter
 513
 514 Installing SDCC
 515 \begin_inset LatexCommand \index{Installation}
 516
 517 \end_inset
 518
 519
 520 \layout Standard
 521
 522 For most users it is sufficient to skip to either section
 523 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 524
 525 \end_inset
 526
 527  or section
 528 \begin_inset LatexCommand \ref{sub:Windows-Install}
 529
 530 \end_inset
 531
 532 .
 533  More detailled instructions follow below.
 534 \layout Section
 535
 536 Configure Options
 537 \begin_inset LatexCommand \index{Options SDCC configuration}
 538
 539 \end_inset
 540
 541
 542 \layout Standard
 543
 544 The install paths, search paths and other options are defined when running
 545  'configure'.
 546  The defaults can be overridden by:
 547 \layout List
 548 \labelwidthstring 00.00.0000
 549
 550 -
 551 \begin_inset ERT
 552 status Collapsed
 553
 554 \layout Standard
 555
 556 \backslash
 557 /
 558 \end_inset
 559
 560 -prefix see table below
 561 \layout List
 562 \labelwidthstring 00.00.0000
 563
 564 -
 565 \begin_inset ERT
 566 status Collapsed
 567
 568 \layout Standard
 569
 570 \backslash
 571 /
 572 \end_inset
 573
 574 -exec_prefix see table below
 575 \layout List
 576 \labelwidthstring 00.00.0000
 577
 578 -
 579 \begin_inset ERT
 580 status Collapsed
 581
 582 \layout Standard
 583
 584 \backslash
 585 /
 586 \end_inset
 587
 588 -bindir see table below
 589 \layout List
 590 \labelwidthstring 00.00.0000
 591
 592 -
 593 \begin_inset ERT
 594 status Collapsed
 595
 596 \layout Standard
 597
 598 \backslash
 599 /
 600 \end_inset
 601
 602 -datadir see table below
 603 \layout List
 604 \labelwidthstring 00.00.0000
 605
 606 docdir environment variable, see table below
 607 \layout List
 608 \labelwidthstring 00.00.0000
 609
 610 include_dir_suffix environment variable, see table below
 611 \layout List
 612 \labelwidthstring 00.00.0000
 613
 614 lib_dir_suffix environment variable, see table below
 615 \layout List
 616 \labelwidthstring 00.00.0000
 617
 618 sdccconf_h_dir_separator environment variable, either / or
 619 \backslash
 620
 621 \backslash
 622  makes sense here.
 623  This character will only be used in sdccconf.h; don't forget it's a C-header,
 624  therefore a double-backslash is needed there.
 625 \layout List
 626 \labelwidthstring 00.00.0000
 627
 628 -
 629 \begin_inset ERT
 630 status Collapsed
 631
 632 \layout Standard
 633
 634 \backslash
 635 /
 636 \end_inset
 637
 638 -disable-mcs51-port Excludes the Intel mcs51 port
 639 \layout List
 640 \labelwidthstring 00.00.0000
 641
 642 -
 643 \begin_inset ERT
 644 status Collapsed
 645
 646 \layout Standard
 647
 648 \backslash
 649 /
 650 \end_inset
 651
 652 -disable-gbz80-port Excludes the Gameboy gbz80 port
 653 \layout List
 654 \labelwidthstring 00.00.0000
 655
 656 -
 657 \begin_inset ERT
 658 status Collapsed
 659
 660 \layout Standard
 661
 662 \backslash
 663 /
 664 \end_inset
 665
 666 -disable-z80-port Excludes the z80 port
 667 \layout List
 668 \labelwidthstring 00.00.0000
 669
 670 -
 671 \begin_inset ERT
 672 status Collapsed
 673
 674 \layout Standard
 675
 676 \backslash
 677 /
 678 \end_inset
 679
 680 -disable-avr-port Excludes the AVR port
 681 \layout List
 682 \labelwidthstring 00.00.0000
 683
 684 -
 685 \begin_inset ERT
 686 status Collapsed
 687
 688 \layout Standard
 689
 690 \backslash
 691 /
 692 \end_inset
 693
 694 -disable-ds390-port Excludes the DS390 port
 695 \layout List
 696 \labelwidthstring 00.00.0000
 697
 698 -
 699 \begin_inset ERT
 700 status Collapsed
 701
 702 \layout Standard
 703
 704 \backslash
 705 /
 706 \end_inset
 707
 708 -disable-hc08-port Excludes the HC08 port
 709 \layout List
 710 \labelwidthstring 00.00.0000
 711
 712 -
 713 \begin_inset ERT
 714 status Collapsed
 715
 716 \layout Standard
 717
 718 \backslash
 719 /
 720 \end_inset
 721
 722 -disable-pic-port Excludes the PIC port
 723 \layout List
 724 \labelwidthstring 00.00.0000
 725
 726 -
 727 \begin_inset ERT
 728 status Collapsed
 729
 730 \layout Standard
 731
 732 \backslash
 733 /
 734 \end_inset
 735
 736 -disable-xa51-port Excludes the XA51 port
 737 \layout List
 738 \labelwidthstring 00.00.0000
 739
 740 -
 741 \begin_inset ERT
 742 status Collapsed
 743
 744 \layout Standard
 745
 746 \backslash
 747 /
 748 \end_inset
 749
 750 -disable-ucsim Disables configuring and building of ucsim
 751 \layout List
 752 \labelwidthstring 00.00.0000
 753
 754 -
 755 \begin_inset ERT
 756 status Collapsed
 757
 758 \layout Standard
 759
 760 \backslash
 761 /
 762 \end_inset
 763
 764 -disable-device-lib-build Disables automatically building device libraries
 765 \layout List
 766 \labelwidthstring 00.00.0000
 767
 768 -
 769 \begin_inset ERT
 770 status Collapsed
 771
 772 \layout Standard
 773
 774 \backslash
 775 /
 776 \end_inset
 777
 778 -disable-packihx Disables building packihx
 779 \layout List
 780 \labelwidthstring 00.00.0000
 781
 782 -
 783 \begin_inset ERT
 784 status Collapsed
 785
 786 \layout Standard
 787
 788 \backslash
 789 /
 790 \end_inset
 791
 792 -enable-libgc Use the Bohem memory allocator.
 793  Lower runtime footprint.
 794 \layout Standard
 795
 796 Furthermore the environment variables CC, CFLAGS, ...
 797  the tools and their arguments can be influenced.
 798  Please see `configure -
 799 \begin_inset ERT
 800 status Collapsed
 801
 802 \layout Standard
 803
 804 \backslash
 805 /
 806 \end_inset
 807
 808 -help` and the man/info pages of `configure` for details.
 809 \newline
 810
 811 \newline
 812 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 813  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 814 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 815  At the moment it's not possible to change the default settings (it was
 816  simply never required).
 817 \newline
 818
 819 \newline
 820 These configure options are compiled into the binaries, and can only be
 821  changed by rerunning 'configure' and recompiling SDCC.
 822  The configure options are written in
 823 \emph on
 824 italics
 825 \emph default
 826  to distinguish them from run time environment variables (see section search
 827  paths).
 828 \newline
 829
 830 \newline
 831 The settings for
 832 \begin_inset Quotes sld
 833 \end_inset
 834
 835 Win32 builds
 836 \begin_inset Quotes srd
 837 \end_inset
 838
 839  are used by the SDCC team to build the official Win32 binaries.
 840  The SDCC team uses Mingw32 to build the official Windows binaries, because
 841  it's
 842 \layout Enumerate
 843
 844 open source,
 845 \layout Enumerate
 846
 847 a gcc compiler and last but not least
 848 \layout Enumerate
 849
 850 the binaries can be built by cross compiling on Sourceforge's compile farm.
 851 \layout Standard
 852
 853 See the examples, how to pass the Win32 settings to 'configure'.
 854  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 855  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 856  for Win32.
 857 \newline
 858
 859 \newline
 860 These defaults are:
 861 \newline
 862
 863 \layout Standard
 864 \align center
 865
 866 \begin_inset  Tabular
 867 <lyxtabular version="3" rows="8" columns="3">
 868 <features>
 869 <column alignment="block" valignment="top" leftline="true" width="0in">
 870 <column alignment="block" valignment="top" leftline="true" width="0in">
 871 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 872 <row topline="true" bottomline="true">
 873 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 874 \begin_inset Text
 875
 876 \layout Standard
 877
 878 Variable
 879 \end_inset
 880 </cell>
 881 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 882 \begin_inset Text
 883
 884 \layout Standard
 885
 886 default
 887 \end_inset
 888 </cell>
 889 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 890 \begin_inset Text
 891
 892 \layout Standard
 893
 894 Win32 builds
 895 \end_inset
 896 </cell>
 897 </row>
 898 <row topline="true">
 899 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 900 \begin_inset Text
 901
 902 \layout Standard
 903
 904
 905 \emph on
 906 PREFIX
 907 \end_inset
 908 </cell>
 909 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 910 \begin_inset Text
 911
 912 \layout Standard
 913
 914 /usr/local
 915 \end_inset
 916 </cell>
 917 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 918 \begin_inset Text
 919
 920 \layout Standard
 921
 922
 923 \backslash
 924 sdcc
 925 \end_inset
 926 </cell>
 927 </row>
 928 <row topline="true">
 929 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 930 \begin_inset Text
 931
 932 \layout Standard
 933
 934
 935 \emph on
 936 EXEC_PREFIX
 937 \end_inset
 938 </cell>
 939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 940 \begin_inset Text
 941
 942 \layout Standard
 943
 944
 945 \emph on
 946 $PREFIX
 947 \end_inset
 948 </cell>
 949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 950 \begin_inset Text
 951
 952 \layout Standard
 953
 954
 955 \emph on
 956 $PREFIX
 957 \end_inset
 958 </cell>
 959 </row>
 960 <row topline="true">
 961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 962 \begin_inset Text
 963
 964 \layout Standard
 965
 966
 967 \emph on
 968 BINDIR
 969 \end_inset
 970 </cell>
 971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 972 \begin_inset Text
 973
 974 \layout Standard
 975
 976
 977 \emph on
 978 $EXECPREFIX
 979 \emph default
 980 /bin
 981 \end_inset
 982 </cell>
 983 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 984 \begin_inset Text
 985
 986 \layout Standard
 987
 988
 989 \emph on
 990 $EXECPREFIX
 991 \emph default
 992
 993 \backslash
 994 bin
 995 \end_inset
 996 </cell>
 997 </row>
 998 <row topline="true">
 999 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1000 \begin_inset Text
1001
1002 \layout Standard
1003
1004
1005 \emph on
1006 DATADIR
1007 \end_inset
1008 </cell>
1009 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1010 \begin_inset Text
1011
1012 \layout Standard
1013
1014
1015 \emph on
1016 $PREFIX
1017 \emph default
1018 /share
1019 \end_inset
1020 </cell>
1021 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1022 \begin_inset Text
1023
1024 \layout Standard
1025
1026
1027 \emph on
1028 $PREFIX
1029 \end_inset
1030 </cell>
1031 </row>
1032 <row topline="true">
1033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1034 \begin_inset Text
1035
1036 \layout Standard
1037
1038
1039 \emph on
1040 DOCDIR
1041 \end_inset
1042 </cell>
1043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1044 \begin_inset Text
1045
1046 \layout Standard
1047
1048
1049 \emph on
1050 $DATADIR
1051 \emph default
1052 /sdcc/doc
1053 \end_inset
1054 </cell>
1055 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1056 \begin_inset Text
1057
1058 \layout Standard
1059
1060
1061 \emph on
1062 $DATADIR
1063 \emph default
1064
1065 \backslash
1066 doc
1067 \end_inset
1068 </cell>
1069 </row>
1070 <row topline="true">
1071 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1072 \begin_inset Text
1073
1074 \layout Standard
1075
1076
1077 \emph on
1078 INCLUDE_DIR_SUFFIX
1079 \end_inset
1080 </cell>
1081 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1082 \begin_inset Text
1083
1084 \layout Standard
1085
1086 sdcc/include
1087 \end_inset
1088 </cell>
1089 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1090 \begin_inset Text
1091
1092 \layout Standard
1093
1094 include
1095 \end_inset
1096 </cell>
1097 </row>
1098 <row topline="true" bottomline="true">
1099 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1100 \begin_inset Text
1101
1102 \layout Standard
1103
1104
1105 \emph on
1106 LIB_DIR_SUFFIX
1107 \end_inset
1108 </cell>
1109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1110 \begin_inset Text
1111
1112 \layout Standard
1113
1114 sdcc/lib
1115 \end_inset
1116 </cell>
1117 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1118 \begin_inset Text
1119
1120 \layout Standard
1121
1122 lib
1123 \end_inset
1124 </cell>
1125 </row>
1126 </lyxtabular>
1127
1128 \end_inset
1129
1130
1131 \newline
1132
1133 \layout Standard
1134 \noindent
1135 'configure' also computes relative paths.
1136  This is needed for full relocatability of a binary package and to complete
1137  search paths (see section search paths below):
1138 \newline
1139
1140 \layout Standard
1141 \align center
1142
1143 \begin_inset  Tabular
1144 <lyxtabular version="3" rows="4" columns="3">
1145 <features>
1146 <column alignment="block" valignment="top" leftline="true" width="0in">
1147 <column alignment="block" valignment="top" leftline="true" width="0in">
1148 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1149 <row topline="true" bottomline="true">
1150 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1151 \begin_inset Text
1152
1153 \layout Standard
1154
1155 Variable (computed)
1156 \end_inset
1157 </cell>
1158 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1159 \begin_inset Text
1160
1161 \layout Standard
1162
1163 default
1164 \end_inset
1165 </cell>
1166 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1167 \begin_inset Text
1168
1169 \layout Standard
1170
1171 Win32 builds
1172 \end_inset
1173 </cell>
1174 </row>
1175 <row topline="true" bottomline="true">
1176 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1177 \begin_inset Text
1178
1179 \layout Standard
1180
1181
1182 \emph on
1183 BIN2DATA_DIR
1184 \end_inset
1185 </cell>
1186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1187 \begin_inset Text
1188
1189 \layout Standard
1190
1191 ../share
1192 \end_inset
1193 </cell>
1194 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1195 \begin_inset Text
1196
1197 \layout Standard
1198
1199 ..
1200 \end_inset
1201 </cell>
1202 </row>
1203 <row bottomline="true">
1204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1205 \begin_inset Text
1206
1207 \layout Standard
1208
1209
1210 \emph on
1211 PREFIX2BIN_DIR
1212 \end_inset
1213 </cell>
1214 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1215 \begin_inset Text
1216
1217 \layout Standard
1218
1219 bin
1220 \end_inset
1221 </cell>
1222 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1223 \begin_inset Text
1224
1225 \layout Standard
1226
1227 bin
1228 \end_inset
1229 </cell>
1230 </row>
1231 <row bottomline="true">
1232 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1233 \begin_inset Text
1234
1235 \layout Standard
1236
1237
1238 \emph on
1239 PREFIX2DATA_DIR
1240 \end_inset
1241 </cell>
1242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1243 \begin_inset Text
1244
1245 \layout Standard
1246
1247 share/sdcc
1248 \end_inset
1249 </cell>
1250 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1251 \begin_inset Text
1252
1253 \layout Standard
1254
1255 \end_inset
1256 </cell>
1257 </row>
1258 </lyxtabular>
1259
1260 \end_inset
1261
1262
1263 \newline
1264
1265 \layout Standard
1266 \noindent
1267 Examples:
1268 \layout LyX-Code
1269
1270 ./configure
1271 \newline
1272 ./configure -
1273 \begin_inset ERT
1274 status Collapsed
1275
1276 \layout Standard
1277
1278 \backslash
1279 /
1280 \end_inset
1281
1282 -prefix=
1283 \begin_inset Quotes srd
1284 \end_inset
1285
1286 /usr/bin
1287 \begin_inset Quotes srd
1288 \end_inset
1289
1290  -
1291 \begin_inset ERT
1292 status Collapsed
1293
1294 \layout Standard
1295
1296 \backslash
1297 /
1298 \end_inset
1299
1300 -datadir=
1301 \begin_inset Quotes srd
1302 \end_inset
1303
1304 /usr/share
1305 \begin_inset Quotes srd
1306 \end_inset
1307
1308
1309 \newline
1310 ./configure -
1311 \begin_inset ERT
1312 status Collapsed
1313
1314 \layout Standard
1315
1316 \backslash
1317 /
1318 \end_inset
1319
1320 -disable-avr-port -
1321 \begin_inset ERT
1322 status Collapsed
1323
1324 \layout Standard
1325
1326 \backslash
1327 /
1328 \end_inset
1329
1330 -disable-xa51-port
1331 \layout Standard
1332
1333 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1334 32'):
1335 \layout LyX-Code
1336
1337 ./configure
1338 \backslash
1339
1340 \newline
1341 CC=
1342 \begin_inset Quotes srd
1343 \end_inset
1344
1345 i586-mingw32msvc-gcc
1346 \begin_inset Quotes srd
1347 \end_inset
1348
1349  CXX=
1350 \begin_inset Quotes srd
1351 \end_inset
1352
1353 i586-mingw32msvc-g++
1354 \begin_inset Quotes srd
1355 \end_inset
1356
1357
1358 \backslash
1359
1360 \newline
1361 RANLIB=
1362 \begin_inset Quotes srd
1363 \end_inset
1364
1365 i586-mingw32msvc-ranlib
1366 \begin_inset Quotes srd
1367 \end_inset
1368
1369
1370 \backslash
1371
1372 \newline
1373 STRIP=
1374 \begin_inset Quotes srd
1375 \end_inset
1376
1377 i586-mingw32msvc-strip
1378 \begin_inset Quotes srd
1379 \end_inset
1380
1381
1382 \backslash
1383
1384 \newline
1385 -
1386 \begin_inset ERT
1387 status Collapsed
1388
1389 \layout Standard
1390
1391 \backslash
1392 /
1393 \end_inset
1394
1395 -prefix=
1396 \begin_inset Quotes srd
1397 \end_inset
1398
1399 /sdcc
1400 \begin_inset Quotes srd
1401 \end_inset
1402
1403
1404 \backslash
1405
1406 \newline
1407 -
1408 \begin_inset ERT
1409 status Collapsed
1410
1411 \layout Standard
1412
1413 \backslash
1414 /
1415 \end_inset
1416
1417 -datadir=
1418 \begin_inset Quotes srd
1419 \end_inset
1420
1421 /sdcc
1422 \begin_inset Quotes srd
1423 \end_inset
1424
1425
1426 \backslash
1427
1428 \newline
1429 docdir=
1430 \begin_inset Quotes srd
1431 \end_inset
1432
1433 /sdcc/doc
1434 \begin_inset Quotes srd
1435 \end_inset
1436
1437
1438 \backslash
1439
1440 \newline
1441 include_dir_suffix=
1442 \begin_inset Quotes srd
1443 \end_inset
1444
1445 include
1446 \begin_inset Quotes srd
1447 \end_inset
1448
1449
1450 \backslash
1451
1452 \newline
1453 lib_dir_suffix=
1454 \begin_inset Quotes srd
1455 \end_inset
1456
1457 lib
1458 \begin_inset Quotes srd
1459 \end_inset
1460
1461
1462 \backslash
1463
1464 \newline
1465 sdccconf_h_dir_separator=
1466 \begin_inset Quotes srd
1467 \end_inset
1468
1469
1470 \backslash
1471
1472 \backslash
1473
1474 \backslash
1475
1476 \backslash
1477
1478 \begin_inset Quotes srd
1479 \end_inset
1480
1481
1482 \backslash
1483
1484 \newline
1485 -
1486 \begin_inset ERT
1487 status Collapsed
1488
1489 \layout Standard
1490
1491 \backslash
1492 /
1493 \end_inset
1494
1495 -disable-device-lib-build
1496 \backslash
1497
1498 \newline
1499 -
1500 \begin_inset ERT
1501 status Collapsed
1502
1503 \layout Standard
1504
1505 \backslash
1506 /
1507 \end_inset
1508
1509 -disable-ucsim
1510 \backslash
1511
1512 \newline
1513 -
1514 \begin_inset ERT
1515 status Collapsed
1516
1517 \layout Standard
1518
1519 \backslash
1520 /
1521 \end_inset
1522
1523 -host=i586-mingw32msvc -
1524 \begin_inset ERT
1525 status Collapsed
1526
1527 \layout Standard
1528
1529 \backslash
1530 /
1531 \end_inset
1532
1533 -build=unknown-unknown-linux-gnu
1534 \layout Standard
1535
1536 To
1537 \begin_inset Quotes sld
1538 \end_inset
1539
1540 cross
1541 \begin_inset Quotes srd
1542 \end_inset
1543
1544 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1545 ):
1546 \layout LyX-Code
1547
1548 ./configure -C
1549 \backslash
1550
1551 \newline
1552 CFLAGS=
1553 \begin_inset Quotes srd
1554 \end_inset
1555
1556 -mno-cygwin -O2
1557 \begin_inset Quotes srd
1558 \end_inset
1559
1560
1561 \backslash
1562
1563 \newline
1564 LDFLAGS=
1565 \begin_inset Quotes srd
1566 \end_inset
1567
1568 -mno-cygwin
1569 \begin_inset Quotes srd
1570 \end_inset
1571
1572
1573 \backslash
1574
1575 \newline
1576 -
1577 \begin_inset ERT
1578 status Collapsed
1579
1580 \layout Standard
1581
1582 \backslash
1583 /
1584 \end_inset
1585
1586 -prefix=
1587 \begin_inset Quotes srd
1588 \end_inset
1589
1590 /sdcc
1591 \begin_inset Quotes srd
1592 \end_inset
1593
1594
1595 \backslash
1596
1597 \newline
1598 -
1599 \begin_inset ERT
1600 status Collapsed
1601
1602 \layout Standard
1603
1604 \backslash
1605 /
1606 \end_inset
1607
1608 -datadir=
1609 \begin_inset Quotes srd
1610 \end_inset
1611
1612 /sdcc
1613 \begin_inset Quotes srd
1614 \end_inset
1615
1616
1617 \backslash
1618
1619 \newline
1620 docdir=
1621 \begin_inset Quotes srd
1622 \end_inset
1623
1624 /sdcc/doc
1625 \begin_inset Quotes srd
1626 \end_inset
1627
1628
1629 \backslash
1630
1631 \newline
1632 include_dir_suffix=
1633 \begin_inset Quotes srd
1634 \end_inset
1635
1636 include
1637 \begin_inset Quotes srd
1638 \end_inset
1639
1640
1641 \backslash
1642
1643 \newline
1644 lib_dir_suffix=
1645 \begin_inset Quotes srd
1646 \end_inset
1647
1648 lib
1649 \begin_inset Quotes srd
1650 \end_inset
1651
1652
1653 \backslash
1654
1655 \newline
1656 sdccconf_h_dir_separator=
1657 \begin_inset Quotes srd
1658 \end_inset
1659
1660
1661 \backslash
1662
1663 \backslash
1664
1665 \backslash
1666
1667 \backslash
1668
1669 \begin_inset Quotes srd
1670 \end_inset
1671
1672
1673 \backslash
1674
1675 \newline
1676 -
1677 \begin_inset ERT
1678 status Collapsed
1679
1680 \layout Standard
1681
1682 \backslash
1683 /
1684 \end_inset
1685
1686 -disable-ucsim
1687 \layout Standard
1688
1689 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1690  The option '-
1691 \begin_inset ERT
1692 status Collapsed
1693
1694 \layout Standard
1695
1696 \backslash
1697 /
1698 \end_inset
1699
1700 -C' turns on caching, which gives a little bit extra speed.
1701  However if options are changed, it can be necessary to delete the config.cache
1702  file.
1703 \layout Section
1704
1705 Install paths
1706 \begin_inset LatexCommand \label{sub:Install-paths}
1707
1708 \end_inset
1709
1710
1711 \begin_inset LatexCommand \index{Install paths}
1712
1713 \end_inset
1714
1715
1716 \layout Standard
1717 \added_space_top medskip \align center
1718
1719 \begin_inset  Tabular
1720 <lyxtabular version="3" rows="5" columns="4">
1721 <features>
1722 <column alignment="center" valignment="top" leftline="true" width="0(null)">
1723 <column alignment="center" valignment="top" leftline="true" width="0(null)">
1724 <column alignment="center" valignment="top" leftline="true" width="0(null)">
1725 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
1726 <row topline="true" bottomline="true">
1727 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1728 \begin_inset Text
1729
1730 \layout Standard
1731
1732
1733 \series bold
1734 Description
1735 \end_inset
1736 </cell>
1737 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1738 \begin_inset Text
1739
1740 \layout Standard
1741
1742
1743 \series bold
1744 Path
1745 \end_inset
1746 </cell>
1747 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1748 \begin_inset Text
1749
1750 \layout Standard
1751
1752
1753 \series bold
1754 Default
1755 \end_inset
1756 </cell>
1757 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1758 \begin_inset Text
1759
1760 \layout Standard
1761
1762
1763 \series bold
1764 Win32 builds
1765 \end_inset
1766 </cell>
1767 </row>
1768 <row topline="true">
1769 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1770 \begin_inset Text
1771
1772 \layout Standard
1773
1774 Binary files*
1775 \end_inset
1776 </cell>
1777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1778 \begin_inset Text
1779
1780 \layout Standard
1781
1782
1783 \emph on
1784 $EXEC_PREFIX
1785 \end_inset
1786 </cell>
1787 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1788 \begin_inset Text
1789
1790 \layout Standard
1791
1792 /usr/local/bin
1793 \end_inset
1794 </cell>
1795 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1796 \begin_inset Text
1797
1798 \layout Standard
1799
1800
1801 \backslash
1802 sdcc
1803 \backslash
1804 bin
1805 \end_inset
1806 </cell>
1807 </row>
1808 <row topline="true">
1809 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1810 \begin_inset Text
1811
1812 \layout Standard
1813
1814 Include files
1815 \end_inset
1816 </cell>
1817 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1818 \begin_inset Text
1819
1820 \layout Standard
1821
1822
1823 \emph on
1824 $DATADIR/ $INCLUDE_DIR_SUFFIX
1825 \end_inset
1826 </cell>
1827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1828 \begin_inset Text
1829
1830 \layout Standard
1831
1832 /usr/local/share/sdcc/include
1833 \end_inset
1834 </cell>
1835 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1836 \begin_inset Text
1837
1838 \layout Standard
1839
1840
1841 \backslash
1842 sdcc
1843 \backslash
1844 include
1845 \end_inset
1846 </cell>
1847 </row>
1848 <row topline="true">
1849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1850 \begin_inset Text
1851
1852 \layout Standard
1853
1854 Library file**
1855 \end_inset
1856 </cell>
1857 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1858 \begin_inset Text
1859
1860 \layout Standard
1861
1862
1863 \emph on
1864 $DATADIR/$LIB_DIR_SUFFIX
1865 \end_inset
1866 </cell>
1867 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1868 \begin_inset Text
1869
1870 \layout Standard
1871
1872 /usr/local/share/sdcc/lib
1873 \end_inset
1874 </cell>
1875 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1876 \begin_inset Text
1877
1878 \layout Standard
1879
1880
1881 \backslash
1882 sdcc
1883 \backslash
1884 lib
1885 \end_inset
1886 </cell>
1887 </row>
1888 <row topline="true" bottomline="true">
1889 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1890 \begin_inset Text
1891
1892 \layout Standard
1893
1894 Documentation
1895 \end_inset
1896 </cell>
1897 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1898 \begin_inset Text
1899
1900 \layout Standard
1901
1902
1903 \emph on
1904 $DOCDIR
1905 \end_inset
1906 </cell>
1907 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1908 \begin_inset Text
1909
1910 \layout Standard
1911
1912 /usr/local/share/sdcc/doc
1913 \end_inset
1914 </cell>
1915 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1916 \begin_inset Text
1917
1918 \layout Standard
1919
1920
1921 \backslash
1922 sdcc
1923 \backslash
1924 doc
1925 \end_inset
1926 </cell>
1927 </row>
1928 </lyxtabular>
1929
1930 \end_inset
1931
1932
1933 \layout Verse
1934
1935
1936 \size footnotesize
1937 *compiler, preprocessor, assembler, and linker
1938 \newline
1939 **the
1940 \shape italic
1941 model
1942 \shape default
1943  is auto-appended by the compiler, e.g.
1944  small, large, z80, ds390 etc
1945 \layout Standard
1946 \noindent
1947 The install paths can still be changed during `make install` with e.g.:
1948 \layout LyX-Code
1949
1950 make install prefix=$(HOME)/local/sdcc
1951 \layout Standard
1952
1953 Of course this doesn't change the search paths compiled into the binaries.
1954 \layout Section
1955
1956 Search Paths
1957 \begin_inset LatexCommand \label{sub:Search-Paths}
1958
1959 \end_inset
1960
1961
1962 \begin_inset LatexCommand \index{Search path}
1963
1964 \end_inset
1965
1966
1967 \layout Standard
1968
1969 Some search paths or parts of them are determined by configure variables
1970  (in
1971 \emph on
1972 italics
1973 \emph default
1974 , see section above).
1975  Further search paths are determined by environment variables during runtime.
1976
1977 \newline
1978 The paths searched when running the compiler are as follows (the first catch
1979  wins):
1980 \newline
1981
1982 \newline
1983 1.
1984  Binary files (preprocessor, assembler and linker)
1985 \newline
1986
1987 \layout Standard
1988 \align center
1989
1990 \begin_inset  Tabular
1991 <lyxtabular version="3" rows="4" columns="3">
1992 <features>
1993 <column alignment="block" valignment="top" leftline="true" width="0in">
1994 <column alignment="block" valignment="top" leftline="true" width="0in">
1995 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1996 <row topline="true" bottomline="true">
1997 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1998 \begin_inset Text
1999
2000 \layout Standard
2001
2002 Search path
2003 \end_inset
2004 </cell>
2005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2006 \begin_inset Text
2007
2008 \layout Standard
2009
2010 default
2011 \end_inset
2012 </cell>
2013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2014 \begin_inset Text
2015
2016 \layout Standard
2017
2018 Win32 builds
2019 \end_inset
2020 </cell>
2021 </row>
2022 <row topline="true">
2023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2024 \begin_inset Text
2025
2026 \layout Standard
2027
2028 $SDCC_HOME/
2029 \emph on
2030 $PPREFIX2BIN_DIR
2031 \end_inset
2032 </cell>
2033 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2034 \begin_inset Text
2035
2036 \layout Standard
2037
2038 $SDCC_HOME/bin
2039 \end_inset
2040 </cell>
2041 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2042 \begin_inset Text
2043
2044 \layout Standard
2045
2046 $SDCC_HOME
2047 \backslash
2048 bin
2049 \end_inset
2050 </cell>
2051 </row>
2052 <row topline="true">
2053 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2054 \begin_inset Text
2055
2056 \layout Standard
2057
2058 Path of argv[0] (if available)
2059 \end_inset
2060 </cell>
2061 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2062 \begin_inset Text
2063
2064 \layout Standard
2065
2066 Path of argv[0]
2067 \end_inset
2068 </cell>
2069 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2070 \begin_inset Text
2071
2072 \layout Standard
2073
2074 Path of argv[0]
2075 \end_inset
2076 </cell>
2077 </row>
2078 <row topline="true" bottomline="true">
2079 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2080 \begin_inset Text
2081
2082 \layout Standard
2083
2084 $PATH
2085 \end_inset
2086 </cell>
2087 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2088 \begin_inset Text
2089
2090 \layout Standard
2091
2092 $PATH
2093 \end_inset
2094 </cell>
2095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2096 \begin_inset Text
2097
2098 \layout Standard
2099
2100 $PATH
2101 \end_inset
2102 </cell>
2103 </row>
2104 </lyxtabular>
2105
2106 \end_inset
2107
2108
2109 \newline
2110
2111 \layout Standard
2112 \noindent
2113 2.
2114  Include files
2115 \newline
2116
2117 \layout Standard
2118 \align center
2119
2120 \begin_inset  Tabular
2121 <lyxtabular version="3" rows="6" columns="3">
2122 <features>
2123 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2124 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2125 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2126 <row topline="true" bottomline="true">
2127 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2128 \begin_inset Text
2129
2130 \layout Standard
2131
2132 Search path
2133 \end_inset
2134 </cell>
2135 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2136 \begin_inset Text
2137
2138 \layout Standard
2139
2140 default
2141 \end_inset
2142 </cell>
2143 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2144 \begin_inset Text
2145
2146 \layout Standard
2147
2148 Win32 builds
2149 \end_inset
2150 </cell>
2151 </row>
2152 <row topline="true">
2153 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2154 \begin_inset Text
2155
2156 \layout Standard
2157
2158 -
2159 \begin_inset ERT
2160 status Collapsed
2161
2162 \layout Standard
2163
2164 \backslash
2165 /
2166 \end_inset
2167
2168 -I dir
2169 \end_inset
2170 </cell>
2171 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2172 \begin_inset Text
2173
2174 \layout Standard
2175
2176 -
2177 \begin_inset ERT
2178 status Collapsed
2179
2180 \layout Standard
2181
2182 \backslash
2183 /
2184 \end_inset
2185
2186 -I dir
2187 \end_inset
2188 </cell>
2189 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2190 \begin_inset Text
2191
2192 \layout Standard
2193
2194 -
2195 \begin_inset ERT
2196 status Collapsed
2197
2198 \layout Standard
2199
2200 \backslash
2201 /
2202 \end_inset
2203
2204 -I dir
2205 \end_inset
2206 </cell>
2207 </row>
2208 <row topline="true">
2209 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2210 \begin_inset Text
2211
2212 \layout Standard
2213
2214 $SDCC_INCLUDE
2215 \end_inset
2216 </cell>
2217 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2218 \begin_inset Text
2219
2220 \layout Standard
2221
2222 $SDCC_INCLUDE
2223 \end_inset
2224 </cell>
2225 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2226 \begin_inset Text
2227
2228 \layout Standard
2229
2230 $SDCC_INCLUDE
2231 \end_inset
2232 </cell>
2233 </row>
2234 <row topline="true">
2235 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2236 \begin_inset Text
2237
2238 \layout Standard
2239
2240 $SDCC_HOME/
2241 \newline
2242
2243 \emph on
2244 $PREFIX2DATA_DIR/
2245 \newline
2246 $INCLUDE_DIR_SUFFIX
2247 \end_inset
2248 </cell>
2249 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2250 \begin_inset Text
2251
2252 \layout Standard
2253
2254 $SDCC_ HOME/
2255 \newline
2256 share/sdcc/
2257 \newline
2258 include
2259 \end_inset
2260 </cell>
2261 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2262 \begin_inset Text
2263
2264 \layout Standard
2265
2266 $SDCC_HOME
2267 \backslash
2268 include
2269 \end_inset
2270 </cell>
2271 </row>
2272 <row topline="true">
2273 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2274 \begin_inset Text
2275
2276 \layout Standard
2277
2278 path(argv[0])/
2279 \newline
2280
2281 \emph on
2282 $BIN2DATADIR/
2283 \emph default
2284
2285 \newline
2286
2287 \emph on
2288 $INCLUDE_DIR_SUFFIX
2289 \end_inset
2290 </cell>
2291 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2292 \begin_inset Text
2293
2294 \layout Standard
2295
2296 path(argv[0])/
2297 \newline
2298 ../sdcc/include
2299 \newline
2300 \SpecialChar ~
2301 \SpecialChar ~
2302 \SpecialChar ~
2303 \SpecialChar ~
2304 \SpecialChar ~
2305 \SpecialChar ~
2306 \SpecialChar ~
2307 \SpecialChar ~
2308 \SpecialChar ~
2309 \SpecialChar ~
2310 \SpecialChar ~
2311 \SpecialChar ~
2312 \SpecialChar ~
2313 \SpecialChar ~
2314 \SpecialChar ~
2315 \SpecialChar ~
2316 \SpecialChar ~
2317 \SpecialChar ~
2318 \SpecialChar ~
2319 \SpecialChar ~
2320 \SpecialChar ~
2321 \SpecialChar ~
2322 \SpecialChar ~
2323 \SpecialChar ~
2324 \SpecialChar ~
2325 \SpecialChar ~
2326 \SpecialChar ~
2327 \SpecialChar ~
2328 \SpecialChar ~
2329 \SpecialChar ~
2330 \SpecialChar ~
2331 \SpecialChar ~
2332 \SpecialChar ~
2333 \SpecialChar ~
2334 \SpecialChar ~
2335 \SpecialChar ~
2336 \SpecialChar ~
2337 \SpecialChar ~
2338
2339 \end_inset
2340 </cell>
2341 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2342 \begin_inset Text
2343
2344 \layout Standard
2345
2346 path(argv[0])
2347 \backslash
2348 ..
2349 \backslash
2350 include
2351 \end_inset
2352 </cell>
2353 </row>
2354 <row topline="true" bottomline="true">
2355 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2356 \begin_inset Text
2357
2358 \layout Standard
2359
2360
2361 \emph on
2362 $DATADIR/
2363 \emph default
2364
2365 \newline
2366
2367 \emph on
2368 $INCLUDE_DIR_SUFFIX
2369 \end_inset
2370 </cell>
2371 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2372 \begin_inset Text
2373
2374 \layout Standard
2375
2376 /usr/local/share/sdcc/
2377 \newline
2378 include
2379 \end_inset
2380 </cell>
2381 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2382 \begin_inset Text
2383
2384 \layout Standard
2385
2386 (not on Win32)
2387 \end_inset
2388 </cell>
2389 </row>
2390 </lyxtabular>
2391
2392 \end_inset
2393
2394
2395 \newline
2396
2397 \layout Standard
2398 \noindent
2399 The option -
2400 \begin_inset ERT
2401 status Collapsed
2402
2403 \layout Standard
2404
2405 \backslash
2406 /
2407 \end_inset
2408
2409 -nostdinc disables the last two search paths.
2410 \newline
2411
2412 \newline
2413 3.
2414  Library files
2415 \newline
2416
2417 \layout Standard
2418
2419 With the exception of
2420 \begin_inset Quotes sld
2421 \end_inset
2422
2423 -
2424 \begin_inset ERT
2425 status Collapsed
2426
2427 \layout Standard
2428
2429 \backslash
2430 /
2431 \end_inset
2432
2433 -L dir
2434 \begin_inset Quotes srd
2435 \end_inset
2436
2437  the
2438 \shape italic
2439 model
2440 \shape default
2441  is auto-appended by the compiler (e.g.
2442  small, large, z80, ds390 etc.).
2443
2444 \newline
2445
2446 \layout Standard
2447 \align center
2448
2449 \begin_inset  Tabular
2450 <lyxtabular version="3" rows="6" columns="3">
2451 <features>
2452 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2453 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2454 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2455 <row topline="true" bottomline="true">
2456 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2457 \begin_inset Text
2458
2459 \layout Standard
2460
2461 Search path
2462 \end_inset
2463 </cell>
2464 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2465 \begin_inset Text
2466
2467 \layout Standard
2468
2469 default
2470 \end_inset
2471 </cell>
2472 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2473 \begin_inset Text
2474
2475 \layout Standard
2476
2477 Win32 builds
2478 \end_inset
2479 </cell>
2480 </row>
2481 <row topline="true">
2482 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2483 \begin_inset Text
2484
2485 \layout Standard
2486
2487 -
2488 \begin_inset ERT
2489 status Collapsed
2490
2491 \layout Standard
2492
2493 \backslash
2494 /
2495 \end_inset
2496
2497 -L dir
2498 \end_inset
2499 </cell>
2500 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2501 \begin_inset Text
2502
2503 \layout Standard
2504
2505 -
2506 \begin_inset ERT
2507 status Collapsed
2508
2509 \layout Standard
2510
2511 \backslash
2512 /
2513 \end_inset
2514
2515 -L dir
2516 \end_inset
2517 </cell>
2518 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2519 \begin_inset Text
2520
2521 \layout Standard
2522
2523 -
2524 \begin_inset ERT
2525 status Collapsed
2526
2527 \layout Standard
2528
2529 \backslash
2530 /
2531 \end_inset
2532
2533 -L dir
2534 \end_inset
2535 </cell>
2536 </row>
2537 <row topline="true">
2538 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2539 \begin_inset Text
2540
2541 \layout Standard
2542
2543 $SDCC_LIB/
2544 \newline
2545
2546 \emph on
2547 <model>
2548 \end_inset
2549 </cell>
2550 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2551 \begin_inset Text
2552
2553 \layout Standard
2554
2555 $SDCC_LIB/
2556 \newline
2557
2558 \emph on
2559 <model>
2560 \end_inset
2561 </cell>
2562 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2563 \begin_inset Text
2564
2565 \layout Standard
2566
2567 $SDCC_LIB
2568 \backslash
2569
2570 \newline
2571
2572 \emph on
2573 <model>
2574 \end_inset
2575 </cell>
2576 </row>
2577 <row topline="true">
2578 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2579 \begin_inset Text
2580
2581 \layout Standard
2582
2583 $SDCC_HOME/
2584 \newline
2585
2586 \emph on
2587 $PREFIX2DATA_DIR/
2588 \newline
2589 $LIB_DIR_SUFFIX/<model>
2590 \end_inset
2591 </cell>
2592 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2593 \begin_inset Text
2594
2595 \layout Standard
2596
2597 $SDCC_HOME/
2598 \newline
2599 share/sdcc/
2600 \newline
2601 lib/
2602 \emph on
2603 <model>
2604 \end_inset
2605 </cell>
2606 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2607 \begin_inset Text
2608
2609 \layout Standard
2610
2611 $SDCC_HOME
2612 \backslash
2613 lib
2614 \backslash
2615
2616 \emph on
2617
2618 \newline
2619 <model>
2620 \end_inset
2621 </cell>
2622 </row>
2623 <row topline="true">
2624 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2625 \begin_inset Text
2626
2627 \layout Standard
2628
2629 path(argv[0])/
2630 \newline
2631
2632 \emph on
2633 $BIN2DATADIR/
2634 \emph default
2635
2636 \newline
2637
2638 \emph on
2639 $LIB_DIR_SUFFIX/<model>
2640 \end_inset
2641 </cell>
2642 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2643 \begin_inset Text
2644
2645 \layout Standard
2646
2647 path(argv[0])/
2648 \newline
2649 ../sdcc/lib/
2650 \emph on
2651 <model>
2652 \newline
2653 \SpecialChar ~
2654 \SpecialChar ~
2655 \SpecialChar ~
2656 \SpecialChar ~
2657 \SpecialChar ~
2658 \SpecialChar ~
2659 \SpecialChar ~
2660 \SpecialChar ~
2661 \SpecialChar ~
2662 \SpecialChar ~
2663 \SpecialChar ~
2664 \SpecialChar ~
2665 \SpecialChar ~
2666 \SpecialChar ~
2667 \SpecialChar ~
2668 \SpecialChar ~
2669 \SpecialChar ~
2670 \SpecialChar ~
2671 \SpecialChar ~
2672 \SpecialChar ~
2673 \SpecialChar ~
2674 \SpecialChar ~
2675 \SpecialChar ~
2676 \SpecialChar ~
2677 \SpecialChar ~
2678 \SpecialChar ~
2679 \SpecialChar ~
2680 \SpecialChar ~
2681 \SpecialChar ~
2682 \SpecialChar ~
2683 \SpecialChar ~
2684 \SpecialChar ~
2685 \SpecialChar ~
2686 \SpecialChar ~
2687 \SpecialChar ~
2688 \SpecialChar ~
2689 \SpecialChar ~
2690 \SpecialChar ~
2691 \SpecialChar ~
2692
2693 \end_inset
2694 </cell>
2695 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2696 \begin_inset Text
2697
2698 \layout Standard
2699
2700 path(argv[0])
2701 \backslash
2702
2703 \newline
2704 ..
2705 \backslash
2706 lib
2707 \backslash
2708
2709 \emph on
2710 <model>
2711 \newline
2712 \SpecialChar ~
2713 \SpecialChar ~
2714 \SpecialChar ~
2715 \SpecialChar ~
2716 \SpecialChar ~
2717 \SpecialChar ~
2718 \SpecialChar ~
2719 \SpecialChar ~
2720 \SpecialChar ~
2721 \SpecialChar ~
2722 \SpecialChar ~
2723 \SpecialChar ~
2724 \SpecialChar ~
2725 \SpecialChar ~
2726 \SpecialChar ~
2727 \SpecialChar ~
2728 \SpecialChar ~
2729 \SpecialChar ~
2730 \SpecialChar ~
2731 \SpecialChar ~
2732 \SpecialChar ~
2733 \SpecialChar ~
2734 \SpecialChar ~
2735 \SpecialChar ~
2736 \SpecialChar ~
2737 \SpecialChar ~
2738 \SpecialChar ~
2739 \SpecialChar ~
2740 \SpecialChar ~
2741 \SpecialChar ~
2742 \SpecialChar ~
2743 \SpecialChar ~
2744 \SpecialChar ~
2745 \SpecialChar ~
2746 \SpecialChar ~
2747
2748 \end_inset
2749 </cell>
2750 </row>
2751 <row topline="true" bottomline="true">
2752 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2753 \begin_inset Text
2754
2755 \layout Standard
2756
2757
2758 \emph on
2759 $DATADIR/
2760 \newline
2761 $LIB_DIR_SUFFIX/<model>
2762 \end_inset
2763 </cell>
2764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2765 \begin_inset Text
2766
2767 \layout Standard
2768
2769 /usr/local/share/sdcc/
2770 \newline
2771 lib/
2772 \emph on
2773 <model>
2774 \end_inset
2775 </cell>
2776 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2777 \begin_inset Text
2778
2779 \layout Standard
2780
2781 (not on Win32)
2782 \end_inset
2783 </cell>
2784 </row>
2785 </lyxtabular>
2786
2787 \end_inset
2788
2789
2790 \newline
2791
2792 \layout Comment
2793
2794 Don't delete any of the stray spaces in the table above without checking
2795  the HTML output (last line)!
2796 \layout Standard
2797
2798 \SpecialChar ~
2799
2800 \newline
2801 The option -
2802 \begin_inset ERT
2803 status Collapsed
2804
2805 \layout Standard
2806
2807 \backslash
2808 /
2809 \end_inset
2810
2811 -nostdlib disables the last two search paths.
2812 \layout Section
2813
2814 Building SDCC
2815 \begin_inset LatexCommand \index{Building SDCC}
2816
2817 \end_inset
2818
2819
2820 \layout Subsection
2821
2822 Building SDCC on Linux
2823 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2824
2825 \end_inset
2826
2827
2828 \layout Enumerate
2829
2830
2831 \series medium
2832 Download the source package
2833 \series default
2834  either from the SDCC CVS repository or from the nightly snapshots
2835 \series medium
2836 , it will be named something like sdcc
2837 \series default
2838 .src
2839 \series medium
2840 .t
2841 \series default
2842 ar.
2843 \series medium
2844 gz
2845 \series default
2846
2847 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2848
2849 \end_inset
2850
2851 .
2852 \layout Enumerate
2853
2854
2855 \series medium
2856 Bring up a command line terminal, such as xterm.
2857 \layout Enumerate
2858
2859
2860 \series medium
2861 Unpack the file using a command like:
2862 \family sans
2863 \series bold
2864 "tar -xvzf sdcc.src.tar.gz
2865 \family default
2866 \series default
2867 "
2868 \series medium
2869 , this will create a sub-directory called sdcc with all of the sources.
2870 \layout Enumerate
2871
2872 Change directory into the main SDCC directory, for example type:
2873 \family sans
2874 \series bold
2875 "cd sdcc
2876 \series default
2877 ".
2878 \layout Enumerate
2879
2880
2881 \series medium
2882 Type
2883 \family sans
2884 \series bold
2885 "./configure
2886 \family default
2887 \series default
2888 ".
2889  This configures the package for compilation on your system.
2890 \layout Enumerate
2891
2892
2893 \series medium
2894 Type
2895 \family sans
2896 \series bold
2897 "make
2898 \family default
2899 \series default
2900 "
2901 \series medium
2902 .
2903
2904 \series default
2905  All of the source packages will compile, this can take a while.
2906 \layout Enumerate
2907
2908
2909 \series medium
2910 Type
2911 \family sans
2912 \series bold
2913 "make install"
2914 \family default
2915 \series default
2916  as root
2917 \series medium
2918 .
2919
2920 \series default
2921  This copies the binary executables, the include files, the libraries and
2922  the documentation to the install directories.
2923  Proceed with section
2924 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
2925
2926 \end_inset
2927
2928 .
2929 \layout Subsection
2930
2931 Building SDCC on OSX 2.x
2932 \layout Standard
2933
2934 Follow the instruction for Linux.
2935 \newline
2936
2937 \newline
2938 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
2939 )) fails to compile SDCC.
2940  Fortunately there's also gcc 2.9.x installed, which works fine.
2941  This compiler can be selected by running 'configure' with:
2942 \layout LyX-Code
2943
2944 ./configure CC=gcc2 CXX=g++2
2945 \layout Subsection
2946
2947 Cross compiling SDCC on Linux for Windows
2948 \layout Standard
2949
2950 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
2951  See section 'Configure Options'.
2952 \layout Subsection
2953
2954 Building SDCC on Windows
2955 \layout Standard
2956
2957 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
2958  built on Windows.
2959  They use Unix-sockets, which are not available on Win32.
2960 \layout Subsection
2961
2962 Building SDCC using Cygwin and Mingw32
2963 \layout Standard
2964
2965 For building and installing a Cygwin executable follow the instructions
2966  for Linux.
2967 \newline
2968
2969 \newline
2970 On Cygwin a
2971 \begin_inset Quotes sld
2972 \end_inset
2973
2974 native
2975 \begin_inset Quotes srd
2976 \end_inset
2977
2978  Win32-binary can be built, which will not need the Cygwin-DLL.
2979  For the necessary 'configure' options see section 'configure options' or
2980  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
2981 \newline
2982
2983 \newline
2984 In order to install Cygwin on Windows download setup.exe from
2985 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
2986
2987 \end_inset
2988
2989 .
2990  Run it, set the
2991 \begin_inset Quotes sld
2992 \end_inset
2993
2994 default text file type
2995 \begin_inset Quotes srd
2996 \end_inset
2997
2998  to
2999 \begin_inset Quotes sld
3000 \end_inset
3001
3002 unix
3003 \begin_inset Quotes srd
3004 \end_inset
3005
3006  and download/install at least the following packages.
3007  Some packages are selected by default, others will be automatically selected
3008  because of dependencies with the manually selected packages.
3009  Never deselect these packages!
3010 \layout Itemize
3011
3012 flex
3013 \layout Itemize
3014
3015 bison
3016 \layout Itemize
3017
3018 gcc ; version 3.x is fine, no need to use the old 2.9x
3019 \layout Itemize
3020
3021 binutils ; selected with gcc
3022 \layout Itemize
3023
3024 make
3025 \layout Itemize
3026
3027 rxvt ; a nice console, which makes life much easier under windoze (see below)
3028 \layout Itemize
3029
3030 man ; not really needed for building SDCC, but you'll miss it sooner or
3031  later
3032 \layout Itemize
3033
3034 less ; not really needed for building SDCC, but you'll miss it sooner or
3035  later
3036 \layout Itemize
3037
3038 cvs ; only if you use CVS access
3039 \layout Standard
3040
3041 If you want to develop something you'll need:
3042 \layout Itemize
3043
3044 python ; for the regression tests
3045 \layout Itemize
3046
3047 gdb ; the gnu debugger, together with the nice GUI
3048 \begin_inset Quotes sld
3049 \end_inset
3050
3051 insight
3052 \begin_inset Quotes srd
3053 \end_inset
3054
3055
3056 \layout Itemize
3057
3058 openssh ; to access the CF or commit changes
3059 \layout Itemize
3060
3061 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3062  use autoconf-stable!
3063 \layout Standard
3064
3065 rxvt is a nice console with history.
3066  Replace in your cygwin.bat the line
3067 \layout LyX-Code
3068
3069 bash -
3070 \begin_inset ERT
3071 status Collapsed
3072
3073 \layout Standard
3074
3075 \backslash
3076 /
3077 \end_inset
3078
3079 -login -i
3080 \layout Standard
3081
3082 with (one line):
3083 \layout LyX-Code
3084
3085 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3086 \layout LyX-Code
3087
3088      -bg black -fg white -geometry 100x65 -e bash -
3089 \begin_inset ERT
3090 status Collapsed
3091
3092 \layout Standard
3093
3094 \backslash
3095 /
3096 \end_inset
3097
3098 -login
3099 \layout Standard
3100
3101 Text selected with the mouse is automatically copied to the clipboard, pasting
3102  works with shift-insert.
3103 \newline
3104
3105 \newline
3106 The other good tip is to make sure you have no //c/-style paths anywhere,
3107  use /cygdrive/c/ instead.
3108  Using // invokes a network lookup which is very slow.
3109  If you think
3110 \begin_inset Quotes sld
3111 \end_inset
3112
3113 cygdrive
3114 \begin_inset Quotes srd
3115 \end_inset
3116
3117  is too long, you can change it with e.g.
3118 \layout LyX-Code
3119
3120 mount -s -u -c /mnt
3121 \layout Standard
3122
3123 SDCC sources use the unix line ending LF.
3124  Life is much easier, if you store the source tree on a drive which is mounted
3125  in binary mode.
3126  And use an editor which can handle LF-only line endings.
3127  Make sure not to commit files with windows line endings.
3128  The tabulator spacing
3129 \begin_inset LatexCommand \index{tabulator spacing (8)}
3130
3131 \end_inset
3132
3133  used in the project is 8.
3134 \layout Subsection
3135
3136 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3137 \layout Standard
3138
3139
3140 \series medium
3141 Download the source package
3142 \series default
3143  either from the SDCC CVS repository or from the
3144 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3145
3146 \end_inset
3147
3148
3149 \series medium
3150 , it will be named something like sdcc
3151 \series default
3152 .src
3153 \series medium
3154 .tgz.
3155
3156 \series default
3157  SDCC is distributed with all the projects, workspaces, and files you need
3158  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3159  doesn't build under MSVC).
3160  The workspace name is 'sdcc.dsw'.
3161  Please note that as it is now, all the executables are created in a folder
3162  called sdcc
3163 \backslash
3164 bin_vc.
3165  Once built you need to copy the executables from sdcc
3166 \backslash
3167 bin_vc to sdcc
3168 \backslash
3169 bin before running SDCC.
3170
3171 \newline
3172
3173 \newline
3174 WARNING: Visual studio is very picky with line terminations; it expects
3175  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3176  If you are getting a message such as "This makefile was not generated by
3177  Developer Studio etc.
3178  etc.
3179 \begin_inset Quotes srd
3180 \end_inset
3181
3182  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3183  need to convert the Unix style line endings to DOS style line endings.
3184  To do so you can use the
3185 \begin_inset Quotes sld
3186 \end_inset
3187
3188 unix2dos
3189 \begin_inset Quotes srd
3190 \end_inset
3191
3192  utility freely available on the internet.
3193  Doug Hawkins reported in the sdcc-user list that this works:
3194 \newline
3195
3196 \newline
3197 C:
3198 \backslash
3199 Programming
3200 \backslash
3201 SDCC> unix2dos sdcc.dsw
3202 \newline
3203 C:
3204 \backslash
3205 Programming
3206 \backslash
3207 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3208 \newline
3209
3210 \newline
3211 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3212  flex.exe, and gawk.exe.
3213  One good place to get them is
3214 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3215
3216 \end_inset
3217
3218
3219 \newline
3220
3221 \newline
3222 Download the file UnxUtils
3223 \begin_inset LatexCommand \index{UnxUtils}
3224
3225 \end_inset
3226
3227 .zip.
3228  Now you have to install the utilities and setup MSVC so it can locate the
3229  required programs.
3230  Here there are two alternatives (choose one!):
3231 \layout Enumerate
3232
3233 The easy way:
3234 \newline
3235
3236 \newline
3237 a) Extract UnxUtils.zip to your C:
3238 \backslash
3239  hard disk PRESERVING the original paths, otherwise bison won't work.
3240  (If you are using WinZip make certain that 'Use folder names' is selected)
3241 \newline
3242
3243 \newline
3244 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3245  in 'Show directories for:' select 'Executable files', and in the directories
3246  window add a new path: 'C:
3247 \backslash
3248 user
3249 \backslash
3250 local
3251 \backslash
3252 wbin', click ok.
3253 \newline
3254
3255 \newline
3256 (As a side effect, you get a bunch of Unix utilities that could be useful,
3257  such as diff and patch.)
3258 \layout Enumerate
3259
3260 A more compact way:
3261 \newline
3262
3263 \newline
3264 This one avoids extracting a bunch of files you may not use, but requires
3265  some extra work:
3266 \newline
3267
3268 \newline
3269 a) Create a directory were to put the tools needed, or use a directory already
3270  present.
3271  Say for example 'C:
3272 \backslash
3273 util'.
3274 \newline
3275
3276 \newline
3277 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3278  to such directory WITHOUT preserving the original paths.
3279  (If you are using WinZip make certain that 'Use folder names' is not selected)
3280 \newline
3281
3282 \newline
3283 c) Rename bison.exe to '_bison.exe'.
3284 \newline
3285
3286 \newline
3287 d) Create a batch file 'bison.bat' in 'C:
3288 \backslash
3289 util
3290 \backslash
3291 ' and add these lines:
3292 \newline
3293 \SpecialChar ~
3294 \SpecialChar ~
3295 set BISON_SIMPLE=C:
3296 \backslash
3297 util
3298 \backslash
3299 bison.simple
3300 \newline
3301 \SpecialChar ~
3302 \SpecialChar ~
3303 set BISON_HAIRY=C:
3304 \backslash
3305 util
3306 \backslash
3307 bison.hairy
3308 \newline
3309 \SpecialChar ~
3310 \SpecialChar ~
3311 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3312 \newline
3313
3314 \newline
3315 Steps 'c' and 'd' are needed because bison requires by default that the
3316  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3317  '/usr/local/share/' I think.
3318  So it is necessary to tell bison where those files are located if they
3319  are not in such directory.
3320  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3321 \newline
3322
3323 \newline
3324 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3325  in 'Show directories for:' select 'Executable files', and in the directories
3326  window add a new path: 'c:
3327 \backslash
3328 util', click ok.
3329  Note that you can use any other path instead of 'c:
3330 \backslash
3331 util', even the path where the Visual C++ tools are, probably: 'C:
3332 \backslash
3333 Program Files
3334 \backslash
3335 Microsoft Visual Studio
3336 \backslash
3337 Common
3338 \backslash
3339 Tools'.
3340  So you don't have to execute step 'e' :)
3341 \layout Standard
3342
3343 That is it.
3344  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3345  the executables from sdcc
3346 \backslash
3347 bin_vc to sdcc
3348 \backslash
3349 bin, and you can compile using SDCC.
3350 \layout Subsection
3351
3352 Building SDCC Using Borland
3353 \layout Enumerate
3354
3355 From the sdcc directory, run the command "make -f Makefile.bcc".
3356  This should regenerate all the .exe files in the bin directory except for
3357  sdcdb.exe (which currently doesn't build under Borland C++).
3358 \layout Enumerate
3359
3360 If you modify any source files and need to rebuild, be aware that the dependenci
3361 es may not be correctly calculated.
3362  The safest option is to delete all .obj files and run the build again.
3363  From a Cygwin BASH prompt, this can easily be done with the command (be
3364  sure you are in the sdcc directory):
3365 \newline
3366
3367 \newline
3368
3369 \family sans
3370 \series bold
3371 find .
3372
3373 \backslash
3374 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3375 \backslash
3376 ) -print -exec rm {}
3377 \backslash
3378 ;
3379 \family default
3380 \series default
3381
3382 \newline
3383
3384 \newline
3385 or on Windows NT/2000/XP from the command prompt with the command:
3386 \newline
3387
3388 \family sans
3389 \series bold
3390
3391 \newline
3392 del /s *.obj *.lib *.rul
3393 \family default
3394 \series default
3395  from the sdcc directory.
3396 \layout Subsection
3397
3398 Windows Install Using a Binary Package
3399 \begin_inset LatexCommand \label{sub:Windows-Install}
3400
3401 \end_inset
3402
3403
3404 \layout Enumerate
3405
3406 Download the binary package from
3407 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3408
3409 \end_inset
3410
3411  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3412  This should unpack to a group of sub-directories.
3413  An example directory structure after unpacking the mingw32 package is:
3414  c:
3415 \backslash
3416 sdcc
3417 \backslash
3418 bin for the executables, c:
3419 \backslash
3420 sdcc
3421 \backslash
3422 include and c:
3423 \backslash
3424 sdcc
3425 \backslash
3426 lib for the include and libraries.
3427 \layout Enumerate
3428
3429 Adjust your environment variable PATH to include the location of the bin
3430  directory or start sdcc using the full path.
3431 \layout Section
3432
3433 Building the Documentation
3434 \layout Standard
3435
3436 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3437  as changing into the doc directory and typing
3438 \family sans
3439 \series bold
3440
3441 \begin_inset Quotes srd
3442 \end_inset
3443
3444 make
3445 \begin_inset Quotes srd
3446 \end_inset
3447
3448
3449 \family default
3450 \series default
3451  there.
3452  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3453 x).
3454  Using LyX
3455 \begin_inset LatexCommand \url{www.lyx.org}
3456
3457 \end_inset
3458
3459  as editor this is straightforward.
3460  If you want to avoid installing the tools you will have some success with
3461  a bootable Knoppix CD
3462 \begin_inset LatexCommand \url{http://www.knoppix.net}
3463
3464 \end_inset
3465
3466 .
3467  Prebuilt documentation in html and pdf format is available from
3468 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3469
3470 \end_inset
3471
3472 .
3473 \layout Section
3474
3475 Reading the Documentation
3476 \layout Standard
3477
3478 Currently reading the document in pdf format is recommended, as for unknown
3479  reason the hyperlinks are working there whereas in the html version they
3480  are not
3481 \begin_inset Foot
3482 collapsed false
3483
3484 \layout Standard
3485
3486 If you should know why please drop us a note
3487 \end_inset
3488
3489 .
3490  You'll find the pdf version at
3491 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
3492
3493 \end_inset
3494
3495 .
3496 \newline
3497 This documentation is in some aspects different from a commercial documentation:
3498
3499 \layout Itemize
3500
3501 It tries to document SDCC for several processor architectures in one document
3502  (commercially these probably would be separate documents/products).
3503  This document
3504 \begin_inset LatexCommand \index{Status of documentation}
3505
3506 \end_inset
3507
3508  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3509 on about f.e.
3510  Z80, PIC14, PIC16 and HC08.
3511 \layout Itemize
3512
3513 There are many references pointing away from this documentation.
3514  Don't let this distract you.
3515  If there f.e.
3516  was a reference like
3517 \begin_inset LatexCommand \url{www.opencores.org}
3518
3519 \end_inset
3520
3521  together with a statement
3522 \begin_inset Quotes sld
3523 \end_inset
3524
3525 some processors which are targetted by SDCC can be implemented in a
3526 \emph on
3527 f
3528 \emph default
3529 ield
3530 \emph on
3531 p
3532 \emph default
3533 rogrammable
3534 \emph on
3535 g
3536 \emph default
3537 ate
3538 \emph on
3539 a
3540 \emph default
3541 rray
3542 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3543
3544 \end_inset
3545
3546
3547 \begin_inset Quotes srd
3548 \end_inset
3549
3550  we expect you to have a quick look there and come back.
3551  If you read this you are on the right track.
3552 \layout Itemize
3553
3554 Some sections attribute more space to problems, restrictions and warnings
3555  than to the solution.
3556 \layout Itemize
3557
3558 The installation section and the section about the debugger is intimidating.
3559 \layout Itemize
3560
3561 There are still lots of typos and there are more different writing styles
3562  than pictures.
3563 \layout Section
3564
3565 Testing the SDCC Compiler
3566 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3567
3568 \end_inset
3569
3570
3571 \layout Standard
3572
3573 The first thing you should do after installing your SDCC compiler is to
3574  see if it runs.
3575  Type
3576 \family sans
3577 \series bold
3578 "sdcc -
3579 \begin_inset ERT
3580 status Collapsed
3581
3582 \layout Standard
3583
3584 \backslash
3585 /
3586 \end_inset
3587
3588 -version"
3589 \begin_inset LatexCommand \index{version}
3590
3591 \end_inset
3592
3593
3594 \family default
3595 \series default
3596  at the prompt, and the program should run and tell you the version.
3597  If it doesn't run, or gives a message about not finding sdcc program, then
3598  you need to check over your installation.
3599  Make sure that the sdcc bin directory is in your executable search path
3600  defined by the PATH environment setting (
3601 \series medium
3602 see
3603 \series default
3604 section
3605 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3606
3607 \end_inset
3608
3609 \SpecialChar ~
3610
3611 \series medium
3612 Install trouble-shooting for suggestions
3613 \series default
3614 ).
3615  Make sure that the sdcc program is in the bin folder, if not perhaps something
3616  did not install correctly.
3617 \newline
3618
3619 \newline
3620
3621 \series medium
3622 SDCC
3623 \series default
3624 is commonly installed as described in section
3625 \begin_inset Quotes sld
3626 \end_inset
3627
3628 Install and search paths
3629 \begin_inset Quotes srd
3630 \end_inset
3631
3632 .
3633 \newline
3634
3635 \newline
3636
3637 \series medium
3638 Make sure the compiler works on a very simple example.
3639  Type in the following test.c program using your favorite
3640 \series default
3641 ASCII
3642 \series medium
3643 editor:
3644 \layout Verse
3645
3646
3647 \family typewriter
3648 char test;
3649 \newline
3650
3651 \newline
3652 void main(void) {
3653 \newline
3654 \SpecialChar ~
3655 \SpecialChar ~
3656 \SpecialChar ~
3657 \SpecialChar ~
3658 test=0;
3659 \newline
3660 }
3661 \layout Standard
3662
3663
3664 \series medium
3665 Compile this using the following command:
3666 \family sans
3667 \series bold
3668 "sdcc -c test.c".
3669
3670 \family default
3671 \series default
3672
3673 \series medium
3674 If all goes well, the compiler will generate a test.asm and test.rel file.
3675  Congratulations, you've just compiled your first program with SDCC.
3676  We used the -c option to tell SDCC not to link the generated code, just
3677  to keep things simple for this step.
3678 \series default
3679
3680 \newline
3681
3682 \newline
3683
3684 \series medium
3685 The next step is to try it with the linker.
3686  Type in
3687 \family sans
3688 \series bold
3689 "sdcc test.c
3690 \family default
3691 \series default
3692 "
3693 \series medium
3694 .
3695  If all goes well the compiler will link with the libraries and produce
3696  a test.ihx output file.
3697  If this step fails
3698 \series default
3699
3700 \series medium
3701 (no test.ihx, and the linker generates warnings), then the problem is most
3702  likely that
3703 \series default
3704 SDCC
3705 \series medium
3706  cannot find the
3707 \series default
3708 /
3709 \series medium
3710 usr/local/share/sdcc/lib directory
3711 \series default
3712
3713 \series medium
3714 (see
3715 \series default
3716 section
3717 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3718
3719 \end_inset
3720
3721 \SpecialChar ~
3722
3723 \series medium
3724 Install trouble-shooting for suggestions).
3725 \series default
3726
3727 \newline
3728
3729 \newline
3730
3731 \series medium
3732 The final test is to ensure
3733 \series default
3734 SDCC
3735 \series medium
3736  can use the
3737 \series default
3738 standard
3739 \series medium
3740  header files and libraries.
3741  Edit test.c and change it to the following:
3742 \layout Verse
3743
3744
3745 \family typewriter
3746 #include <string.h>
3747 \newline
3748
3749 \newline
3750 char str1[10];
3751 \newline
3752
3753 \newline
3754 void main(void) {
3755 \newline
3756 \SpecialChar ~
3757 \SpecialChar ~
3758 strcpy(str1, "testing");
3759 \newline
3760 }
3761 \layout Standard
3762
3763
3764 \series medium
3765 Compile this by typing
3766 \family sans
3767 \series bold
3768 "sdcc test.c"
3769 \family default
3770 \series medium
3771 .
3772  This should generate a test.ihx output file, and it should give no warnings
3773  such as not finding the string.h file.
3774  If it cannot find the string.h file, then the problem is that
3775 \series default
3776 SDCC
3777 \series medium
3778  cannot find the /usr/local/share/sdcc/include directory
3779 \series default
3780
3781 \series medium
3782 (see the
3783 \series default
3784 section
3785 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3786
3787 \end_inset
3788
3789 \SpecialChar ~
3790
3791 \series medium
3792 Install trouble-shooting section for suggestions).
3793
3794 \series default
3795  Use option
3796 \series bold
3797 -
3798 \begin_inset ERT
3799 status Collapsed
3800
3801 \layout Standard
3802
3803 \backslash
3804 /
3805 \end_inset
3806
3807 -print-search-dirs
3808 \series default
3809
3810 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3811
3812 \end_inset
3813
3814  to find exactly where SDCC is looking for the include and lib files.
3815 \layout Section
3816
3817 Install Trouble-shooting
3818 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3819
3820 \end_inset
3821
3822
3823 \begin_inset LatexCommand \index{Install trouble-shooting}
3824
3825 \end_inset
3826
3827
3828 \layout Subsection
3829
3830 If SDCC does not build correctly
3831 \layout Standard
3832
3833 A thing to try is starting from scratch by unpacking the .tgz source package
3834  again in an empty directory.
3835  Configure it like:
3836 \newline
3837
3838 \newline
3839
3840 \family sans
3841 \series bold
3842 ./configure 2>&1 | tee configure.log
3843 \family default
3844 \series default
3845
3846 \newline
3847
3848 \newline
3849 and build it like:
3850 \newline
3851
3852 \newline
3853
3854 \family sans
3855 \series bold
3856 make 2>&1 | tee make.log
3857 \family default
3858 \series default
3859
3860 \newline
3861
3862 \newline
3863 If anything goes wrong, you can review the log files to locate the problem.
3864  Or a relevant part of this can be attached to an email that could be helpful
3865  when requesting help from the mailing list.
3866 \layout Subsection
3867
3868 What the
3869 \begin_inset Quotes sld
3870 \end_inset
3871
3872 ./configure
3873 \begin_inset Quotes srd
3874 \end_inset
3875
3876  does
3877 \layout Standard
3878
3879 The
3880 \begin_inset Quotes sld
3881 \end_inset
3882
3883 ./configure
3884 \begin_inset Quotes srd
3885 \end_inset
3886
3887  command is a script that analyzes your system and performs some configuration
3888  to ensure the source package compiles on your system.
3889  It will take a few minutes to run, and will compile a few tests to determine
3890  what compiler features are installed.
3891 \layout Subsection
3892
3893 What the
3894 \begin_inset Quotes sld
3895 \end_inset
3896
3897 make
3898 \begin_inset Quotes srd
3899 \end_inset
3900
3901  does
3902 \layout Standard
3903
3904 This runs the GNU make tool, which automatically compiles all the source
3905  packages into the final installed binary executables.
3906 \layout Subsection
3907
3908 What the
3909 \begin_inset Quotes sld
3910 \end_inset
3911
3912 make install
3913 \begin_inset Quotes erd
3914 \end_inset
3915
3916  command does.
3917 \layout Standard
3918
3919 This will install the compiler, other executables libraries and include
3920  files into the appropriate directories.
3921  See sections
3922 \begin_inset LatexCommand \ref{sub:Install-paths}
3923
3924 \end_inset
3925
3926 ,\SpecialChar ~
3927
3928 \begin_inset LatexCommand \ref{sub:Search-Paths}
3929
3930 \end_inset
3931
3932 \SpecialChar ~
3933 about install and search paths.
3934 \newline
3935 On most systems you will need super-user privileges to do this.
3936 \layout Section
3937
3938 Components of SDCC
3939 \layout Standard
3940
3941 SDCC is not just a compiler, but a collection of tools by various developers.
3942  These include linkers, assemblers, simulators and other components.
3943  Here is a summary of some of the components.
3944  Note that the included simulator and assembler have separate documentation
3945  which you can find in the source package in their respective directories.
3946  As SDCC grows to include support for other processors, other packages from
3947  various developers are included and may have their own sets of documentation.
3948 \newline
3949
3950 \newline
3951 You might want to look at the files which are installed in <installdir>.
3952  At the time of this writing, we find the following programs for gcc-builds:
3953 \newline
3954
3955 \newline
3956 In <installdir>/bin:
3957 \layout Itemize
3958
3959 sdcc - The compiler.
3960 \layout Itemize
3961
3962 sdcpp - The C preprocessor.
3963 \layout Itemize
3964
3965 asx8051 - The assembler for 8051 type processors.
3966 \layout Itemize
3967
3968 as-z80
3969 \series bold
3970 ,
3971 \series default
3972 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
3973 \layout Itemize
3974
3975 aslink -The linker for 8051 type processors.
3976 \layout Itemize
3977
3978 link-z80
3979 \series bold
3980 ,
3981 \series default
3982 link-gbz80 - The Z80 and GameBoy Z80 linkers.
3983 \layout Itemize
3984
3985 s51 - The ucSim 8051 simulator.
3986 \layout Itemize
3987
3988 sdcdb - The source debugger.
3989 \layout Itemize
3990
3991 packihx - A tool to pack (compress) Intel hex files.
3992 \layout Standard
3993
3994 In <installdir>/share/sdcc/include
3995 \layout Itemize
3996
3997 the include files
3998 \layout Standard
3999
4000 In <installdir>/share/sdcc/lib
4001 \layout Itemize
4002
4003 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4004  relocatables.
4005 \layout Standard
4006
4007 In <installdir>/share/sdcc/doc
4008 \layout Itemize
4009
4010 the documentation
4011 \layout Standard
4012
4013 As development for other processors proceeds, this list will expand to include
4014  executables to support processors like AVR, PIC, etc.
4015 \layout Subsection
4016
4017 sdcc - The Compiler
4018 \layout Standard
4019
4020 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4021  the assembler and linkage editor.
4022 \layout Subsection
4023
4024 sdcpp - The C-Preprocessor
4025 \layout Standard
4026
4027 The preprocessor
4028 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4029
4030 \end_inset
4031
4032  is a modified version of the GNU preprocessor.
4033  The C preprocessor is used to pull in #include sources, process #ifdef
4034  statements, #defines and so on.
4035 \layout Subsection
4036
4037 as
4038 \emph on
4039 xxxx
4040 \emph default
4041 , aslink, link-
4042 \emph on
4043 xxx
4044 \emph default
4045  - The Assemblers and Linkage Editors
4046 \layout Standard
4047
4048 This is retargettable assembler & linkage editor, it was developed by Alan
4049  Baldwin.
4050  John Hartman created the version for 8051, and I (Sandeep) have made some
4051  enhancements and bug fixes for it to work properly with SDCC.
4052 \layout Subsection
4053
4054 s51 - The Simulator
4055 \layout Standard
4056
4057 S51
4058 \begin_inset LatexCommand \index{s51}
4059
4060 \end_inset
4061
4062  is a freeware, opensource simulator developed by Daniel Drotos (
4063 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
4064
4065 \end_inset
4066
4067 ).
4068  The simulator is built as part of the build process.
4069  For more information visit Daniel's web site at:
4070 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4071
4072 \end_inset
4073
4074 .
4075  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4076  XA51 family.
4077 \layout Subsection
4078
4079 sdcdb - Source Level Debugger
4080 \layout Standard
4081
4082 Sdcdb
4083 \begin_inset LatexCommand \index{sdcdb (debugger)}
4084
4085 \end_inset
4086
4087  is the companion source level debugger.
4088  More about sdcdb in section
4089 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4090
4091 \end_inset
4092
4093 .
4094  The current version of the debugger uses Daniel's Simulator S51
4095 \begin_inset LatexCommand \index{s51}
4096
4097 \end_inset
4098
4099 , but can be easily changed to use other simulators.
4100
4101 \layout Chapter
4102
4103 Using SDCC
4104 \layout Section
4105
4106 Compiling
4107 \layout Subsection
4108
4109 Single Source File Projects
4110 \layout Standard
4111
4112 For single source file 8051 projects the process is very simple.
4113  Compile your programs with the following command
4114 \family sans
4115 \series bold
4116 "sdcc sourcefile.c".
4117
4118 \family default
4119 \series default
4120  This will compile, assemble and link your source file.
4121  Output files are as follows:
4122 \layout Itemize
4123
4124 sourcefile.asm
4125 \begin_inset LatexCommand \index{<file>.asm}
4126
4127 \end_inset
4128
4129  - Assembler source
4130 \begin_inset LatexCommand \index{Assembler source}
4131
4132 \end_inset
4133
4134  file created by the compiler
4135 \layout Itemize
4136
4137 sourcefile.lst
4138 \begin_inset LatexCommand \index{<file>.lst}
4139
4140 \end_inset
4141
4142  - Assembler listing
4143 \begin_inset LatexCommand \index{Assembler listing}
4144
4145 \end_inset
4146
4147  file created by the Assembler
4148 \layout Itemize
4149
4150 sourcefile.rst
4151 \begin_inset LatexCommand \index{<file>.rst}
4152
4153 \end_inset
4154
4155  - Assembler listing
4156 \begin_inset LatexCommand \index{Assembler listing}
4157
4158 \end_inset
4159
4160  file updated with linkedit information, created by linkage editor
4161 \layout Itemize
4162
4163 sourcefile.sym
4164 \begin_inset LatexCommand \index{<file>.sym}
4165
4166 \end_inset
4167
4168  - symbol listing
4169 \begin_inset LatexCommand \index{Symbol listing}
4170
4171 \end_inset
4172
4173  for the sourcefile, created by the assembler
4174 \layout Itemize
4175
4176 sourcefile.rel
4177 \begin_inset LatexCommand \index{<file>.rel}
4178
4179 \end_inset
4180
4181  or sourcefile.o
4182 \begin_inset LatexCommand \index{<file>.o}
4183
4184 \end_inset
4185
4186  - Object file
4187 \begin_inset LatexCommand \index{Object file}
4188
4189 \end_inset
4190
4191  created by the assembler, input to Linkage editor
4192 \layout Itemize
4193
4194 sourcefile.map
4195 \begin_inset LatexCommand \index{<file>.map}
4196
4197 \end_inset
4198
4199  - The memory map
4200 \begin_inset LatexCommand \index{Memory map}
4201
4202 \end_inset
4203
4204  for the load module, created by the Linker
4205 \layout Itemize
4206
4207 sourcefile.mem
4208 \begin_inset LatexCommand \index{<file>.mem}
4209
4210 \end_inset
4211
4212  - A file with a summary of the memory usage
4213 \layout Itemize
4214
4215 sourcefile.ihx
4216 \begin_inset LatexCommand \index{<file>.ihx}
4217
4218 \end_inset
4219
4220  - The load module in Intel hex format
4221 \begin_inset LatexCommand \index{Intel hex format}
4222
4223 \end_inset
4224
4225  (you can select the Motorola S19 format
4226 \begin_inset LatexCommand \index{Motorola S19 format}
4227
4228 \end_inset
4229
4230  with -
4231 \begin_inset ERT
4232 status Collapsed
4233
4234 \layout Standard
4235
4236 \backslash
4237 /
4238 \end_inset
4239
4240 -out-fmt-s19
4241 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4242
4243 \end_inset
4244
4245 .
4246  If you need another format you might want to use
4247 \family sans
4248 \shape italic
4249 objdump
4250 \family default
4251 \shape default
4252
4253 \begin_inset LatexCommand \index{objdump (tool)}
4254
4255 \end_inset
4256
4257  or
4258 \family sans
4259 \shape italic
4260  srecord
4261 \family default
4262 \shape default
4263
4264 \begin_inset LatexCommand \index{srecord (tool)}
4265
4266 \end_inset
4267
4268 ).
4269  Both formats are documented in the documentation of srecord
4270 \begin_inset LatexCommand \index{srecord (tool)}
4271
4272 \end_inset
4273
4274
4275 \layout Itemize
4276
4277 sourcefile.adb
4278 \begin_inset LatexCommand \index{<file>.adb}
4279
4280 \end_inset
4281
4282  - An intermediate file containing debug information needed to create the
4283  .cdb file (with -
4284 \begin_inset ERT
4285 status Collapsed
4286
4287 \layout Standard
4288
4289 \backslash
4290 /
4291 \end_inset
4292
4293 -debug
4294 \begin_inset LatexCommand \index{-\/-debug}
4295
4296 \end_inset
4297
4298 )
4299 \layout Itemize
4300
4301 sourcefile.cdb
4302 \begin_inset LatexCommand \index{<file>.cdb}
4303
4304 \end_inset
4305
4306  - An optional file (with -
4307 \begin_inset ERT
4308 status Collapsed
4309
4310 \layout Standard
4311
4312 \backslash
4313 /
4314 \end_inset
4315
4316 -debug) containing debug information.
4317  The format is documented in cdbfileformat.pdf.
4318 \layout Itemize
4319
4320 sourcefile.
4321  - (no extension)
4322 \begin_inset LatexCommand \index{<file> (no extension)}
4323
4324 \end_inset
4325
4326  An optional AOMF or AOMF51
4327 \begin_inset LatexCommand \index{AOMF, AOMF51}
4328
4329 \end_inset
4330
4331  file containing debug information (generated with option -
4332 \begin_inset ERT
4333 status Collapsed
4334
4335 \layout Standard
4336
4337 \backslash
4338 /
4339 \end_inset
4340
4341 -debug).
4342  The (Intel)
4343 \emph on
4344  a
4345 \emph default
4346 bsolute
4347 \emph on
4348 o
4349 \emph default
4350 bject
4351 \emph on
4352 m
4353 \emph default
4354 odule
4355 \emph on
4356 f
4357 \emph default
4358 ormat is commonly used by third party tools (debuggers
4359 \begin_inset LatexCommand \index{Debugger}
4360
4361 \end_inset
4362
4363 , simulators, emulators)
4364 \layout Itemize
4365
4366 sourcefile.dump*
4367 \begin_inset LatexCommand \index{<file>.dump*}
4368
4369 \end_inset
4370
4371  - Dump file to debug the compiler it self (generated with option -
4372 \begin_inset ERT
4373 status Collapsed
4374
4375 \layout Standard
4376
4377 \backslash
4378 /
4379 \end_inset
4380
4381 -dumpall) (see section
4382 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4383
4384 \end_inset
4385
4386 \SpecialChar ~
4387  and section
4388 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4389
4390 \end_inset
4391
4392 \SpecialChar ~
4393
4394 \begin_inset Quotes sld
4395 \end_inset
4396
4397 Anatomy of the compiler
4398 \begin_inset Quotes srd
4399 \end_inset
4400
4401 ).
4402 \layout Subsection
4403
4404 Projects with Multiple Source Files
4405 \layout Standard
4406
4407 SDCC can compile only ONE file at a time.
4408  Let us for example assume that you have a project containing the following
4409  files:
4410 \newline
4411
4412 \newline
4413 foo1.c (contains some functions)
4414 \newline
4415 foo2.c (contains some more functions)
4416 \newline
4417 foomain.c (contains more functions and the function main)
4418 \newline
4419
4420 \size footnotesize
4421
4422 \newline
4423
4424 \size default
4425 The first two files will need to be compiled separately with the commands:
4426 \size footnotesize
4427
4428 \size default
4429
4430 \newline
4431
4432 \newline
4433
4434 \family sans
4435 \series bold
4436 sdcc\SpecialChar ~
4437 -c\SpecialChar ~
4438 foo1.c
4439 \family default
4440 \series default
4441 \size footnotesize
4442
4443 \newline
4444
4445 \family sans
4446 \series bold
4447 \size default
4448 sdcc\SpecialChar ~
4449 -c\SpecialChar ~
4450 foo2.c
4451 \family default
4452 \series default
4453
4454 \newline
4455
4456 \newline
4457 Then compile the source file containing the
4458 \emph on
4459 main()
4460 \emph default
4461  function and link
4462 \begin_inset LatexCommand \index{Linker}
4463
4464 \end_inset
4465
4466  the files together with the following command:
4467 \newline
4468
4469 \newline
4470
4471 \family sans
4472 \series bold
4473 sdcc\SpecialChar ~
4474 foomain.c\SpecialChar ~
4475 foo1.rel\SpecialChar ~
4476 foo2.rel
4477 \family default
4478 \series default
4479
4480 \begin_inset LatexCommand \index{<file>.rel}
4481
4482 \end_inset
4483
4484
4485 \newline
4486
4487 \newline
4488 Alternatively,
4489 \emph on
4490 foomain.c
4491 \emph default
4492 can be separately compiled as well:
4493 \family sans
4494 \series bold
4495
4496 \newline
4497
4498 \newline
4499 sdcc\SpecialChar ~
4500 -c\SpecialChar ~
4501 foomain.c
4502 \newline
4503 sdcc foomain.rel foo1.rel foo2.rel
4504 \newline
4505
4506 \newline
4507
4508 \family default
4509 \series default
4510 The file containing the
4511 \emph on
4512 main()
4513 \emph default
4514  function
4515 \emph on
4516
4517 \emph default
4518 \noun on
4519 must
4520 \noun default
4521  be the
4522 \noun on
4523 first
4524 \noun default
4525  file specified in the command line, since the linkage editor processes
4526  file in the order they are presented to it.
4527  The linker is invoked from SDCC using a script file with extension .lnk
4528 \begin_inset LatexCommand \index{<file>.lnk}
4529
4530 \end_inset
4531
4532 .
4533  You can view this file to troubleshoot linking problems such as those arising
4534  from missing libraries.
4535 \layout Subsection
4536
4537 Projects with Additional Libraries
4538 \begin_inset LatexCommand \index{Libraries}
4539
4540 \end_inset
4541
4542
4543 \layout Standard
4544
4545 Some reusable routines may be compiled into a library, see the documentation
4546  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4547  for how to create a
4548 \emph on
4549 .lib
4550 \begin_inset LatexCommand \index{<file>.lib}
4551
4552 \end_inset
4553
4554
4555 \emph default
4556  library file.
4557  Libraries created in this manner can be included in the command line.
4558  Make sure you include the -L <library-path> option to tell the linker where
4559  to look for these files if they are not in the current directory.
4560  Here is an example, assuming you have the source file
4561 \emph on
4562 foomain.c
4563 \emph default
4564  and a library
4565 \emph on
4566  foolib.lib
4567 \emph default
4568  in the directory
4569 \emph on
4570 mylib
4571 \emph default
4572  (if that is not the same as your current project):
4573 \newline
4574
4575 \newline
4576
4577 \family sans
4578 \series bold
4579 sdcc foomain.c foolib.lib -L mylib
4580 \newline
4581
4582 \newline
4583
4584 \family default
4585 \series default
4586 Note here that
4587 \emph on
4588  mylib
4589 \emph default
4590  must be an absolute path name.
4591 \newline
4592
4593 \newline
4594 The most efficient way to use libraries is to keep separate modules in separate
4595  source files.
4596  The lib file now should name all the modules.rel
4597 \begin_inset LatexCommand \index{<file>.rel}
4598
4599 \end_inset
4600
4601  files.
4602  For an example see the standard library file
4603 \emph on
4604 libsdcc.lib
4605 \emph default
4606  in the directory <installdir>/share/lib/small.
4607 \layout Subsection
4608
4609 Using sdcclib to Create and Manage Libraries
4610 \begin_inset LatexCommand \index{sdcclib}
4611
4612 \end_inset
4613
4614
4615 \layout Standard
4616
4617 Alternatively, instead of having a .rel file for each entry on the library
4618  file as described in the preceding section, sdcclib can be used to embed
4619  all the modules belonging to such library in the library file itself.
4620  This results in a larger library file, but it greatly reduces the number
4621  of disk files accessed by the linker.
4622   Additionally, the packed library file contains an index of all include
4623  modules and symbols that significantly speeds up the linking process.
4624  To display a list of options supported by sdcclib type:
4625 \newline
4626
4627 \layout Standard
4628
4629
4630 \family sans
4631 \series bold
4632 sdcclib -?
4633 \begin_inset LatexCommand \index{sdcclib}
4634
4635 \end_inset
4636
4637
4638 \newline
4639
4640 \newline
4641
4642 \family default
4643 \series default
4644 To create a new library file, start by compiling all the required modules.
4645  For example:
4646 \newline
4647
4648 \layout Standard
4649
4650
4651 \series bold
4652 sdcc -c _divsint.c
4653 \layout Standard
4654
4655
4656 \series bold
4657 sdcc -c _divuint.c
4658 \layout Standard
4659
4660
4661 \series bold
4662 sdcc -c _modsint.c
4663 \layout Standard
4664
4665
4666 \series bold
4667 sdcc -c _moduint.c
4668 \layout Standard
4669
4670
4671 \series bold
4672 sdcc -c _mulint.c
4673 \newline
4674
4675 \layout Standard
4676
4677 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4678  and _mulint.rel.
4679  The next step is to add the .rel files to the library file:
4680 \newline
4681
4682 \layout Standard
4683
4684
4685 \series bold
4686 sdcclib libint.lib _divsint.rel
4687 \begin_inset LatexCommand \index{sdcclib}
4688
4689 \end_inset
4690
4691
4692 \layout Standard
4693
4694
4695 \series bold
4696 sdcclib libint.lib _divuint.rel
4697 \layout Standard
4698
4699
4700 \series bold
4701 sdcclib libint.lib _modsint.rel
4702 \layout Standard
4703
4704
4705 \series bold
4706 sdcclib libint.lib _moduint.rel
4707 \layout Standard
4708
4709
4710 \series bold
4711 sdcclib libint.lib _mulint.rel
4712 \series default
4713
4714 \newline
4715
4716 \layout Standard
4717
4718 If the file already exists in the library, it will be replaced.
4719  To see what modules and symbols are included in the library, options -s
4720  and -m are available.
4721  For example:
4722 \newline
4723
4724 \newline
4725
4726 \series bold
4727 sdcclib -s libint.lib
4728 \begin_inset LatexCommand \index{sdcclib}
4729
4730 \end_inset
4731
4732
4733 \newline
4734 _divsint.rel:
4735 \layout Standard
4736
4737
4738 \series bold
4739 __divsint_a_1_1
4740 \layout Standard
4741
4742
4743 \series bold
4744 __divsint_PARM_2
4745 \layout Standard
4746
4747
4748 \series bold
4749 __divsint
4750 \newline
4751 _divuint.rel:
4752 \layout Standard
4753
4754
4755 \series bold
4756 __divuint_a_1_1
4757 \layout Standard
4758
4759
4760 \series bold
4761 __divuint_PARM_2
4762 \layout Standard
4763
4764
4765 \series bold
4766 __divuint_reste_1_1
4767 \layout Standard
4768
4769
4770 \series bold
4771 __divuint_count_1_1
4772 \layout Standard
4773
4774
4775 \series bold
4776 __divuint
4777 \newline
4778 _modsint.rel:
4779 \layout Standard
4780
4781
4782 \series bold
4783 __modsint_a_1_1
4784 \layout Standard
4785
4786
4787 \series bold
4788 __modsint_PARM_2
4789 \layout Standard
4790
4791
4792 \series bold
4793 __modsint
4794 \newline
4795 _moduint.rel:
4796 \layout Standard
4797
4798
4799 \series bold
4800 __moduint_a_1_1
4801 \layout Standard
4802
4803
4804 \series bold
4805 __moduint_PARM_2
4806 \layout Standard
4807
4808
4809 \series bold
4810 __moduint_count_1_1
4811 \layout Standard
4812
4813
4814 \series bold
4815 __moduint
4816 \newline
4817 _mulint.rel:
4818 \layout Standard
4819
4820
4821 \series bold
4822 __mulint_PARM_2
4823 \layout Standard
4824
4825
4826 \series bold
4827 __mulint
4828 \newline
4829
4830 \layout Standard
4831
4832 If the source files are compiled using --debug, the corresponding debug
4833  information file .adb will be include in the library file as well.
4834  The library files created with sdcclib are plain text files, so they can
4835  be viewed with a text editor.
4836  It is not recomended to modify a library file created with sdcclib using
4837  a text editor, as there are file indexes numbers located accross the file
4838  used by the linker to quickly locate the required module to link.
4839  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
4840  it can be safely deleted, since all the information required for linking
4841  is embedded in the library file itself.
4842  Library files created using sdcclib are used as described in the preceding
4843  sections.
4844 \layout Section
4845
4846 Command Line Options
4847 \begin_inset LatexCommand \index{Command Line Options}
4848
4849 \end_inset
4850
4851
4852 \layout Subsection
4853
4854 Processor Selection Options
4855 \begin_inset LatexCommand \index{Options processor selection}
4856
4857 \end_inset
4858
4859
4860 \begin_inset LatexCommand \index{Processor selection options}
4861
4862 \end_inset
4863
4864
4865 \layout List
4866 \labelwidthstring 00.00.0000
4867
4868
4869 \series bold
4870 -mmcs51
4871 \begin_inset LatexCommand \index{-mmcs51}
4872
4873 \end_inset
4874
4875
4876 \series default
4877  Generate code for the Intel MCS51
4878 \begin_inset LatexCommand \index{MCS51}
4879
4880 \end_inset
4881
4882  family of processors.
4883  This is the default processor target.
4884 \layout List
4885 \labelwidthstring 00.00.0000
4886
4887
4888 \series bold
4889 -mds390
4890 \begin_inset LatexCommand \index{-mds390}
4891
4892 \end_inset
4893
4894
4895 \series default
4896  Generate code for the Dallas DS80C390
4897 \begin_inset LatexCommand \index{DS80C390}
4898
4899 \end_inset
4900
4901  processor.
4902 \layout List
4903 \labelwidthstring 00.00.0000
4904
4905
4906 \series bold
4907 -mds400
4908 \begin_inset LatexCommand \index{-mds400}
4909
4910 \end_inset
4911
4912
4913 \series default
4914  Generate code for the Dallas DS80C400
4915 \begin_inset LatexCommand \index{DS80C400}
4916
4917 \end_inset
4918
4919  processor.
4920 \layout List
4921 \labelwidthstring 00.00.0000
4922
4923
4924 \series bold
4925 -mhc08
4926 \begin_inset LatexCommand \index{-mhc08}
4927
4928 \end_inset
4929
4930
4931 \series default
4932  Generate code for the Motorola HC08
4933 \begin_inset LatexCommand \index{HC08}
4934
4935 \end_inset
4936
4937  family of processors (added Oct 2003).
4938 \layout List
4939 \labelwidthstring 00.00.0000
4940
4941
4942 \series bold
4943 -mz80
4944 \begin_inset LatexCommand \index{-mz80}
4945
4946 \end_inset
4947
4948
4949 \series default
4950  Generate code for the Zilog Z80
4951 \begin_inset LatexCommand \index{Z80}
4952
4953 \end_inset
4954
4955  family of processors.
4956 \layout List
4957 \labelwidthstring 00.00.0000
4958
4959
4960 \series bold
4961 -mgbz80
4962 \begin_inset LatexCommand \index{-mgbz80}
4963
4964 \end_inset
4965
4966
4967 \series default
4968  Generate code for the GameBoy Z80
4969 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
4970
4971 \end_inset
4972
4973  processor (Not actively maintained).
4974 \layout List
4975 \labelwidthstring 00.00.0000
4976
4977
4978 \series bold
4979 -mavr
4980 \begin_inset LatexCommand \index{-mavr}
4981
4982 \end_inset
4983
4984
4985 \series default
4986  Generate code for the Atmel AVR
4987 \begin_inset LatexCommand \index{AVR}
4988
4989 \end_inset
4990
4991  processor (In development, not complete).
4992  AVR users should probably have a look at avr-gcc
4993 \begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
4994
4995 \end_inset
4996
4997 .
4998 \layout Comment
4999
5000 I think it is fair to direct users there for now.
5001  Open source is also about avoiding unnecessary work .
5002  But I didn't find the 'official' link.
5003 \layout List
5004 \labelwidthstring 00.00.0000
5005
5006
5007 \series bold
5008 -mpic14
5009 \begin_inset LatexCommand \index{-mpic14}
5010
5011 \end_inset
5012
5013
5014 \series default
5015  Generate code for the Microchip PIC 14
5016 \begin_inset LatexCommand \index{PIC14}
5017
5018 \end_inset
5019
5020 -bit processors (p16f84 and variants.
5021  In development, not complete).
5022 \layout Comment
5023
5024 p16f627 p16f628 p16f84 p16f873 p16f877?
5025 \layout List
5026 \labelwidthstring 00.00.0000
5027
5028
5029 \series bold
5030 -mpic16
5031 \begin_inset LatexCommand \index{-mpic16}
5032
5033 \end_inset
5034
5035
5036 \series default
5037  Generate code for the Microchip PIC 16
5038 \begin_inset LatexCommand \index{PIC16}
5039
5040 \end_inset
5041
5042 -bit processors (p18f452 and variants.
5043  In development, not complete).
5044 \layout List
5045 \labelwidthstring 00.00.0000
5046
5047
5048 \series bold
5049 -mtlcs900h
5050 \series default
5051  Generate code for the Toshiba TLCS-900H
5052 \begin_inset LatexCommand \index{TLCS-900H}
5053
5054 \end_inset
5055
5056  processor (Not maintained, not complete).
5057 \layout List
5058 \labelwidthstring 00.00.0000
5059
5060
5061 \series bold
5062 -mxa51
5063 \begin_inset LatexCommand \index{-mxa51}
5064
5065 \end_inset
5066
5067
5068 \series default
5069  Generate code for the Phillips XA51
5070 \begin_inset LatexCommand \index{XA51}
5071
5072 \end_inset
5073
5074  processor (Not maintained, not complete).
5075 \layout Subsection
5076
5077 Preprocessor Options
5078 \begin_inset LatexCommand \index{Options preprocessor}
5079
5080 \end_inset
5081
5082
5083 \begin_inset LatexCommand \index{Preprocessor options}
5084
5085 \end_inset
5086
5087
5088 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5089
5090 \end_inset
5091
5092
5093 \layout List
5094 \labelwidthstring 00.00.0000
5095
5096
5097 \series bold
5098 -I<path>
5099 \begin_inset LatexCommand \index{-I<path>}
5100
5101 \end_inset
5102
5103
5104 \series default
5105  The additional location where the pre processor will look for <..h> or
5106 \begin_inset Quotes eld
5107 \end_inset
5108
5109 ..h
5110 \begin_inset Quotes erd
5111 \end_inset
5112
5113  files.
5114 \layout List
5115 \labelwidthstring 00.00.0000
5116
5117
5118 \series bold
5119 -D<macro[=value]>
5120 \begin_inset LatexCommand \index{-D<macro[=value]>}
5121
5122 \end_inset
5123
5124
5125 \series default
5126  Command line definition of macros.
5127  Passed to the preprocessor.
5128 \layout List
5129 \labelwidthstring 00.00.0000
5130
5131
5132 \series bold
5133 -M
5134 \begin_inset LatexCommand \index{-M}
5135
5136 \end_inset
5137
5138
5139 \series default
5140  Tell the preprocessor to output a rule suitable for make describing the
5141  dependencies of each object file.
5142  For each source file, the preprocessor outputs one make-rule whose target
5143  is the object file name for that source file and whose dependencies are
5144  all the files `#include'd in it.
5145  This rule may be a single line or may be continued with `
5146 \backslash
5147 '-newline if it is long.
5148  The list of rules is printed on standard output instead of the preprocessed
5149  C program.
5150  `-M' implies `-E
5151 \begin_inset LatexCommand \index{-E}
5152
5153 \end_inset
5154
5155 '.
5156 \layout List
5157 \labelwidthstring 00.00.0000
5158
5159
5160 \series bold
5161 -C
5162 \begin_inset LatexCommand \index{-C}
5163
5164 \end_inset
5165
5166
5167 \series default
5168  Tell the preprocessor not to discard comments.
5169  Used with the `-E' option.
5170 \layout List
5171 \labelwidthstring 00.00.0000
5172
5173
5174 \series bold
5175 -MM
5176 \begin_inset LatexCommand \index{-MM}
5177
5178 \end_inset
5179
5180
5181 \size large
5182 \bar under
5183
5184 \series default
5185 \size default
5186 \bar default
5187 Like `-M' but the output mentions only the user header files included with
5188  `#include
5189 \begin_inset Quotes eld
5190 \end_inset
5191
5192 file"'.
5193  System header files included with `#include <file>' are omitted.
5194 \layout List
5195 \labelwidthstring 00.00.0000
5196
5197
5198 \series bold
5199 -Aquestion(answer)
5200 \begin_inset LatexCommand \index{-Aquestion(answer)}
5201
5202 \end_inset
5203
5204
5205 \series default
5206  Assert the answer answer for question, in case it is tested with a preprocessor
5207  conditional such as `#if #question(answer)'.
5208  `-A-' disables the standard assertions that normally describe the target
5209  machine.
5210 \layout List
5211 \labelwidthstring 00.00.0000
5212
5213
5214 \series bold
5215 -Umacro
5216 \begin_inset LatexCommand \index{-Umacro}
5217
5218 \end_inset
5219
5220
5221 \series default
5222  Undefine macro macro.
5223  `-U' options are evaluated after all `-D' options, but before any `-include'
5224  and `-imacros' options.
5225 \layout List
5226 \labelwidthstring 00.00.0000
5227
5228
5229 \series bold
5230 -dM
5231 \begin_inset LatexCommand \index{-dM}
5232
5233 \end_inset
5234
5235
5236 \series default
5237  Tell the preprocessor to output only a list of the macro definitions that
5238  are in effect at the end of preprocessing.
5239  Used with the `-E' option.
5240 \layout List
5241 \labelwidthstring 00.00.0000
5242
5243
5244 \series bold
5245 -dD
5246 \begin_inset LatexCommand \index{-dD}
5247
5248 \end_inset
5249
5250
5251 \series default
5252  Tell the preprocessor to pass all macro definitions into the output, in
5253  their proper sequence in the rest of the output.
5254 \layout List
5255 \labelwidthstring 00.00.0000
5256
5257
5258 \series bold
5259 -dN
5260 \begin_inset LatexCommand \index{-dN}
5261
5262 \end_inset
5263
5264
5265 \size large
5266 \bar under
5267
5268 \series default
5269 \size default
5270 \bar default
5271 Like `-dD' except that the macro arguments and contents are omitted.
5272  Only `#define name' is included in the output.
5273 \layout List
5274 \labelwidthstring 00.00.0000
5275
5276
5277 \series bold
5278 -Wp\SpecialChar ~
5279 preprocessorOption[,preprocessorOption]
5280 \series default
5281
5282 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5283
5284 \end_inset
5285
5286 ...
5287  Pass the preprocessorOption to the preprocessor
5288 \family typewriter
5289 sdcpp
5290 \family default
5291
5292 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5293
5294 \end_inset
5295
5296 .
5297  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5298  Collection (gcc), if you need more dedicated options please refer to the
5299  documentation at
5300 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5301
5302 \end_inset
5303
5304 .
5305 \layout Subsection
5306
5307 Linker Options
5308 \begin_inset LatexCommand \index{Options linker}
5309
5310 \end_inset
5311
5312
5313 \begin_inset LatexCommand \index{Linker options}
5314
5315 \end_inset
5316
5317
5318 \layout List
5319 \labelwidthstring 00.00.0000
5320
5321
5322 \series bold
5323 -L\SpecialChar ~
5324 -
5325 \series default
5326
5327 \begin_inset ERT
5328 status Collapsed
5329
5330 \layout Standard
5331
5332 \backslash
5333 /
5334 \end_inset
5335
5336
5337 \series bold
5338 -lib-path
5339 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5340
5341 \end_inset
5342
5343
5344 \begin_inset LatexCommand \index{-L -\/-lib-path}
5345
5346 \end_inset
5347
5348
5349 \series default
5350 \SpecialChar ~
5351 <absolute path to additional libraries> This option is passed to the linkage
5352  editor's additional libraries
5353 \begin_inset LatexCommand \index{Libraries}
5354
5355 \end_inset
5356
5357  search path.
5358  The path name must be absolute.
5359  Additional library files may be specified in the command line.
5360  See section Compiling programs for more details.
5361 \layout List
5362 \labelwidthstring 00.00.0000
5363
5364
5365 \series bold
5366 -
5367 \begin_inset ERT
5368 status Collapsed
5369
5370 \layout Standard
5371
5372 \backslash
5373 /
5374 \end_inset
5375
5376 -xram-loc
5377 \series default
5378
5379 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5380
5381 \end_inset
5382
5383 \SpecialChar ~
5384 <Value> The start location of the external ram
5385 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5386
5387 \end_inset
5388
5389 , default value is 0.
5390  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5391 \begin_inset ERT
5392 status Collapsed
5393
5394 \layout Standard
5395
5396 \backslash
5397 /
5398 \end_inset
5399
5400 -xram-loc 0x8000 or -
5401 \begin_inset ERT
5402 status Collapsed
5403
5404 \layout Standard
5405
5406 \backslash
5407 /
5408 \end_inset
5409
5410 -xram-loc 32768.
5411 \layout List
5412 \labelwidthstring 00.00.0000
5413
5414
5415 \series bold
5416 -
5417 \begin_inset ERT
5418 status Collapsed
5419
5420 \layout Standard
5421
5422 \backslash
5423 /
5424 \end_inset
5425
5426 -code-loc
5427 \series default
5428
5429 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5430
5431 \end_inset
5432
5433 \SpecialChar ~
5434 <Value> The start location of the code
5435 \begin_inset LatexCommand \index{code}
5436
5437 \end_inset
5438
5439  segment, default value 0.
5440  Note when this option is used the interrupt vector table is also relocated
5441  to the given address.
5442  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5443 \begin_inset ERT
5444 status Collapsed
5445
5446 \layout Standard
5447
5448 \backslash
5449 /
5450 \end_inset
5451
5452 -code-loc 0x8000 or -
5453 \begin_inset ERT
5454 status Collapsed
5455
5456 \layout Standard
5457
5458 \backslash
5459 /
5460 \end_inset
5461
5462 -code-loc 32768.
5463 \layout List
5464 \labelwidthstring 00.00.0000
5465
5466
5467 \series bold
5468 -
5469 \begin_inset ERT
5470 status Collapsed
5471
5472 \layout Standard
5473
5474 \backslash
5475 /
5476 \end_inset
5477
5478 -stack-loc
5479 \series default
5480
5481 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5482
5483 \end_inset
5484
5485 \SpecialChar ~
5486 <Value> By default the stack
5487 \begin_inset LatexCommand \index{stack}
5488
5489 \end_inset
5490
5491  is placed after the data segment.
5492  Using this option the stack can be placed anywhere in the internal memory
5493  space of the 8051.
5494  The value entered can be in Hexadecimal or Decimal format, e.g.
5495  -
5496 \begin_inset ERT
5497 status Collapsed
5498
5499 \layout Standard
5500
5501 \backslash
5502 /
5503 \end_inset
5504
5505 -stack-loc 0x20 or -
5506 \begin_inset ERT
5507 status Collapsed
5508
5509 \layout Standard
5510
5511 \backslash
5512 /
5513 \end_inset
5514
5515 -stack-loc 32.
5516  Since the sp register is incremented before a push or call, the initial
5517  sp will be set to one byte prior the provided value.
5518  The provided value should not overlap any other memory areas such as used
5519  register banks or the data segment and with enough space for the current
5520  application.
5521 \layout List
5522 \labelwidthstring 00.00.0000
5523
5524
5525 \series bold
5526 -
5527 \begin_inset ERT
5528 status Collapsed
5529
5530 \layout Standard
5531
5532 \backslash
5533 /
5534 \end_inset
5535
5536 -data-loc
5537 \series default
5538
5539 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5540
5541 \end_inset
5542
5543 \SpecialChar ~
5544 <Value> The start location of the internal ram data
5545 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5546
5547 \end_inset
5548
5549  segment.
5550  The value entered can be in Hexadecimal or Decimal format, eg.
5551  -
5552 \begin_inset ERT
5553 status Collapsed
5554
5555 \layout Standard
5556
5557 \backslash
5558 /
5559 \end_inset
5560
5561 -data-loc 0x20 or -
5562 \begin_inset ERT
5563 status Collapsed
5564
5565 \layout Standard
5566
5567 \backslash
5568 /
5569 \end_inset
5570
5571 -data-loc 32.
5572  (By default, the start location of the internal ram data segment  is set
5573  as low as possible in memory, taking into account the used register banks
5574  and the bit segment at address 0x20.
5575  For example if register banks 0 and 1 are used without bit variables, the
5576  data segment will be set, if -
5577 \begin_inset ERT
5578 status Collapsed
5579
5580 \layout Standard
5581
5582 \backslash
5583 /
5584 \end_inset
5585
5586 -data-loc is not used, to location 0x10.)
5587 \layout List
5588 \labelwidthstring 00.00.0000
5589
5590
5591 \series bold
5592 -
5593 \begin_inset ERT
5594 status Collapsed
5595
5596 \layout Standard
5597
5598 \backslash
5599 /
5600 \end_inset
5601
5602 -idata-loc
5603 \series default
5604
5605 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5606
5607 \end_inset
5608
5609 \SpecialChar ~
5610 <Value> The start location of the indirectly addressable internal ram
5611 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5612
5613 \end_inset
5614
5615  of the 8051, default value is 0x80.
5616  The value entered can be in Hexadecimal or Decimal format, eg.
5617  -
5618 \begin_inset ERT
5619 status Collapsed
5620
5621 \layout Standard
5622
5623 \backslash
5624 /
5625 \end_inset
5626
5627 -idata-loc 0x88 or -
5628 \begin_inset ERT
5629 status Collapsed
5630
5631 \layout Standard
5632
5633 \backslash
5634 /
5635 \end_inset
5636
5637 -idata-loc 136.
5638 \layout List
5639 \labelwidthstring 00.00.0000
5640
5641
5642 \series bold
5643 -
5644 \begin_inset ERT
5645 status Collapsed
5646
5647 \layout Standard
5648
5649 \backslash
5650 /
5651 \end_inset
5652
5653 -bit-loc
5654 \series default
5655 \SpecialChar ~
5656 <Value> The start location of the bit
5657 \begin_inset LatexCommand \index{bit}
5658
5659 \end_inset
5660
5661  addressable internal ram of the 8051.
5662  This is
5663 \emph on
5664 not
5665 \emph default
5666  implemented yet.
5667  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5668 -bBSEG=<Value>.
5669 \layout List
5670 \labelwidthstring 00.00.0000
5671
5672
5673 \series bold
5674 -
5675 \begin_inset ERT
5676 status Collapsed
5677
5678 \layout Standard
5679
5680 \backslash
5681 /
5682 \end_inset
5683
5684 -out-fmt-ihx
5685 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5686
5687 \end_inset
5688
5689
5690 \bar under
5691
5692 \series default
5693 \bar default
5694 The linker output (final object code) is in Intel Hex format.
5695 \begin_inset LatexCommand \index{Intel hex format}
5696
5697 \end_inset
5698
5699  This is the default option.
5700  The format itself is documented in the documentation of srecord
5701 \begin_inset LatexCommand \index{srecord (tool)}
5702
5703 \end_inset
5704
5705 .
5706 \layout List
5707 \labelwidthstring 00.00.0000
5708
5709
5710 \series bold
5711 -
5712 \begin_inset ERT
5713 status Collapsed
5714
5715 \layout Standard
5716
5717 \backslash
5718 /
5719 \end_inset
5720
5721 -out-fmt-s19
5722 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5723
5724 \end_inset
5725
5726
5727 \bar under
5728
5729 \series default
5730 \bar default
5731 The linker output (final object code) is in Motorola S19 format
5732 \begin_inset LatexCommand \index{Motorola S19 format}
5733
5734 \end_inset
5735
5736 .
5737  The format itself is documented in the documentation of srecord.
5738 \layout List
5739 \labelwidthstring 00.00.0000
5740
5741
5742 \series bold
5743 -Wl\SpecialChar ~
5744 linkOption[,linkOption]
5745 \series default
5746
5747 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5748
5749 \end_inset
5750
5751 ...
5752  Pass the linkOption to the linker.
5753  See file sdcc/as/doc/asxhtm.html for more on linker options.
5754 \layout Subsection
5755
5756 MCS51 Options
5757 \begin_inset LatexCommand \index{Options MCS51}
5758
5759 \end_inset
5760
5761
5762 \begin_inset LatexCommand \index{MCS51 options}
5763
5764 \end_inset
5765
5766
5767 \layout List
5768 \labelwidthstring 00.00.0000
5769
5770
5771 \series bold
5772 -
5773 \begin_inset ERT
5774 status Collapsed
5775
5776 \layout Standard
5777
5778 \backslash
5779 /
5780 \end_inset
5781
5782 -model-small
5783 \begin_inset LatexCommand \index{-\/-model-small}
5784
5785 \end_inset
5786
5787
5788 \series default
5789 \size large
5790 \emph on
5791
5792 \size default
5793 \emph default
5794 Generate code for Small Model programs, see section Memory Models for more
5795  details.
5796  This is the default model.
5797 \layout List
5798 \labelwidthstring 00.00.0000
5799
5800
5801 \series bold
5802 -
5803 \begin_inset ERT
5804 status Collapsed
5805
5806 \layout Standard
5807
5808 \backslash
5809 /
5810 \end_inset
5811
5812 -model-large
5813 \begin_inset LatexCommand \index{-\/-model-large}
5814
5815 \end_inset
5816
5817
5818 \series default
5819  Generate code for Large model programs, see section Memory Models for more
5820  details.
5821  If this option is used all source files in the project have to be compiled
5822  with this option.
5823 \layout List
5824 \labelwidthstring 00.00.0000
5825
5826
5827 \series bold
5828 -
5829 \begin_inset ERT
5830 status Collapsed
5831
5832 \layout Standard
5833
5834 \backslash
5835 /
5836 \end_inset
5837
5838 -xstack
5839 \begin_inset LatexCommand \index{-\/-xstack}
5840
5841 \end_inset
5842
5843
5844 \series default
5845  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5846  variables and passing parameters.
5847  See section
5848 \begin_inset LatexCommand \ref{sub:External-Stack}
5849
5850 \end_inset
5851
5852 \SpecialChar ~
5853  External Stack for more details.
5854 \layout List
5855 \labelwidthstring 00.00.0000
5856
5857
5858 \series bold
5859 -
5860 \begin_inset ERT
5861 status Collapsed
5862
5863 \layout Standard
5864
5865 \backslash
5866 /
5867 \end_inset
5868
5869 -iram-size
5870 \series default
5871 \SpecialChar ~
5872 <Value>
5873 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
5874
5875 \end_inset
5876
5877  Causes the linker to check if the internal ram usage is within limits of
5878  the given value.
5879 \layout List
5880 \labelwidthstring 00.00.0000
5881
5882
5883 \series bold
5884 -
5885 \begin_inset ERT
5886 status Collapsed
5887
5888 \layout Standard
5889
5890 \backslash
5891 /
5892 \end_inset
5893
5894 -xram-size
5895 \series default
5896 \SpecialChar ~
5897 <Value>
5898 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
5899
5900 \end_inset
5901
5902  Causes the linker to check if the external ram usage is within limits of
5903  the given value.
5904 \layout List
5905 \labelwidthstring 00.00.0000
5906
5907
5908 \series bold
5909 -
5910 \begin_inset ERT
5911 status Collapsed
5912
5913 \layout Standard
5914
5915 \backslash
5916 /
5917 \end_inset
5918
5919 -code-size
5920 \series default
5921 \SpecialChar ~
5922 <Value>
5923 \begin_inset LatexCommand \index{-\/-code-size <Value>}
5924
5925 \end_inset
5926
5927  Causes the linker to check if the code memory usage is within limits of
5928  the given value.
5929 \layout List
5930 \labelwidthstring 00.00.0000
5931
5932
5933 \series bold
5934 -
5935 \begin_inset ERT
5936 status Collapsed
5937
5938 \layout Standard
5939
5940 \backslash
5941 /
5942 \end_inset
5943
5944 -stack-size
5945 \series default
5946 \SpecialChar ~
5947 <Value>
5948 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
5949
5950 \end_inset
5951
5952  Causes the linker to check if there is at minimum <Value> bytes for stack.
5953 \layout List
5954 \labelwidthstring 00.00.0000
5955
5956
5957 \series bold
5958 -
5959 \begin_inset ERT
5960 status Collapsed
5961
5962 \layout Standard
5963
5964 \backslash
5965 /
5966 \end_inset
5967
5968 -pack-iram
5969 \series default
5970 \SpecialChar ~
5971
5972 \begin_inset LatexCommand \index{-\/-pack-iram}
5973
5974 \end_inset
5975
5976  Causes the linker use unused register banks for data variables or stack.
5977 \layout Subsection
5978
5979 DS390 / DS400 Options
5980 \begin_inset LatexCommand \index{Options DS390}
5981
5982 \end_inset
5983
5984
5985 \begin_inset LatexCommand \index{DS390 options}
5986
5987 \end_inset
5988
5989
5990 \layout List
5991 \labelwidthstring 00.00.0000
5992
5993
5994 \series bold
5995 -
5996 \begin_inset ERT
5997 status Collapsed
5998
5999 \layout Standard
6000
6001 \backslash
6002 /
6003 \end_inset
6004
6005 -model-flat24
6006 \series default
6007
6008 \begin_inset LatexCommand \index{-\/-model-flat24}
6009
6010 \end_inset
6011
6012
6013 \size large
6014 \emph on
6015
6016 \size default
6017 \emph default
6018 Generate 24-bit flat mode code.
6019  This is the one and only that the ds390 code generator supports right now
6020  and is default when using
6021 \emph on
6022 -mds390
6023 \emph default
6024 .
6025  See section Memory Models for more details.
6026 \layout List
6027 \labelwidthstring 00.00.0000
6028
6029
6030 \series bold
6031 -
6032 \begin_inset ERT
6033 status Collapsed
6034
6035 \layout Standard
6036
6037 \backslash
6038 /
6039 \end_inset
6040
6041 -protect-sp-update
6042 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6043
6044 \end_inset
6045
6046
6047 \series default
6048  disable interrupts during ESP:SP updates.
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 -stack-10bit
6065 \series default
6066
6067 \begin_inset LatexCommand \index{-\/-stack-10bit}
6068
6069 \end_inset
6070
6071  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6072  This is the one and only that the ds390 code generator supports right now
6073  and is default when using
6074 \emph on
6075 -mds390
6076 \emph default
6077 .
6078  In this mode, the stack is located in the lower 1K of the internal RAM,
6079  which is mapped to 0x400000.
6080  Note that the support is incomplete, since it still uses a single byte
6081  as the stack pointer.
6082  This means that only the lower 256 bytes of the potential 1K stack space
6083  will actually be used.
6084  However, this does allow you to reclaim the precious 256 bytes of low RAM
6085  for use for the DATA and IDATA segments.
6086  The compiler will not generate any code to put the processor into 10 bit
6087  stack mode.
6088  It is important to ensure that the processor is in this mode before calling
6089  any re-entrant functions compiled with this option.
6090  In principle, this should work with the
6091 \emph on
6092 -
6093 \begin_inset ERT
6094 status Collapsed
6095
6096 \layout Standard
6097
6098 \backslash
6099 /
6100 \end_inset
6101
6102 -stack-auto
6103 \begin_inset LatexCommand \index{-\/-stack-auto}
6104
6105 \end_inset
6106
6107
6108 \emph default
6109  option, but that has not been tested.
6110  It is incompatible with the
6111 \emph on
6112 -
6113 \begin_inset ERT
6114 status Collapsed
6115
6116 \layout Standard
6117
6118 \backslash
6119 /
6120 \end_inset
6121
6122 -xstack
6123 \begin_inset LatexCommand \index{-\/-xstack}
6124
6125 \end_inset
6126
6127
6128 \emph default
6129  option.
6130  It also only makes sense if the processor is in 24 bit contiguous addressing
6131  mode (see the
6132 \emph on
6133 -
6134 \begin_inset ERT
6135 status Collapsed
6136
6137 \layout Standard
6138
6139 \backslash
6140 /
6141 \end_inset
6142
6143 -model-flat24 option
6144 \emph default
6145 ).
6146 \layout List
6147 \labelwidthstring 00.00.0000
6148
6149
6150 \series bold
6151 -
6152 \begin_inset ERT
6153 status Collapsed
6154
6155 \layout Standard
6156
6157 \backslash
6158 /
6159 \end_inset
6160
6161 -stack-probe
6162 \begin_inset LatexCommand \index{-\/-stack-probe}
6163
6164 \end_inset
6165
6166
6167 \series default
6168  insert call to function __stack_probe at each function prologue.
6169 \layout List
6170 \labelwidthstring 00.00.0000
6171
6172
6173 \series bold
6174 -
6175 \begin_inset ERT
6176 status Collapsed
6177
6178 \layout Standard
6179
6180 \backslash
6181 /
6182 \end_inset
6183
6184 -tini-libid
6185 \begin_inset LatexCommand \index{-\/-tini-libid}
6186
6187 \end_inset
6188
6189
6190 \series default
6191  <nnnn> LibraryID used in -mTININative.
6192
6193 \layout List
6194 \labelwidthstring 00.00.0000
6195
6196
6197 \series bold
6198 -
6199 \begin_inset ERT
6200 status Collapsed
6201
6202 \layout Standard
6203
6204 \backslash
6205 /
6206 \end_inset
6207
6208 -use-accelerator
6209 \begin_inset LatexCommand \index{-\/-use-accelerator}
6210
6211 \end_inset
6212
6213
6214 \series default
6215  generate code for DS390 Arithmetic Accelerator.
6216
6217 \layout Subsection
6218
6219 Z80 Options
6220 \begin_inset LatexCommand \index{Options Z80}
6221
6222 \end_inset
6223
6224
6225 \begin_inset LatexCommand \index{Z80 options}
6226
6227 \end_inset
6228
6229
6230 \layout List
6231 \labelwidthstring 00.00.0000
6232
6233
6234 \series bold
6235 -
6236 \begin_inset ERT
6237 status Collapsed
6238
6239 \layout Standard
6240
6241 \backslash
6242 /
6243 \end_inset
6244
6245 -callee-saves-bc
6246 \series default
6247
6248 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6249
6250 \end_inset
6251
6252
6253 \size large
6254 \emph on
6255
6256 \size default
6257 \emph default
6258 Force a called function to always save BC.
6259 \layout List
6260 \labelwidthstring 00.00.0000
6261
6262
6263 \series bold
6264 -
6265 \begin_inset ERT
6266 status Collapsed
6267
6268 \layout Standard
6269
6270 \backslash
6271 /
6272 \end_inset
6273
6274 -no-std-crt0
6275 \series default
6276
6277 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6278
6279 \end_inset
6280
6281  When linking, skip the standard crt0.o object file.
6282  You must provide your own crt0.o for your system when linking.
6283
6284 \layout Subsection
6285
6286 Optimization Options
6287 \begin_inset LatexCommand \index{Options optimization}
6288
6289 \end_inset
6290
6291
6292 \begin_inset LatexCommand \index{Optimization options}
6293
6294 \end_inset
6295
6296
6297 \layout List
6298 \labelwidthstring 00.00.0000
6299
6300
6301 \series bold
6302 -
6303 \begin_inset ERT
6304 status Collapsed
6305
6306 \layout Standard
6307
6308 \backslash
6309 /
6310 \end_inset
6311
6312 -nogcse
6313 \begin_inset LatexCommand \index{-\/-nogcse}
6314
6315 \end_inset
6316
6317
6318 \series default
6319  Will not do global subexpression elimination, this option may be used when
6320  the compiler creates undesirably large stack/data spaces to store compiler
6321  temporaries.
6322  A warning message will be generated when this happens and the compiler
6323  will indicate the number of extra bytes it allocated.
6324  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6325 nogcse
6326 \begin_inset LatexCommand \index{\#pragma nogcse}
6327
6328 \end_inset
6329
6330  can be used to turn off global subexpression elimination
6331 \begin_inset LatexCommand \index{Subexpression elimination}
6332
6333 \end_inset
6334
6335  for a given function only.
6336 \layout List
6337 \labelwidthstring 00.00.0000
6338
6339
6340 \series bold
6341 -
6342 \begin_inset ERT
6343 status Collapsed
6344
6345 \layout Standard
6346
6347 \backslash
6348 /
6349 \end_inset
6350
6351 -noinvariant
6352 \begin_inset LatexCommand \index{-\/-noinvariant}
6353
6354 \end_inset
6355
6356
6357 \series default
6358  Will not do loop invariant optimizations, this may be turned off for reasons
6359  explained for the previous option.
6360  For more details of loop optimizations performed see section Loop Invariants.
6361  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6362 noinvariant
6363 \begin_inset LatexCommand \index{\#pragma noinvariant}
6364
6365 \end_inset
6366
6367  can be used to turn off invariant optimizations for a given function only.
6368 \layout List
6369 \labelwidthstring 00.00.0000
6370
6371
6372 \series bold
6373 -
6374 \begin_inset ERT
6375 status Collapsed
6376
6377 \layout Standard
6378
6379 \backslash
6380 /
6381 \end_inset
6382
6383 -noinduction
6384 \begin_inset LatexCommand \index{-\/-noinduction}
6385
6386 \end_inset
6387
6388
6389 \series default
6390  Will not do loop induction optimizations, see section strength reduction
6391  for more details.
6392  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6393 noinduction
6394 \begin_inset LatexCommand \index{\#pragma noinduction}
6395
6396 \end_inset
6397
6398  can be used to turn off induction optimizations for a given function only.
6399 \layout List
6400 \labelwidthstring 00.00.0000
6401
6402
6403 \series bold
6404 -
6405 \begin_inset ERT
6406 status Collapsed
6407
6408 \layout Standard
6409
6410 \backslash
6411 /
6412 \end_inset
6413
6414 -nojtbound
6415 \begin_inset LatexCommand \index{-\/-nojtbound}
6416
6417 \end_inset
6418
6419
6420 \size large
6421 \bar under
6422
6423 \series default
6424 \size default
6425 \bar default
6426  Will not generate boundary condition check when switch statements
6427 \begin_inset LatexCommand \index{switch statement}
6428
6429 \end_inset
6430
6431  are implemented using jump-tables.
6432  See section
6433 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6434
6435 \end_inset
6436
6437 \SpecialChar ~
6438 Switch Statements for more details.
6439  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6440 nojtbound
6441 \begin_inset LatexCommand \index{\#pragma nojtbound}
6442
6443 \end_inset
6444
6445  can be used to turn off boundary checking for jump tables for a given function
6446  only.
6447 \layout List
6448 \labelwidthstring 00.00.0000
6449
6450
6451 \series bold
6452 -
6453 \begin_inset ERT
6454 status Collapsed
6455
6456 \layout Standard
6457
6458 \backslash
6459 /
6460 \end_inset
6461
6462 -noloopreverse
6463 \begin_inset LatexCommand \index{-\/-noloopreverse}
6464
6465 \end_inset
6466
6467
6468 \series default
6469 \size large
6470
6471 \size default
6472 Will not do loop reversal
6473 \begin_inset LatexCommand \index{Loop reversing}
6474
6475 \end_inset
6476
6477 optimization.
6478 \layout List
6479 \labelwidthstring 00.00.0000
6480
6481 -
6482 \begin_inset ERT
6483 status Collapsed
6484
6485 \layout Standard
6486
6487 \backslash
6488 /
6489 \end_inset
6490
6491 -
6492 \series bold
6493 nolabelopt
6494 \series default
6495
6496 \begin_inset LatexCommand \index{-\/-nolabelopt }
6497
6498 \end_inset
6499
6500 Will not optimize labels (makes the dumpfiles more readable).
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 -no-xinit-opt
6517 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6518
6519 \end_inset
6520
6521
6522 \series default
6523  Will not memcpy initialized data from code space into xdata space.
6524  This saves a few bytes in code space if you don't have initialized data.
6525 \layout List
6526 \labelwidthstring 00.00.0000
6527
6528
6529 \series bold
6530 -
6531 \begin_inset ERT
6532 status Collapsed
6533
6534 \layout Standard
6535
6536 \backslash
6537 /
6538 \end_inset
6539
6540 -nooverlay
6541 \begin_inset LatexCommand \index{-\/-nooverlay}
6542
6543 \end_inset
6544
6545
6546 \series default
6547   The compiler will not overlay parameters and local variables of any function,
6548  see section Parameters and local variables for more details.
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 -no-peep
6565 \begin_inset LatexCommand \index{-\/-no-peep}
6566
6567 \end_inset
6568
6569
6570 \series default
6571  Disable peep-hole optimization.
6572 \layout List
6573 \labelwidthstring 00.00.0000
6574
6575
6576 \series bold
6577 -
6578 \begin_inset ERT
6579 status Collapsed
6580
6581 \layout Standard
6582
6583 \backslash
6584 /
6585 \end_inset
6586
6587 -peep-file
6588 \series default
6589
6590 \begin_inset LatexCommand \index{-\/-peep-file}
6591
6592 \end_inset
6593
6594 \SpecialChar ~
6595 <filename> This option can be used to use additional rules to be used by
6596  the peep hole optimizer.
6597  See section
6598 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6599
6600 \end_inset
6601
6602 \SpecialChar ~
6603 Peep Hole optimizations for details on how to write these rules.
6604 \layout List
6605 \labelwidthstring 00.00.0000
6606
6607
6608 \series bold
6609 -
6610 \begin_inset ERT
6611 status Collapsed
6612
6613 \layout Standard
6614
6615 \backslash
6616 /
6617 \end_inset
6618
6619 -peep-asm
6620 \begin_inset LatexCommand \index{-\/-peep-asm}
6621
6622 \end_inset
6623
6624
6625 \series default
6626   Pass the inline assembler code through the peep hole optimizer.
6627  This can cause unexpected changes to inline assembler code, please go through
6628  the peephole optimizer
6629 \begin_inset LatexCommand \index{Peephole optimizer}
6630
6631 \end_inset
6632
6633  rules defined in the source file tree '<target>/peeph.def' before using
6634  this option.
6635 \layout Subsection
6636
6637 Other Options
6638 \begin_inset LatexCommand \index{Options other}
6639
6640 \end_inset
6641
6642
6643 \layout List
6644 \labelwidthstring 00.00.0000
6645
6646
6647 \series bold
6648 -c\SpecialChar ~
6649 -
6650 \begin_inset ERT
6651 status Collapsed
6652
6653 \layout Standard
6654
6655 \backslash
6656 /
6657 \end_inset
6658
6659 -compile-only
6660 \begin_inset LatexCommand \index{-\/-compile-only}
6661
6662 \end_inset
6663
6664
6665 \begin_inset LatexCommand \index{-c -\/-compile-only}
6666
6667 \end_inset
6668
6669
6670 \series default
6671  will compile and assemble the source, but will not call the linkage editor.
6672 \layout List
6673 \labelwidthstring 00.00.0000
6674
6675
6676 \series bold
6677 -
6678 \series default
6679
6680 \begin_inset ERT
6681 status Collapsed
6682
6683 \layout Standard
6684
6685 \backslash
6686 /
6687 \end_inset
6688
6689
6690 \series bold
6691 -c1mode
6692 \begin_inset LatexCommand \index{-\/-c1mode}
6693
6694 \end_inset
6695
6696
6697 \series default
6698  reads the preprocessed source from standard input and compiles it.
6699  The file name for the assembler output must be specified using the -o option.
6700 \layout List
6701 \labelwidthstring 00.00.0000
6702
6703
6704 \series bold
6705 -E
6706 \begin_inset LatexCommand \index{-E}
6707
6708 \end_inset
6709
6710
6711 \series default
6712  Run only the C preprocessor.
6713  Preprocess all the C source files specified and output the results to standard
6714  output.
6715 \layout List
6716 \labelwidthstring 00.00.0000
6717
6718
6719 \series bold
6720 -o\SpecialChar ~
6721 <path/file>
6722 \begin_inset LatexCommand \index{-o <path/file>}
6723
6724 \end_inset
6725
6726
6727 \series default
6728 The output path resp.
6729  file where everything will be placed.
6730  If the parameter is a path, it must have a trailing slash (or backslash
6731  for the Windows binaries) to be recognized as a path.
6732
6733 \layout List
6734 \labelwidthstring 00.00.0000
6735
6736
6737 \series bold
6738 -
6739 \begin_inset ERT
6740 status Collapsed
6741
6742 \layout Standard
6743
6744 \backslash
6745 /
6746 \end_inset
6747
6748 -stack-auto
6749 \begin_inset LatexCommand \index{-\/-stack-auto}
6750
6751 \end_inset
6752
6753
6754 \series default
6755 \size large
6756 \emph on
6757
6758 \size default
6759 \emph default
6760 All functions in the source file will be compiled as
6761 \emph on
6762 reentrant
6763 \emph default
6764
6765 \begin_inset LatexCommand \index{reentrant}
6766
6767 \end_inset
6768
6769 , i.e.
6770  the parameters and local variables will be allocated on the stack
6771 \begin_inset LatexCommand \index{stack}
6772
6773 \end_inset
6774
6775 .
6776  see section Parameters and Local Variables for more details.
6777  If this option is used all source files in the project should be compiled
6778  with this option.
6779
6780 \layout List
6781 \labelwidthstring 00.00.0000
6782
6783
6784 \series bold
6785 -
6786 \begin_inset ERT
6787 status Collapsed
6788
6789 \layout Standard
6790
6791 \backslash
6792 /
6793 \end_inset
6794
6795 -callee-saves
6796 \begin_inset LatexCommand \index{-\/-callee-saves}
6797
6798 \end_inset
6799
6800  function1[,function2][,function3]....
6801
6802 \series default
6803  The compiler by default uses a caller saves convention for register saving
6804  across function calls, however this can cause unnecessary register pushing
6805  & popping when calling small functions from larger functions.
6806  This option can be used to switch the register saving convention for the
6807  function names specified.
6808  The compiler will not save registers when calling these functions, no extra
6809  code will be generated at the entry & exit (function prologue
6810 \series bold
6811
6812 \begin_inset LatexCommand \index{function prologue}
6813
6814 \end_inset
6815
6816
6817 \series default
6818  & epilogue
6819 \series bold
6820
6821 \begin_inset LatexCommand \index{function epilogue}
6822
6823 \end_inset
6824
6825
6826 \series default
6827 ) for these functions to save & restore the registers used by these functions,
6828  this can SUBSTANTIALLY reduce code & improve run time performance of the
6829  generated code.
6830  In the future the compiler (with inter procedural analysis) will be able
6831  to determine the appropriate scheme to use for each function call.
6832  DO NOT use this option for built-in functions such as _mulint..., if this
6833  option is used for a library function the appropriate library function
6834  needs to be recompiled with the same option.
6835  If the project consists of multiple source files then all the source file
6836  should be compiled with the same -
6837 \begin_inset ERT
6838 status Collapsed
6839
6840 \layout Standard
6841
6842 \backslash
6843 /
6844 \end_inset
6845
6846 -callee-saves option string.
6847  Also see #pragma\SpecialChar ~
6848 callee_saves
6849 \begin_inset LatexCommand \index{\#pragma callee\_saves}
6850
6851 \end_inset
6852
6853 .
6854 \layout List
6855 \labelwidthstring 00.00.0000
6856
6857
6858 \series bold
6859 -
6860 \begin_inset ERT
6861 status Collapsed
6862
6863 \layout Standard
6864
6865 \backslash
6866 /
6867 \end_inset
6868
6869 -debug
6870 \begin_inset LatexCommand \index{-\/-debug}
6871
6872 \end_inset
6873
6874
6875 \bar under
6876
6877 \series default
6878 \bar default
6879 When this option is used the compiler will generate debug information.
6880  The debug information collected in a file with .cdb extension can be used
6881  with the SDCDB.
6882  For more information see documentation for SDCDB.
6883  Another file with no extension contains debug information in AOMF or AOMF51
6884 \begin_inset LatexCommand \index{AOMF, AOMF51}
6885
6886 \end_inset
6887
6888  format which is commonly used by third party tools.
6889 \layout List
6890 \labelwidthstring 00.00.0000
6891
6892
6893 \series bold
6894 -S
6895 \begin_inset LatexCommand \index{-S}
6896
6897 \end_inset
6898
6899
6900 \size large
6901 \bar under
6902
6903 \series default
6904 \size default
6905 \bar default
6906 Stop after the stage of compilation proper; do not assemble.
6907  The output is an assembler code file for the input file specified.
6908 \layout List
6909 \labelwidthstring 00.00.0000
6910
6911
6912 \series bold
6913 -
6914 \begin_inset ERT
6915 status Collapsed
6916
6917 \layout Standard
6918
6919 \backslash
6920 /
6921 \end_inset
6922
6923 -int-long-reent
6924 \begin_inset LatexCommand \index{-\/-int-long-reent}
6925
6926 \end_inset
6927
6928
6929 \series default
6930  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
6931  Note by default these libraries are compiled as non-reentrant.
6932  See section Installation for more details.
6933 \layout List
6934 \labelwidthstring 00.00.0000
6935
6936
6937 \series bold
6938 -
6939 \begin_inset ERT
6940 status Collapsed
6941
6942 \layout Standard
6943
6944 \backslash
6945 /
6946 \end_inset
6947
6948 -cyclomatic
6949 \begin_inset LatexCommand \index{-\/-cyclomatic}
6950
6951 \end_inset
6952
6953
6954 \bar under
6955
6956 \series default
6957 \bar default
6958 This option will cause the compiler to generate an information message for
6959  each function in the source file.
6960  The message contains some
6961 \emph on
6962 important
6963 \emph default
6964  information about the function.
6965  The number of edges and nodes the compiler detected in the control flow
6966  graph of the function, and most importantly the
6967 \emph on
6968 cyclomatic complexity
6969 \begin_inset LatexCommand \index{Cyclomatic complexity}
6970
6971 \end_inset
6972
6973
6974 \emph default
6975  see section on Cyclomatic Complexity for more details.
6976 \layout List
6977 \labelwidthstring 00.00.0000
6978
6979
6980 \series bold
6981 -
6982 \begin_inset ERT
6983 status Collapsed
6984
6985 \layout Standard
6986
6987 \backslash
6988 /
6989 \end_inset
6990
6991 -float-reent
6992 \begin_inset LatexCommand \index{-\/-float-reent}
6993
6994 \end_inset
6995
6996
6997 \series default
6998  Floating point library is compiled as reentrant
6999 \begin_inset LatexCommand \index{reentrant}
7000
7001 \end_inset
7002
7003 .
7004  See section Installation for more details.
7005 \layout List
7006 \labelwidthstring 00.00.0000
7007
7008
7009 \series bold
7010 -
7011 \begin_inset ERT
7012 status Collapsed
7013
7014 \layout Standard
7015
7016 \backslash
7017 /
7018 \end_inset
7019
7020 -main-return
7021 \begin_inset LatexCommand \index{-\/-main-return}
7022
7023 \end_inset
7024
7025
7026 \series default
7027  This option can be used when the code generated is called by a monitor
7028  program.
7029  The compiler will generate a 'ret' upon return from the 'main'
7030 \begin_inset LatexCommand \index{main return}
7031
7032 \end_inset
7033
7034  function.
7035  The default setting is to lock up i.e.
7036  generate a '
7037 \family typewriter
7038 sjmp .
7039 \family default
7040 '.
7041 \layout List
7042 \labelwidthstring 00.00.0000
7043
7044
7045 \series bold
7046 -
7047 \begin_inset ERT
7048 status Collapsed
7049
7050 \layout Standard
7051
7052 \backslash
7053 /
7054 \end_inset
7055
7056 -nostdincl
7057 \begin_inset LatexCommand \index{-\/-nostdincl}
7058
7059 \end_inset
7060
7061
7062 \series default
7063  This will prevent the compiler from passing on the default include path
7064  to the preprocessor.
7065 \layout List
7066 \labelwidthstring 00.00.0000
7067
7068
7069 \series bold
7070 -
7071 \begin_inset ERT
7072 status Collapsed
7073
7074 \layout Standard
7075
7076 \backslash
7077 /
7078 \end_inset
7079
7080 -nostdlib
7081 \begin_inset LatexCommand \index{-\/-nostdlib}
7082
7083 \end_inset
7084
7085
7086 \series default
7087  This will prevent the compiler from passing on the default library
7088 \begin_inset LatexCommand \index{Libraries}
7089
7090 \end_inset
7091
7092  path to the linker.
7093 \layout List
7094 \labelwidthstring 00.00.0000
7095
7096
7097 \series bold
7098 -
7099 \begin_inset ERT
7100 status Collapsed
7101
7102 \layout Standard
7103
7104 \backslash
7105 /
7106 \end_inset
7107
7108 -verbose
7109 \begin_inset LatexCommand \index{-\/-verbose}
7110
7111 \end_inset
7112
7113
7114 \series default
7115  Shows the various actions the compiler is performing.
7116 \layout List
7117 \labelwidthstring 00.00.0000
7118
7119
7120 \series bold
7121 -V
7122 \begin_inset LatexCommand \index{-V}
7123
7124 \end_inset
7125
7126
7127 \series default
7128  Shows the actual commands the compiler is executing.
7129 \layout List
7130 \labelwidthstring 00.00.0000
7131
7132
7133 \series bold
7134 -
7135 \begin_inset ERT
7136 status Collapsed
7137
7138 \layout Standard
7139
7140 \backslash
7141 /
7142 \end_inset
7143
7144 -no-c-code-in-asm
7145 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7146
7147 \end_inset
7148
7149
7150 \series default
7151  Hides your ugly and inefficient c-code from the asm file, so you can always
7152  blame the compiler :).
7153 \layout List
7154 \labelwidthstring 00.00.0000
7155
7156
7157 \series bold
7158 -
7159 \begin_inset ERT
7160 status Collapsed
7161
7162 \layout Standard
7163
7164 \backslash
7165 /
7166 \end_inset
7167
7168 -i-code-in-asm
7169 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7170
7171 \end_inset
7172
7173
7174 \series default
7175  Include i-codes in the asm file.
7176  Sounds like noise but is most helpful for debugging the compiler itself.
7177 \layout List
7178 \labelwidthstring 00.00.0000
7179
7180
7181 \series bold
7182 -
7183 \begin_inset ERT
7184 status Collapsed
7185
7186 \layout Standard
7187
7188 \backslash
7189 /
7190 \end_inset
7191
7192 -less-pedantic
7193 \begin_inset LatexCommand \index{-\/-less-pedantic}
7194
7195 \end_inset
7196
7197
7198 \series default
7199  Disable some of the more pedantic warnings
7200 \begin_inset LatexCommand \index{Warnings}
7201
7202 \end_inset
7203
7204  (jwk burps: please be more specific here, please!).
7205  If you want rather more than less warnings you should consider using a
7206  separate tool dedicated to syntax checking like splint
7207 \begin_inset LatexCommand \url{www.splint.org}
7208
7209 \end_inset
7210
7211 .
7212 \layout List
7213 \labelwidthstring 00.00.0000
7214
7215
7216 \series bold
7217 -
7218 \begin_inset ERT
7219 status Collapsed
7220
7221 \layout Standard
7222
7223 \backslash
7224 /
7225 \end_inset
7226
7227 -print-search-dirs
7228 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7229
7230 \end_inset
7231
7232
7233 \series default
7234  Display the directories in the compiler's search path
7235 \layout List
7236 \labelwidthstring 00.00.0000
7237
7238
7239 \series bold
7240 -
7241 \begin_inset ERT
7242 status Collapsed
7243
7244 \layout Standard
7245
7246 \backslash
7247 /
7248 \end_inset
7249
7250 -vc
7251 \begin_inset LatexCommand \index{-\/-vc}
7252
7253 \end_inset
7254
7255
7256 \series default
7257  Display errors and warnings using MSVC style, so you can use SDCC with
7258  visual studio.
7259 \layout List
7260 \labelwidthstring 00.00.0000
7261
7262
7263 \series bold
7264 -
7265 \begin_inset ERT
7266 status Collapsed
7267
7268 \layout Standard
7269
7270 \backslash
7271 /
7272 \end_inset
7273
7274 -use-stdout
7275 \begin_inset LatexCommand \index{-\/-use-stdout}
7276
7277 \end_inset
7278
7279
7280 \series default
7281  Send errors and warnings to stdout instead of stderr.
7282 \layout List
7283 \labelwidthstring 00.00.0000
7284
7285
7286 \series bold
7287 -Wa\SpecialChar ~
7288 asmOption[,asmOption]
7289 \series default
7290
7291 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7292
7293 \end_inset
7294
7295 ...
7296  Pass the asmOption to the assembler
7297 \begin_inset LatexCommand \index{Options assembler}
7298
7299 \end_inset
7300
7301
7302 \begin_inset LatexCommand \index{Assembler options}
7303
7304 \end_inset
7305
7306 .
7307  See file sdcc/as/doc/asxhtm.html for assembler options.
7308 \layout Subsection
7309
7310 Intermediate Dump Options
7311 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7312
7313 \end_inset
7314
7315
7316 \begin_inset LatexCommand \index{Options intermediate dump}
7317
7318 \end_inset
7319
7320
7321 \begin_inset LatexCommand \index{Intermediate dump options}
7322
7323 \end_inset
7324
7325
7326 \layout Standard
7327
7328 The following options are provided for the purpose of retargetting and debugging
7329  the compiler.
7330  These provided a means to dump the intermediate code (iCode
7331 \begin_inset LatexCommand \index{iCode}
7332
7333 \end_inset
7334
7335 ) generated by the compiler in human readable form at various stages of
7336  the compilation process.
7337  More on iCodes see chapter
7338 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7339
7340 \end_inset
7341
7342
7343 \begin_inset Quotes srd
7344 \end_inset
7345
7346 The anatomy of the compiler
7347 \begin_inset Quotes srd
7348 \end_inset
7349
7350 .
7351 \layout List
7352 \labelwidthstring 00.00.0000
7353
7354
7355 \series bold
7356 -
7357 \begin_inset ERT
7358 status Collapsed
7359
7360 \layout Standard
7361
7362 \backslash
7363 /
7364 \end_inset
7365
7366 -dumpraw
7367 \begin_inset LatexCommand \index{-\/-dumpraw}
7368
7369 \end_inset
7370
7371
7372 \series default
7373  This option will cause the compiler to dump the intermediate code into
7374  a file of named
7375 \emph on
7376 <source filename>.dumpraw
7377 \emph default
7378  just after the intermediate code has been generated for a function, i.e.
7379  before any optimizations are done.
7380  The basic blocks
7381 \begin_inset LatexCommand \index{Basic blocks}
7382
7383 \end_inset
7384
7385  at this stage ordered in the depth first number, so they may not be in
7386  sequence of execution.
7387 \layout List
7388 \labelwidthstring 00.00.0000
7389
7390
7391 \series bold
7392 -
7393 \begin_inset ERT
7394 status Collapsed
7395
7396 \layout Standard
7397
7398 \backslash
7399 /
7400 \end_inset
7401
7402 -dumpgcse
7403 \begin_inset LatexCommand \index{-\/-dumpgcse}
7404
7405 \end_inset
7406
7407
7408 \series default
7409  Will create a dump of iCode's, after global subexpression elimination
7410 \begin_inset LatexCommand \index{Global subexpression elimination}
7411
7412 \end_inset
7413
7414 , into a file named
7415 \emph on
7416 <source filename>.dumpgcse.
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 -dumpdeadcode
7433 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
7434
7435 \end_inset
7436
7437
7438 \series default
7439  Will create a dump of iCode's, after deadcode elimination
7440 \begin_inset LatexCommand \index{Dead-code elimination}
7441
7442 \end_inset
7443
7444 , into a file named
7445 \emph on
7446 <source filename>.dumpdeadcode.
7447 \layout List
7448 \labelwidthstring 00.00.0000
7449
7450
7451 \series bold
7452 -
7453 \begin_inset ERT
7454 status Collapsed
7455
7456 \layout Standard
7457
7458 \backslash
7459 /
7460 \end_inset
7461
7462 -dumploop
7463 \begin_inset LatexCommand \index{-\/-dumploop}
7464
7465 \end_inset
7466
7467
7468 \series default
7469 \size large
7470
7471 \size default
7472 Will create a dump of iCode's, after loop optimizations
7473 \begin_inset LatexCommand \index{Loop optimization}
7474
7475 \end_inset
7476
7477 , into a file named
7478 \emph on
7479 <source filename>.dumploop.
7480 \layout List
7481 \labelwidthstring 00.00.0000
7482
7483
7484 \series bold
7485 -
7486 \begin_inset ERT
7487 status Collapsed
7488
7489 \layout Standard
7490
7491 \backslash
7492 /
7493 \end_inset
7494
7495 -dumprange
7496 \begin_inset LatexCommand \index{-\/-dumprange}
7497
7498 \end_inset
7499
7500
7501 \series default
7502 \size large
7503
7504 \size default
7505 Will create a dump of iCode's, after live range analysis
7506 \begin_inset LatexCommand \index{Live range analysis}
7507
7508 \end_inset
7509
7510 , into a file named
7511 \emph on
7512 <source filename>.dumprange.
7513 \layout List
7514 \labelwidthstring 00.00.0000
7515
7516
7517 \series bold
7518 -
7519 \begin_inset ERT
7520 status Collapsed
7521
7522 \layout Standard
7523
7524 \backslash
7525 /
7526 \end_inset
7527
7528 -dumlrange
7529 \begin_inset LatexCommand \index{-\/-dumlrange}
7530
7531 \end_inset
7532
7533
7534 \series default
7535  Will dump the life ranges
7536 \begin_inset LatexCommand \index{Live range analysis}
7537
7538 \end_inset
7539
7540  for all symbols.
7541 \layout List
7542 \labelwidthstring 00.00.0000
7543
7544
7545 \series bold
7546 -
7547 \begin_inset ERT
7548 status Collapsed
7549
7550 \layout Standard
7551
7552 \backslash
7553 /
7554 \end_inset
7555
7556 -dumpregassign
7557 \begin_inset LatexCommand \index{-\/-dumpregassign}
7558
7559 \end_inset
7560
7561
7562 \bar under
7563
7564 \series default
7565 \bar default
7566 Will create a dump of iCode's, after register assignment
7567 \begin_inset LatexCommand \index{Register assignment}
7568
7569 \end_inset
7570
7571 , into a file named
7572 \emph on
7573 <source filename>.dumprassgn.
7574 \layout List
7575 \labelwidthstring 00.00.0000
7576
7577
7578 \series bold
7579 -
7580 \begin_inset ERT
7581 status Collapsed
7582
7583 \layout Standard
7584
7585 \backslash
7586 /
7587 \end_inset
7588
7589 -dumplrange
7590 \begin_inset LatexCommand \index{-\/-dumplrange}
7591
7592 \end_inset
7593
7594
7595 \series default
7596  Will create a dump of the live ranges of iTemp's
7597 \layout List
7598 \labelwidthstring 00.00.0000
7599
7600
7601 \series bold
7602 -
7603 \begin_inset ERT
7604 status Collapsed
7605
7606 \layout Standard
7607
7608 \backslash
7609 /
7610 \end_inset
7611
7612 -dumpall
7613 \begin_inset LatexCommand \index{-\/-dumpall}
7614
7615 \end_inset
7616
7617
7618 \size large
7619 \bar under
7620
7621 \series default
7622 \size default
7623 \bar default
7624 Will cause all the above mentioned dumps to be created.
7625 \layout Subsection
7626
7627 Redirecting output on Windows Shells
7628 \layout Standard
7629
7630 By default SDCC writes it's error messages to
7631 \begin_inset Quotes sld
7632 \end_inset
7633
7634 standard error
7635 \begin_inset Quotes srd
7636 \end_inset
7637
7638 .
7639  To force all messages to
7640 \begin_inset Quotes sld
7641 \end_inset
7642
7643 standard output
7644 \begin_inset Quotes srd
7645 \end_inset
7646
7647  use
7648 \series bold
7649 -
7650 \series default
7651 \emph on
7652
7653 \begin_inset ERT
7654 status Collapsed
7655
7656 \layout Standard
7657
7658 \backslash
7659 /
7660 \end_inset
7661
7662
7663 \series bold
7664 \emph default
7665 -
7666 \series default
7667 use-stdout
7668 \begin_inset LatexCommand \index{-\/-use-stdout}
7669
7670 \end_inset
7671
7672 .
7673  Additionally, if you happen to have visual studio installed in your windows
7674  machine, you can use it to compile your sources using a custom build and
7675  the SDCC -
7676 \emph on
7677
7678 \begin_inset ERT
7679 status Collapsed
7680
7681 \layout Standard
7682
7683 \backslash
7684 /
7685 \end_inset
7686
7687
7688 \emph default
7689 -vc
7690 \begin_inset LatexCommand \index{-\/-vc}
7691
7692 \end_inset
7693
7694  option.
7695  Something like this should work:
7696 \newline
7697
7698 \newline
7699
7700 \series bold
7701 c:
7702 \backslash
7703 sdcc
7704 \backslash
7705 bin
7706 \backslash
7707 sdcc.exe -
7708 \series default
7709 \emph on
7710
7711 \begin_inset ERT
7712 status Collapsed
7713
7714 \layout Standard
7715
7716 \backslash
7717 /
7718 \end_inset
7719
7720
7721 \series bold
7722 \emph default
7723 -vc -
7724 \series default
7725 \emph on
7726
7727 \begin_inset ERT
7728 status Collapsed
7729
7730 \layout Standard
7731
7732 \backslash
7733 /
7734 \end_inset
7735
7736
7737 \series bold
7738 \emph default
7739 -model-large -c $(InputPath)
7740 \layout Section
7741
7742 Environment variables
7743 \begin_inset LatexCommand \index{Environment variables}
7744
7745 \end_inset
7746
7747
7748 \layout Standard
7749
7750 SDCC recognizes the following environment variables:
7751 \layout List
7752 \labelwidthstring 00.00.0000
7753
7754
7755 \series bold
7756 SDCC_LEAVE_SIGNALS
7757 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7758
7759 \end_inset
7760
7761
7762 \series default
7763  SDCC installs a signal handler
7764 \begin_inset LatexCommand \index{signal handler}
7765
7766 \end_inset
7767
7768  to be able to delete temporary files after an user break (^C) or an exception.
7769  If this environment variable is set, SDCC won't install the signal handler
7770  in order to be able to debug SDCC.
7771 \layout List
7772 \labelwidthstring 00.00.0000
7773
7774
7775 \series bold
7776 TMP,\SpecialChar ~
7777 TEMP,\SpecialChar ~
7778 TMPDIR
7779 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7780
7781 \end_inset
7782
7783
7784 \series default
7785  Path, where temporary files will be created.
7786  The order of the variables is the search order.
7787  In a standard *nix environment these variables are not set, and there's
7788  no need to set them.
7789  On Windows it's recommended to set one of them.
7790 \layout List
7791 \labelwidthstring 00.00.0000
7792
7793
7794 \series bold
7795 SDCC_HOME
7796 \begin_inset LatexCommand \index{SDCC\_HOME}
7797
7798 \end_inset
7799
7800
7801 \series default
7802  Path, see section
7803 \begin_inset LatexCommand \ref{sub:Install-paths}
7804
7805 \end_inset
7806
7807 \SpecialChar ~
7808
7809 \begin_inset Quotes sld
7810 \end_inset
7811
7812  Install Paths
7813 \begin_inset Quotes srd
7814 \end_inset
7815
7816 .
7817 \layout List
7818 \labelwidthstring 00.00.0000
7819
7820
7821 \series bold
7822 SDCC_INCLUDE
7823 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
7824
7825 \end_inset
7826
7827
7828 \series default
7829  Path, see section
7830 \begin_inset LatexCommand \ref{sub:Search-Paths}
7831
7832 \end_inset
7833
7834 \SpecialChar ~
7835
7836 \begin_inset Quotes sld
7837 \end_inset
7838
7839 Search Paths
7840 \begin_inset Quotes srd
7841 \end_inset
7842
7843 .
7844 \layout List
7845 \labelwidthstring 00.00.0000
7846
7847
7848 \series bold
7849 SDCC_LIB
7850 \begin_inset LatexCommand \index{SDCC\_LIB}
7851
7852 \end_inset
7853
7854
7855 \series default
7856  Path, see section
7857 \begin_inset LatexCommand \ref{sub:Search-Paths}
7858
7859 \end_inset
7860
7861 \SpecialChar ~
7862
7863 \begin_inset Quotes sld
7864 \end_inset
7865
7866 Search Paths
7867 \begin_inset Quotes srd
7868 \end_inset
7869
7870 ..
7871 \layout Standard
7872
7873 There are some more environment variables recognized by SDCC, but these
7874  are solely used for debugging purposes.
7875  They can change or disappear very quickly, and will never be documented.
7876 \layout Section
7877
7878 Storage Class Language Extensions
7879 \layout Subsection
7880
7881 MCS51/DS390 Storage Class
7882 \begin_inset LatexCommand \index{Storage class}
7883
7884 \end_inset
7885
7886  Language Extensions
7887 \layout Standard
7888
7889 In addition to the ANSI storage classes SDCC allows the following MCS51
7890  specific storage classes:
7891 \layout Subsubsection
7892
7893 data
7894 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
7895
7896 \end_inset
7897
7898  / near
7899 \begin_inset LatexCommand \index{near (storage class)}
7900
7901 \end_inset
7902
7903
7904 \layout Standard
7905
7906 This is the
7907 \series bold
7908 default
7909 \series default
7910  storage class for the Small Memory model (
7911 \emph on
7912 data
7913 \emph default
7914  and
7915 \emph on
7916 near
7917 \emph default
7918  can be used synonymously).
7919  Variables declared with this storage class will be allocated in the directly
7920  addressable portion of the internal RAM of a 8051, e.g.:
7921 \layout Verse
7922
7923
7924 \family typewriter
7925 data unsigned char test_data;
7926 \layout Standard
7927
7928 Writing 0x01 to this variable generates the assembly code:
7929 \layout Verse
7930
7931
7932 \family typewriter
7933 75*00 01\SpecialChar ~
7934 \SpecialChar ~
7935 \SpecialChar ~
7936 mov\SpecialChar ~
7937 \SpecialChar ~
7938 _test_data,#0x01
7939 \layout Subsubsection
7940
7941 xdata
7942 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
7943
7944 \end_inset
7945
7946  / far
7947 \begin_inset LatexCommand \index{far (storage class)}
7948
7949 \end_inset
7950
7951
7952 \layout Standard
7953
7954 Variables declared with this storage class will be placed in the external
7955  RAM.
7956  This is the
7957 \series bold
7958 default
7959 \series default
7960  storage class for the Large Memory model, e.g.:
7961 \layout Verse
7962
7963
7964 \family typewriter
7965 xdata unsigned char test_xdata;
7966 \layout Standard
7967
7968 Writing 0x01 to this variable generates the assembly code:
7969 \layout Verse
7970
7971
7972 \family typewriter
7973 90s00r00\SpecialChar ~
7974 \SpecialChar ~
7975 \SpecialChar ~
7976 mov\SpecialChar ~
7977 \SpecialChar ~
7978 dptr,#_test_xdata
7979 \newline
7980 74\SpecialChar ~
7981 01\SpecialChar ~
7982 \SpecialChar ~
7983 \SpecialChar ~
7984 \SpecialChar ~
7985 \SpecialChar ~
7986 \SpecialChar ~
7987 mov\SpecialChar ~
7988 \SpecialChar ~
7989 a,#0x01
7990 \newline
7991 F0\SpecialChar ~
7992 \SpecialChar ~
7993 \SpecialChar ~
7994 \SpecialChar ~
7995 \SpecialChar ~
7996 \SpecialChar ~
7997 \SpecialChar ~
7998 \SpecialChar ~
7999 \SpecialChar ~
8000 movx\SpecialChar ~
8001 @dptr,a
8002 \layout Subsubsection
8003
8004 idata
8005 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8006
8007 \end_inset
8008
8009
8010 \layout Standard
8011
8012 Variables declared with this storage class will be allocated into the indirectly
8013  addressable portion of the internal ram of a 8051, e.g.:
8014 \layout Verse
8015
8016
8017 \family typewriter
8018 idata unsigned char test_idata;
8019 \layout Standard
8020
8021 Writing 0x01 to this variable generates the assembly code:
8022 \layout Verse
8023
8024
8025 \family typewriter
8026 78r00\SpecialChar ~
8027 \SpecialChar ~
8028 \SpecialChar ~
8029 \SpecialChar ~
8030 \SpecialChar ~
8031 \SpecialChar ~
8032 \SpecialChar ~
8033 mov\SpecialChar ~
8034 \SpecialChar ~
8035 r0,#_test_idata
8036 \newline
8037 76\SpecialChar ~
8038 01\SpecialChar ~
8039 \SpecialChar ~
8040 \SpecialChar ~
8041 \SpecialChar ~
8042 \SpecialChar ~
8043 \SpecialChar ~
8044 \SpecialChar ~
8045 mov\SpecialChar ~
8046 \SpecialChar ~
8047 @r0,#0x01
8048 \layout Standard
8049
8050 Please note, the first 128 byte of idata physically access the same RAM
8051  as the data memory.
8052  The original 8051 had 128 byte idata memory, nowadays most devices have
8053  256 byte idata memory.
8054  The stack
8055 \begin_inset LatexCommand \index{stack}
8056
8057 \end_inset
8058
8059  is located in idata memory.
8060 \layout Subsubsection
8061
8062 pdata
8063 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8064
8065 \end_inset
8066
8067
8068 \layout Standard
8069
8070 Paged xdata access is currently not as straightforward as using the other
8071  addressing modes of a 8051.
8072  The following example writes 0x01 to the address pointed to.
8073  Please note, pdata access physically accesses xdata memory.
8074  The high byte of the address is determined by port P2
8075 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8076
8077 \end_inset
8078
8079 (or in case of some 8051 variants by a separate Special Function Register,
8080  see section
8081 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8082
8083 \end_inset
8084
8085 ).
8086 \layout Verse
8087
8088
8089 \family typewriter
8090 pdata unsigned char *test_pdata_ptr;
8091 \newline
8092
8093 \newline
8094 void main()
8095 \newline
8096 {
8097 \newline
8098 \SpecialChar ~
8099 \SpecialChar ~
8100 \SpecialChar ~
8101 \SpecialChar ~
8102 test_pdata_ptr = (pdata *)0xfe;
8103 \newline
8104 \SpecialChar ~
8105 \SpecialChar ~
8106 \SpecialChar ~
8107 \SpecialChar ~
8108 *test_pdata_ptr = 1;
8109 \newline
8110 }
8111 \layout Standard
8112
8113 Generates the assembly code:
8114 \layout Verse
8115
8116
8117 \family typewriter
8118 75*01 FE\SpecialChar ~
8119 \SpecialChar ~
8120 \SpecialChar ~
8121 mov\SpecialChar ~
8122  _test_pdata_ptr,#0xFE
8123 \newline
8124 78 FE\SpecialChar ~
8125 \SpecialChar ~
8126 \SpecialChar ~
8127 \SpecialChar ~
8128 \SpecialChar ~
8129 \SpecialChar ~
8130 mov\SpecialChar ~
8131  r0,#0xFE
8132 \newline
8133 74 01\SpecialChar ~
8134 \SpecialChar ~
8135 \SpecialChar ~
8136 \SpecialChar ~
8137 \SpecialChar ~
8138 \SpecialChar ~
8139 mov\SpecialChar ~
8140  a,#0x01
8141 \newline
8142 F2\SpecialChar ~
8143 \SpecialChar ~
8144 \SpecialChar ~
8145 \SpecialChar ~
8146 \SpecialChar ~
8147 \SpecialChar ~
8148 \SpecialChar ~
8149 \SpecialChar ~
8150 \SpecialChar ~
8151 movx @r0,a
8152 \layout Standard
8153
8154 Be extremely carefull if you use pdata together with the -
8155 \begin_inset ERT
8156 status Collapsed
8157
8158 \layout Standard
8159
8160 \backslash
8161 /
8162 \end_inset
8163
8164 -xstack
8165 \begin_inset LatexCommand \index{-\/-xstack}
8166
8167 \end_inset
8168
8169  option.
8170 \layout Subsubsection
8171
8172 code
8173 \begin_inset LatexCommand \index{code}
8174
8175 \end_inset
8176
8177
8178 \layout Standard
8179
8180 'Variables' declared with this storage class will be placed in the code
8181  memory:
8182 \layout Verse
8183
8184
8185 \family typewriter
8186 code unsigned char test_code;
8187 \layout Standard
8188
8189 Read access to this variable generates the assembly code:
8190 \layout Verse
8191
8192
8193 \family typewriter
8194 90s00r6F\SpecialChar ~
8195 \SpecialChar ~
8196 \SpecialChar ~
8197 mov dptr,#_test_code
8198 \newline
8199 E4\SpecialChar ~
8200 \SpecialChar ~
8201 \SpecialChar ~
8202 \SpecialChar ~
8203 \SpecialChar ~
8204 \SpecialChar ~
8205 \SpecialChar ~
8206 \SpecialChar ~
8207 \SpecialChar ~
8208 clr a
8209 \newline
8210 93\SpecialChar ~
8211 \SpecialChar ~
8212 \SpecialChar ~
8213 \SpecialChar ~
8214 \SpecialChar ~
8215 \SpecialChar ~
8216 \SpecialChar ~
8217 \SpecialChar ~
8218 \SpecialChar ~
8219 movc a,@a+dptr
8220 \layout Standard
8221
8222
8223 \family typewriter
8224 char
8225 \family default
8226  indexed arrays of characters in code memory can be accessed efficiently:
8227 \layout Verse
8228
8229
8230 \family typewriter
8231 code char test_array[] = {'c','h','e','a','p'};
8232 \layout Standard
8233
8234 Read access to this array using an 8-bit unsigned index generates the assembly
8235  code:
8236 \layout Verse
8237
8238
8239 \family typewriter
8240 E5*00\SpecialChar ~
8241 \SpecialChar ~
8242 \SpecialChar ~
8243 \SpecialChar ~
8244 \SpecialChar ~
8245 \SpecialChar ~
8246 mov a,_index
8247 \layout Verse
8248
8249
8250 \family typewriter
8251 90s00r41\SpecialChar ~
8252 \SpecialChar ~
8253 \SpecialChar ~
8254 mov dptr,#_test_array
8255 \layout Verse
8256
8257
8258 \family typewriter
8259 93\SpecialChar ~
8260 \SpecialChar ~
8261 \SpecialChar ~
8262 \SpecialChar ~
8263 \SpecialChar ~
8264 \SpecialChar ~
8265 \SpecialChar ~
8266 \SpecialChar ~
8267 \SpecialChar ~
8268 movc a,@a+dptr
8269 \layout Subsubsection
8270
8271 bit
8272 \begin_inset LatexCommand \index{bit}
8273
8274 \end_inset
8275
8276
8277 \layout Standard
8278
8279 This is a data-type and a storage class specifier.
8280  When a variable is declared as a bit, it is allocated into the bit addressable
8281  memory of 8051, e.g.:
8282 \layout Verse
8283
8284
8285 \family typewriter
8286 bit test_bit;
8287 \layout Standard
8288
8289 Writing 1 to this variable generates the assembly code:
8290 \layout Verse
8291
8292
8293 \family typewriter
8294 D2*00\SpecialChar ~
8295 \SpecialChar ~
8296 \SpecialChar ~
8297 \SpecialChar ~
8298 \SpecialChar ~
8299 \SpecialChar ~
8300 \SpecialChar ~
8301 setb\SpecialChar ~
8302 _test_bit
8303 \layout Standard
8304
8305 The bit addressable memory consists of 128 bits which are located from 0x20
8306  to 0x2f in data memory.
8307
8308 \layout Standard
8309
8310 Apart from this 8051 specific storage class most architectures support ANSI-C
8311  bitfields
8312 \begin_inset LatexCommand \index{bitfields}
8313
8314 \end_inset
8315
8316
8317 \newline
8318
8319 \layout Standard
8320
8321 In accordance with ISO/IEC 9899 bits and bitfields without an explicit signed
8322  modifier are implemented as unsigned.
8323 \layout Standard
8324
8325
8326 \begin_inset Foot
8327 collapsed false
8328
8329 \layout Standard
8330
8331 Not really meant as examples, but nevertheless showing what bitfields are
8332  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8333 \end_inset
8334
8335 .
8336 \layout Subsubsection
8337
8338 sfr
8339 \begin_inset LatexCommand \index{sfr}
8340
8341 \end_inset
8342
8343  / sbit
8344 \begin_inset LatexCommand \index{sbit}
8345
8346 \end_inset
8347
8348
8349 \layout Standard
8350
8351 Like the bit keyword,
8352 \emph on
8353 sfr / sbit
8354 \emph default
8355 signifies both a data-type and storage class, they are used to describe
8356  the
8357 \emph on
8358 s
8359 \emph default
8360 pecial
8361 \emph on
8362 f
8363 \emph default
8364 unction
8365 \emph on
8366 r
8367 \emph default
8368 egisters and
8369 \emph on
8370 s
8371 \emph default
8372 pecial
8373 \emph on
8374 bit
8375 \emph default
8376  variables of a 8051, eg:
8377 \layout Verse
8378
8379
8380 \family typewriter
8381 sfr at
8382 \begin_inset LatexCommand \index{at}
8383
8384 \end_inset
8385
8386  0x80 P0;\SpecialChar ~
8387  /* special function register P0 at location 0x80 */
8388 \newline
8389 sbit at 0xd7 CY; /* CY (Carry Flag
8390 \begin_inset LatexCommand \index{Flags}
8391
8392 \end_inset
8393
8394
8395 \begin_inset LatexCommand \index{Carry flag}
8396
8397 \end_inset
8398
8399 ) */
8400 \layout Standard
8401
8402 Special function registers which are located on an address dividable by
8403  8 are bit-addressable, an
8404 \emph on
8405  sbit
8406 \emph default
8407  addresses a specific bit within these sfr.
8408 \layout Subsubsection
8409
8410 Pointers
8411 \begin_inset LatexCommand \index{Pointer}
8412
8413 \end_inset
8414
8415  to MCS51/DS390 specific memory spaces
8416 \layout Standard
8417
8418 SDCC allows (via language extensions) pointers to explicitly point to any
8419  of the memory spaces
8420 \begin_inset LatexCommand \index{Memory model}
8421
8422 \end_inset
8423
8424  of the 8051.
8425  In addition to the explicit pointers, the compiler uses (by default) generic
8426  pointers which can be used to point to any of the memory spaces.
8427 \newline
8428
8429 \newline
8430 Pointer declaration examples:
8431 \layout Verse
8432
8433
8434 \family typewriter
8435 /* pointer physically in internal ram pointing to object in external ram
8436  */
8437 \newline
8438 xdata unsigned char * data p;
8439 \newline
8440
8441 \newline
8442 /* pointer physically in external ram pointing to object in internal ram
8443  */
8444 \newline
8445 data unsigned char * xdata p;
8446 \newline
8447
8448 \newline
8449 /* pointer physically in code rom pointing to data in xdata space */
8450 \newline
8451 xdata unsigned char * code p;
8452 \newline
8453
8454 \newline
8455 /* pointer physically in code space pointing to data in code space */
8456 \newline
8457 code unsigned char * code p;
8458 \newline
8459
8460 \newline
8461 /* the following is a generic pointer physically located in xdata space
8462  */
8463 \newline
8464 char * xdata p;
8465 \layout Standard
8466
8467 Well you get the idea.
8468
8469 \newline
8470
8471 \newline
8472 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
8473 \emph on
8474 generic
8475 \emph default
8476  pointers.
8477
8478 \size small
8479
8480 \newline
8481
8482 \newline
8483
8484 \size default
8485 The highest order byte of the
8486 \emph on
8487 generic
8488 \emph default
8489  pointers contains the data space information.
8490  Assembler support routines are called whenever data is stored or retrieved
8491  using
8492 \emph on
8493 generic
8494 \emph default
8495  pointers.
8496  These are useful for developing reusable library
8497 \begin_inset LatexCommand \index{Libraries}
8498
8499 \end_inset
8500
8501  routines.
8502  Explicitly specifying the pointer type will generate the most efficient
8503  code.
8504 \layout Subsubsection
8505
8506 Notes on MCS51 memory
8507 \begin_inset LatexCommand \index{MCS51 memory}
8508
8509 \end_inset
8510
8511  layout
8512 \layout Standard
8513
8514 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
8515  RAM memory which is structured as follows:
8516 \newline
8517
8518 \newline
8519 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
8520
8521 \newline
8522 - Bytes 20-2F - 16 bytes to hold 128 bit
8523 \begin_inset LatexCommand \index{bit}
8524
8525 \end_inset
8526
8527  variables and,
8528 \newline
8529 - Bytes 30-7F - 80 bytes for general purpose use.
8530 \newline
8531
8532 \layout Standard
8533
8534 Additionally some members of the MCS51 family may have up to 128 bytes of
8535  additional, indirectly addressable, internal RAM memory (
8536 \emph on
8537 idata
8538 \emph default
8539
8540 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8541
8542 \end_inset
8543
8544 ).
8545  Furthermore, some chips may have some built in external memory (
8546 \emph on
8547 xdata
8548 \emph default
8549
8550 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8551
8552 \end_inset
8553
8554 ) which should not be confused with the internal, directly addressable RAM
8555  memory (
8556 \emph on
8557 data
8558 \emph default
8559
8560 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8561
8562 \end_inset
8563
8564 ).
8565  Sometimes this built in
8566 \emph on
8567 xdata
8568 \emph default
8569  memory has to be activated before using it (you can probably find this
8570  information on the datasheet of the microcontroller your are using, see
8571  also section
8572 \begin_inset LatexCommand \ref{sub:Startup-Code}
8573
8574 \end_inset
8575
8576 \SpecialChar ~
8577 Startup-Code).
8578 \layout Standard
8579
8580 Normally SDCC will only use the first bank
8581 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
8582
8583 \end_inset
8584
8585  of registers (register bank 0), but it is possible to specify that other
8586  banks of registers should be used in interrupt
8587 \begin_inset LatexCommand \index{interrupt}
8588
8589 \end_inset
8590
8591  routines.
8592  By default, the compiler will place the stack after the last byte of allocated
8593  memory for variables.
8594  For example, if the first 2 banks of registers are used, and only four
8595  bytes are used for
8596 \emph on
8597 data
8598 \emph default
8599  variables, it will position the base of the internal stack at address 20
8600  (0x14).
8601  This implies that as the stack
8602 \begin_inset LatexCommand \index{stack}
8603
8604 \end_inset
8605
8606  grows, it will use up the remaining register banks, and the 16 bytes used
8607  by the 128 bit variables, and 80 bytes for general purpose use.
8608  If any bit variables are used, the data variables will be placed after
8609  the byte holding the last bit variable.
8610  For example, if register banks 0 and 1 are used, and there are 9 bit variables
8611  (two bytes used),
8612 \emph on
8613 data
8614 \emph default
8615  variables will be placed starting at address 0x22.
8616  You can also use -
8617 \begin_inset ERT
8618 status Collapsed
8619
8620 \layout Standard
8621
8622 \backslash
8623 /
8624 \end_inset
8625
8626 -data-loc
8627 \begin_inset LatexCommand \index{-\/-data-loc<Value>}
8628
8629 \end_inset
8630
8631  to specify the start address of the
8632 \emph on
8633 data
8634 \emph default
8635  and -
8636 \begin_inset ERT
8637 status Collapsed
8638
8639 \layout Standard
8640
8641 \backslash
8642 /
8643 \end_inset
8644
8645 -iram-size to specify the size of the total internal RAM (
8646 \emph on
8647 data
8648 \emph default
8649 +
8650 \emph on
8651 idata
8652 \emph default
8653 ).
8654
8655 \layout Standard
8656
8657 By default the 8051 linker will place the stack after the last byte of data
8658  variables.
8659  Option -
8660 \begin_inset ERT
8661 status Collapsed
8662
8663 \layout Standard
8664
8665 \backslash
8666 /
8667 \end_inset
8668
8669 -stack-loc
8670 \begin_inset LatexCommand \index{-\/-stack-loc<Value>}
8671
8672 \end_inset
8673
8674  allows you to specify the start of the stack, i.e.
8675  you could start it after any data in the general purpose area.
8676  If your microcontroller has additional indirectly addressable internal
8677  RAM (
8678 \emph on
8679 idata
8680 \emph default
8681 ) you can place the stack on it.
8682  You may also need to use -
8683 \begin_inset ERT
8684 status Collapsed
8685
8686 \layout Standard
8687
8688 \backslash
8689 /
8690 \end_inset
8691
8692 -xdata-loc
8693 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
8694
8695 \end_inset
8696
8697  to set the start address of the external RAM (
8698 \emph on
8699 xdata
8700 \emph default
8701 ) and -
8702 \begin_inset ERT
8703 status Collapsed
8704
8705 \layout Standard
8706
8707 \backslash
8708 /
8709 \end_inset
8710
8711 -xram-size
8712 \begin_inset LatexCommand \index{-\/-data-loc}
8713
8714 \end_inset
8715
8716  to specify its size.
8717  Same goes for the code memory, using -
8718 \begin_inset ERT
8719 status Collapsed
8720
8721 \layout Standard
8722
8723 \backslash
8724 /
8725 \end_inset
8726
8727 -code-loc
8728 \begin_inset LatexCommand \index{-\/-data-loc}
8729
8730 \end_inset
8731
8732  and -
8733 \begin_inset ERT
8734 status Collapsed
8735
8736 \layout Standard
8737
8738 \backslash
8739 /
8740 \end_inset
8741
8742 -code-size
8743 \begin_inset LatexCommand \index{-\/-data-loc}
8744
8745 \end_inset
8746
8747 .
8748  If in doubt, don't specify any options and see if the resulting memory
8749  layout is appropriate, then you can adjust it.
8750 \layout Standard
8751
8752 The linker generates two files with memory allocation information.
8753  The first, with extension .map
8754 \begin_inset LatexCommand \index{<file>.map}
8755
8756 \end_inset
8757
8758  shows all the variables and segments.
8759  The second with extension .mem
8760 \begin_inset LatexCommand \index{<file>.mem}
8761
8762 \end_inset
8763
8764  shows the final memory layout.
8765  The linker will complain either if memory segments overlap, there is not
8766  enough memory, or there is not enough space for stack.
8767  If you get any linking warnings and/or errors related to stack or segments
8768  allocation, take a look at either the .map or .mem files to find out what
8769  the problem is.
8770  The .mem file may even suggest a solution to the problem.
8771 \layout Subsection
8772
8773 Z80/Z180 Storage Class
8774 \begin_inset LatexCommand \index{Storage class}
8775
8776 \end_inset
8777
8778  Language Extensions
8779 \layout Subsubsection
8780
8781 sfr
8782 \begin_inset LatexCommand \index{sfr}
8783
8784 \end_inset
8785
8786  (in/out to 8-bit addresses)
8787 \layout Standard
8788
8789 The Z80
8790 \begin_inset LatexCommand \index{Z80}
8791
8792 \end_inset
8793
8794  family has separate address spaces for memory and
8795 \emph on
8796 i
8797 \emph default
8798 nput/
8799 \emph on
8800 o
8801 \emph default
8802 utput memory.
8803  I/O memory
8804 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
8805
8806 \end_inset
8807
8808  is accessed with special instructions, e.g.:
8809 \layout Verse
8810
8811
8812 \family typewriter
8813 sfr at 0x78 IoPort;\SpecialChar ~
8814 \SpecialChar ~
8815 /* define a var in I/O space at 78h called IoPort */
8816
8817 \layout Standard
8818
8819 Writing 0x01 to this variable generates the assembly code:
8820 \layout Verse
8821
8822
8823 \family typewriter
8824 3E 01\SpecialChar ~
8825 \SpecialChar ~
8826 \SpecialChar ~
8827 \SpecialChar ~
8828 \SpecialChar ~
8829 \SpecialChar ~
8830 ld a,#0x01
8831 \newline
8832 D3 78\SpecialChar ~
8833 \SpecialChar ~
8834 \SpecialChar ~
8835 \SpecialChar ~
8836 \SpecialChar ~
8837 \SpecialChar ~
8838 out (_IoPort),a
8839 \layout Subsubsection
8840
8841 banked sfr
8842 \begin_inset LatexCommand \index{sfr}
8843
8844 \end_inset
8845
8846  (in/out to 16-bit addresses)
8847 \layout Standard
8848
8849 The keyword
8850 \emph on
8851 banked
8852 \emph default
8853  is used to support 16 bit addresses in I/O memory e.g.:
8854 \layout Verse
8855
8856
8857 \family typewriter
8858 sfr banked at
8859 \begin_inset LatexCommand \index{at}
8860
8861 \end_inset
8862
8863  0x123 IoPort;
8864 \layout Standard
8865
8866 Writing 0x01 to this variable generates the assembly code:
8867 \layout Verse
8868
8869
8870 \family typewriter
8871 01 23 01\SpecialChar ~
8872 \SpecialChar ~
8873 \SpecialChar ~
8874 ld bc,#_IoPort
8875 \newline
8876 3E 01\SpecialChar ~
8877 \SpecialChar ~
8878 \SpecialChar ~
8879 \SpecialChar ~
8880 \SpecialChar ~
8881 \SpecialChar ~
8882 ld a,#0x01
8883 \newline
8884 ED 79\SpecialChar ~
8885 \SpecialChar ~
8886 \SpecialChar ~
8887 \SpecialChar ~
8888 \SpecialChar ~
8889 \SpecialChar ~
8890 out (c),a
8891 \layout Subsubsection
8892
8893 sfr
8894 \begin_inset LatexCommand \index{sfr}
8895
8896 \end_inset
8897
8898  (in0/out0 to 8 bit addresses on Z180
8899 \begin_inset LatexCommand \index{Z180}
8900
8901 \end_inset
8902
8903 /HD64180
8904 \begin_inset LatexCommand \index{HD64180}
8905
8906 \end_inset
8907
8908 )
8909 \layout Standard
8910
8911 The compiler option -
8912 \begin_inset ERT
8913 status Collapsed
8914
8915 \layout Standard
8916
8917 \backslash
8918 /
8919 \end_inset
8920
8921 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
8922 portmode
8923 \begin_inset LatexCommand \index{\#pragma portmode}
8924
8925 \end_inset
8926
8927 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
8928 ns
8929 \family typewriter
8930 in0/out0
8931 \family default
8932  instead of
8933 \family typewriter
8934 in/out
8935 \family default
8936 .
8937  If you include the file z180.h this will be set automatically.
8938 \layout Subsection
8939
8940 HC08 Storage Class
8941 \begin_inset LatexCommand \index{Storage class}
8942
8943 \end_inset
8944
8945  Language Extensions
8946 \layout Subsubsection
8947
8948 data
8949 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8950
8951 \end_inset
8952
8953
8954 \layout Standard
8955
8956 The data storage class declares a variable that resides in the first 256
8957  bytes of memory (the direct page).
8958  The HC08 is most efficient at accessing variables (especially pointers)
8959  stored here.
8960 \layout Subsubsection
8961
8962 xdata
8963 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8964
8965 \end_inset
8966
8967
8968 \layout Standard
8969
8970 The xdata storage class declares a variable that can reside anywhere in
8971  memory.
8972  This is the default if no storage class is specified.
8973
8974 \layout Section
8975
8976 Absolute Addressing
8977 \begin_inset LatexCommand \index{Absolute addressing}
8978
8979 \end_inset
8980
8981
8982 \layout Standard
8983
8984 Data items can be assigned an absolute address with the
8985 \emph on
8986 at
8987 \begin_inset LatexCommand \index{at}
8988
8989 \end_inset
8990
8991  <address>
8992 \emph default
8993  keyword, in addition to a storage class, e.g.:
8994 \layout Verse
8995
8996
8997 \family typewriter
8998 xdata
8999 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9000
9001 \end_inset
9002
9003  at
9004 \begin_inset LatexCommand \index{at}
9005
9006 \end_inset
9007
9008  0x7ffe unsigned int chksum;
9009 \layout Standard
9010
9011 In the above example the variable chksum will located at 0x7ffe and 0x7fff
9012  of the external ram.
9013  The compiler does
9014 \emph on
9015 not
9016 \emph default
9017  reserve any space for variables declared in this way (they are implemented
9018  with an equate in the assembler).
9019  Thus it is left to the programmer to make sure there are no overlaps with
9020  other variables that are declared without the absolute address.
9021  The assembler listing file (.lst
9022 \begin_inset LatexCommand \index{<file>.lst}
9023
9024 \end_inset
9025
9026 ) and the linker output files (.rst
9027 \begin_inset LatexCommand \index{<file>.rst}
9028
9029 \end_inset
9030
9031 ) and (.map
9032 \begin_inset LatexCommand \index{<file>.map}
9033
9034 \end_inset
9035
9036 ) are good places to look for such overlaps.
9037  Variables with an absolute address are
9038 \emph on
9039 not
9040 \emph default
9041  initialized
9042 \begin_inset LatexCommand \index{Variable initialization}
9043
9044 \end_inset
9045
9046 .
9047 \layout Standard
9048
9049 In case of memory mapped I/O devices the keyword
9050 \emph on
9051 volatile
9052 \emph default
9053  should be used to tell the compiler that accesses might not be optimized
9054  away:
9055 \layout Verse
9056
9057
9058 \family typewriter
9059 volatile
9060 \begin_inset LatexCommand \index{volatile}
9061
9062 \end_inset
9063
9064  xdata
9065 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9066
9067 \end_inset
9068
9069  at
9070 \begin_inset LatexCommand \index{at}
9071
9072 \end_inset
9073
9074  0x8000 unsigned char PORTA_8255;
9075 \layout Standard
9076
9077 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9078 r) array
9079 \family typewriter
9080 \size footnotesize
9081
9082 \begin_inset LatexCommand \index{Aligned array}
9083
9084 \end_inset
9085
9086
9087 \family default
9088 \size default
9089  starts at a block (256 byte) boundary
9090 \begin_inset LatexCommand \index{block boundary}
9091
9092 \end_inset
9093
9094  (section
9095 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9096
9097 \end_inset
9098
9099  has an example).
9100 \newline
9101 Absolute addresses can be specified for variables in all storage classes,
9102  e.g.:
9103 \layout Verse
9104
9105
9106 \family typewriter
9107 bit
9108 \begin_inset LatexCommand \index{bit}
9109
9110 \end_inset
9111
9112  at
9113 \begin_inset LatexCommand \index{at}
9114
9115 \end_inset
9116
9117  0x02 bvar;
9118 \layout Standard
9119
9120 The above example will allocate the variable at offset 0x02 in the bit-addressab
9121 le space.
9122  There is no real advantage to assigning absolute addresses to variables
9123  in this manner, unless you want strict control over all the variables allocated.
9124  One possible use would be to write hardware portable code.
9125  For example, if you have a routine that uses one or more of the microcontroller
9126  I/O pins, and such pins are different for two different hardwares, you
9127  can declare the I/O pins in your routine using:
9128 \layout Verse
9129
9130
9131 \family typewriter
9132 extern volatile bit SDI;
9133 \newline
9134 extern volatile bit SCLK;
9135 \newline
9136 extern volatile bit CPOL;
9137 \newline
9138
9139 \newline
9140 void DS1306_put(unsigned char value)
9141 \newline
9142 {
9143 \newline
9144 \SpecialChar ~
9145 \SpecialChar ~
9146 \SpecialChar ~
9147 \SpecialChar ~
9148 unsigned char mask=0x80;
9149 \newline
9150
9151 \newline
9152 \SpecialChar ~
9153 \SpecialChar ~
9154 \SpecialChar ~
9155 \SpecialChar ~
9156 while(mask)
9157 \newline
9158 \SpecialChar ~
9159 \SpecialChar ~
9160 \SpecialChar ~
9161 \SpecialChar ~
9162 {
9163 \newline
9164 \SpecialChar ~
9165 \SpecialChar ~
9166 \SpecialChar ~
9167 \SpecialChar ~
9168 \SpecialChar ~
9169 \SpecialChar ~
9170 \SpecialChar ~
9171 \SpecialChar ~
9172 SDI=(value & mask)?1:0;
9173 \newline
9174 \SpecialChar ~
9175 \SpecialChar ~
9176 \SpecialChar ~
9177 \SpecialChar ~
9178 \SpecialChar ~
9179 \SpecialChar ~
9180 \SpecialChar ~
9181 \SpecialChar ~
9182 SCLK=!CPOL;
9183 \newline
9184 \SpecialChar ~
9185 \SpecialChar ~
9186 \SpecialChar ~
9187 \SpecialChar ~
9188 \SpecialChar ~
9189 \SpecialChar ~
9190 \SpecialChar ~
9191 \SpecialChar ~
9192 SCLK=CPOL;
9193 \newline
9194 \SpecialChar ~
9195 \SpecialChar ~
9196 \SpecialChar ~
9197 \SpecialChar ~
9198 \SpecialChar ~
9199 \SpecialChar ~
9200 \SpecialChar ~
9201 \SpecialChar ~
9202 mask/=2;
9203 \newline
9204 \SpecialChar ~
9205 \SpecialChar ~
9206 \SpecialChar ~
9207 \SpecialChar ~
9208 }
9209 \newline
9210 }
9211 \layout Standard
9212
9213 Then, someplace in the code for the first hardware you would use
9214 \layout Verse
9215
9216
9217 \family typewriter
9218 bit at 0x80 SDI;\SpecialChar ~
9219 \SpecialChar ~
9220 \SpecialChar ~
9221 \SpecialChar ~
9222 /* I/O port 0, bit 0 */
9223 \newline
9224 bit at 0x81 SCLK;\SpecialChar ~
9225 \SpecialChar ~
9226 \SpecialChar ~
9227 /* I/O port 0, bit 1 */
9228 \newline
9229 bit CPOL;\SpecialChar ~
9230 \SpecialChar ~
9231 \SpecialChar ~
9232 \SpecialChar ~
9233 \SpecialChar ~
9234 \SpecialChar ~
9235 \SpecialChar ~
9236 \SpecialChar ~
9237 \SpecialChar ~
9238 \SpecialChar ~
9239 \SpecialChar ~
9240 /* This is a variable, let the linker allocate this one */
9241 \layout Standard
9242
9243 Similarly, for the second hardware you would use
9244 \layout Verse
9245
9246
9247 \family typewriter
9248 bit at 0x83 SDI;\SpecialChar ~
9249 \SpecialChar ~
9250 \SpecialChar ~
9251 \SpecialChar ~
9252 /* I/O port 0, bit 3 */
9253 \newline
9254 bit at 0x91 SCLK;\SpecialChar ~
9255 \SpecialChar ~
9256 \SpecialChar ~
9257 /* I/O port 1, bit 1 */
9258 \newline
9259 bit
9260 \begin_inset LatexCommand \index{bit}
9261
9262 \end_inset
9263
9264  CPOL;\SpecialChar ~
9265 \SpecialChar ~
9266 \SpecialChar ~
9267 \SpecialChar ~
9268 \SpecialChar ~
9269 \SpecialChar ~
9270 \SpecialChar ~
9271 \SpecialChar ~
9272 \SpecialChar ~
9273 \SpecialChar ~
9274 \SpecialChar ~
9275 /* This is a variable, let the linker allocate this one */
9276 \layout Standard
9277
9278 and you can use the same hardware dependent routine without changes, as
9279  for example in a library.
9280  This is somehow similar to sbit, but only one absolute address has to be
9281  specified in the whole project.
9282 \layout Section
9283
9284 Parameters
9285 \begin_inset LatexCommand \index{Parameters}
9286
9287 \end_inset
9288
9289
9290 \begin_inset LatexCommand \index{function parameter}
9291
9292 \end_inset
9293
9294  & Local Variables
9295 \begin_inset LatexCommand \index{local variables}
9296
9297 \end_inset
9298
9299
9300 \layout Standard
9301
9302 Automatic (local) variables and parameters to functions can either be placed
9303  on the stack or in data-space.
9304  The default action of the compiler is to place these variables in the internal
9305  RAM (for small model) or external RAM (for large model).
9306  This in fact makes them similar to
9307 \emph on
9308 static
9309 \begin_inset LatexCommand \index{static}
9310
9311 \end_inset
9312
9313
9314 \emph default
9315  so by default functions are non-reentrant
9316 \begin_inset LatexCommand \index{reentrant}
9317
9318 \end_inset
9319
9320 .
9321
9322 \newline
9323
9324 \newline
9325 They can be placed on the stack
9326 \begin_inset LatexCommand \index{stack}
9327
9328 \end_inset
9329
9330  either by using the
9331 \emph on
9332  -
9333 \begin_inset ERT
9334 status Collapsed
9335
9336 \layout Standard
9337
9338 \backslash
9339 /
9340 \end_inset
9341
9342 -stack-auto
9343 \begin_inset LatexCommand \index{-\/-stack-auto}
9344
9345 \end_inset
9346
9347
9348 \emph default
9349  option or by using the
9350 \emph on
9351 reentrant
9352 \begin_inset LatexCommand \index{reentrant}
9353
9354 \end_inset
9355
9356
9357 \emph default
9358  keyword in the function declaration, e.g.:
9359 \layout Verse
9360
9361
9362 \family typewriter
9363 unsigned char foo(char i) reentrant
9364 \newline
9365 {
9366 \newline
9367 \SpecialChar ~
9368 \SpecialChar ~
9369 \SpecialChar ~
9370 \SpecialChar ~
9371 ...
9372
9373 \newline
9374 }
9375 \layout Standard
9376
9377 Since stack space on 8051 is limited, the
9378 \emph on
9379 reentrant
9380 \emph default
9381 keyword or the
9382 \emph on
9383  -
9384 \begin_inset ERT
9385 status Collapsed
9386
9387 \layout Standard
9388
9389 \backslash
9390 /
9391 \end_inset
9392
9393 -stack-auto
9394 \emph default
9395  option should be used sparingly.
9396  Note that the reentrant keyword just means that the parameters & local
9397  variables will be allocated to the stack, it
9398 \emph on
9399 does not
9400 \emph default
9401  mean that the function is register bank
9402 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9403
9404 \end_inset
9405
9406  independent.
9407 \newline
9408
9409 \newline
9410 Local variables
9411 \begin_inset LatexCommand \index{local variables}
9412
9413 \end_inset
9414
9415  can be assigned storage classes and absolute
9416 \begin_inset LatexCommand \index{Absolute addressing}
9417
9418 \end_inset
9419
9420  addresses, e.g.:
9421 \layout Verse
9422
9423
9424 \family typewriter
9425 unsigned char foo()
9426 \newline
9427 {
9428 \newline
9429 \SpecialChar ~
9430 \SpecialChar ~
9431 \SpecialChar ~
9432 \SpecialChar ~
9433 xdata unsigned char i;
9434 \newline
9435 \SpecialChar ~
9436 \SpecialChar ~
9437 \SpecialChar ~
9438 \SpecialChar ~
9439 bit bvar;
9440 \newline
9441 \SpecialChar ~
9442 \SpecialChar ~
9443 \SpecialChar ~
9444 \SpecialChar ~
9445 data at
9446 \begin_inset LatexCommand \index{at}
9447
9448 \end_inset
9449
9450  0x31 unsigned char j;
9451 \newline
9452 \SpecialChar ~
9453 \SpecialChar ~
9454 \SpecialChar ~
9455 \SpecialChar ~
9456 ...
9457
9458 \newline
9459 }
9460 \layout Standard
9461
9462 In the above example the variable
9463 \emph on
9464 i
9465 \emph default
9466  will be allocated in the external ram,
9467 \emph on
9468 bvar
9469 \emph default
9470  in bit addressable space and
9471 \emph on
9472  j
9473 \emph default
9474  in internal ram.
9475  When compiled with
9476 \emph on
9477 -
9478 \begin_inset ERT
9479 status Collapsed
9480
9481 \layout Standard
9482
9483 \backslash
9484 /
9485 \end_inset
9486
9487 -stack-auto
9488 \emph default
9489  or when a function is declared as
9490 \emph on
9491 reentrant
9492 \emph default
9493  this should only be done for static variables.
9494 \layout Standard
9495
9496 Parameters
9497 \begin_inset LatexCommand \index{function parameter}
9498
9499 \end_inset
9500
9501  however are not allowed any storage class
9502 \begin_inset LatexCommand \index{Storage class}
9503
9504 \end_inset
9505
9506 , (storage classes for parameters will be ignored), their allocation is
9507  governed by the memory model in use, and the reentrancy options.
9508 \layout Section
9509
9510 Overlaying
9511 \begin_inset LatexCommand \label{sub:Overlaying}
9512
9513 \end_inset
9514
9515
9516 \begin_inset LatexCommand \index{Overlaying}
9517
9518 \end_inset
9519
9520
9521 \layout Standard
9522
9523 For non-reentrant
9524 \begin_inset LatexCommand \index{reentrant}
9525
9526 \end_inset
9527
9528  functions SDCC will try to reduce internal ram space usage by overlaying
9529  parameters and local variables of a function (if possible).
9530  Parameters and local variables
9531 \begin_inset LatexCommand \index{local variables}
9532
9533 \end_inset
9534
9535  of a function will be allocated to an overlayable segment if the function
9536  has
9537 \emph on
9538 no other function calls and the function is non-reentrant and the memory
9539  model
9540 \begin_inset LatexCommand \index{Memory model}
9541
9542 \end_inset
9543
9544  is small.
9545
9546 \emph default
9547  If an explicit storage class
9548 \begin_inset LatexCommand \index{Storage class}
9549
9550 \end_inset
9551
9552  is specified for a local variable, it will NOT be overlayed.
9553 \layout Standard
9554
9555 Note that the compiler (not the linkage editor) makes the decision for overlayin
9556 g the data items.
9557  Functions that are called from an interrupt service routine should be preceded
9558  by a #pragma\SpecialChar ~
9559 nooverlay
9560 \begin_inset LatexCommand \index{\#pragma nooverlay}
9561
9562 \end_inset
9563
9564  if they are not reentrant.
9565 \layout Standard
9566
9567 Also note that the compiler does not do any processing of inline assembler
9568  code, so the compiler might incorrectly assign local variables and parameters
9569  of a function into the overlay segment if the inline assembler code calls
9570  other c-functions that might use the overlay.
9571  In that case the #pragma\SpecialChar ~
9572 nooverlay should be used.
9573 \layout Standard
9574
9575 Parameters and local variables of functions that contain 16 or 32 bit multiplica
9576 tion
9577 \begin_inset LatexCommand \index{Multiplication}
9578
9579 \end_inset
9580
9581  or division
9582 \begin_inset LatexCommand \index{Division}
9583
9584 \end_inset
9585
9586  will NOT be overlayed since these are implemented using external functions,
9587  e.g.:
9588 \layout Verse
9589
9590
9591 \family typewriter
9592 #pragma save
9593 \newline
9594 #pragma nooverlay
9595 \begin_inset LatexCommand \index{\#pragma nooverlay}
9596
9597 \end_inset
9598
9599
9600 \newline
9601 void set_error(unsigned char errcd)
9602 \newline
9603 {
9604 \newline
9605 \SpecialChar ~
9606 \SpecialChar ~
9607 \SpecialChar ~
9608 \SpecialChar ~
9609 P3 = errcd;
9610 \newline
9611 }
9612 \newline
9613 #pragma restore
9614 \newline
9615
9616 \newline
9617 void some_isr () interrupt
9618 \begin_inset LatexCommand \index{interrupt}
9619
9620 \end_inset
9621
9622  2
9623 \newline
9624 {
9625 \newline
9626 \SpecialChar ~
9627 \SpecialChar ~
9628 \SpecialChar ~
9629 \SpecialChar ~
9630 ...
9631 \newline
9632 \SpecialChar ~
9633 \SpecialChar ~
9634 \SpecialChar ~
9635 \SpecialChar ~
9636 set_error(10);
9637 \newline
9638 \SpecialChar ~
9639 \SpecialChar ~
9640 \SpecialChar ~
9641 \SpecialChar ~
9642 ...
9643
9644 \newline
9645 }
9646 \layout Standard
9647
9648 In the above example the parameter
9649 \emph on
9650 errcd
9651 \emph default
9652  for the function
9653 \emph on
9654 set_error
9655 \emph default
9656  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
9657 nooverlay was
9658  not present, this could cause unpredictable runtime behavior when called
9659  from an interrupt service routine.
9660  The #pragma\SpecialChar ~
9661 nooverlay ensures that the parameters and local variables for
9662  the function are NOT overlayed.
9663 \layout Section
9664
9665 Interrupt Service Routines
9666 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
9667
9668 \end_inset
9669
9670
9671 \layout Subsection
9672
9673 General Information
9674 \layout Standard
9675
9676 SDCC allows
9677 \emph on
9678 i
9679 \emph default
9680 nterrupt
9681 \emph on
9682 s
9683 \emph default
9684 ervice
9685 \emph on
9686 r
9687 \emph default
9688 outines to be coded in C, with some extended keywords.
9689 \layout Verse
9690
9691
9692 \family typewriter
9693 void timer_isr (void) interrupt 1 using 1
9694 \newline
9695 {
9696 \newline
9697 \SpecialChar ~
9698 \SpecialChar ~
9699 \SpecialChar ~
9700 \SpecialChar ~
9701 ...
9702
9703 \newline
9704 }
9705 \layout Standard
9706
9707 The optional number following the
9708 \emph on
9709 interrupt
9710 \begin_inset LatexCommand \index{interrupt}
9711
9712 \end_inset
9713
9714
9715 \emph default
9716  keyword is the interrupt number this routine will service.
9717  When present, the compiler will insert a call to this routine in the interrupt
9718  vector table for the interrupt number specified.
9719  If you have multiple source files in your project, interrupt service routines
9720  can be present in any of them, but a prototype of the isr MUST be present
9721  or included in the file that contains the function
9722 \emph on
9723 main
9724 \emph default
9725 .
9726  The
9727 \emph on
9728 using
9729 \emph default
9730  keyword can be used to tell the compiler to use the specified register
9731  bank (8051 specific) when generating code for this function.
9732
9733 \newline
9734
9735 \layout Standard
9736
9737 Interrupt service routines open the door for some very interesting bugs:
9738
9739 \layout Standard
9740
9741 If the interrupt service routines changes variables which are accessed by
9742  other functions these variables should be declared
9743 \emph on
9744 volatile
9745 \emph default
9746
9747 \begin_inset LatexCommand \index{volatile}
9748
9749 \end_inset
9750
9751 .
9752
9753 \layout Standard
9754
9755 If the access to these variables is not
9756 \emph on
9757 atomic
9758 \begin_inset LatexCommand \index{atomic access}
9759
9760 \end_inset
9761
9762
9763 \emph default
9764  (i.e.
9765  the processor needs more than one instruction for the access and could
9766  be interrupted while accessing the variable) the interrupt must disabled
9767  during the access to avoid inconsistent data.
9768  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
9769  and should be protected by disabling interrupts.
9770  You're not automatically on the safe side if you use 8 bit variables though.
9771  We need an example here: f.e.
9772  on the 8051 the harmless looking
9773 \begin_inset Quotes srd
9774 \end_inset
9775
9776
9777 \family typewriter
9778 flags\SpecialChar ~
9779 |=\SpecialChar ~
9780 0x80;
9781 \family default
9782
9783 \begin_inset Quotes sld
9784 \end_inset
9785
9786  is not atomic if
9787 \family typewriter
9788 flags
9789 \family default
9790  resides in xdata.
9791  Setting
9792 \begin_inset Quotes srd
9793 \end_inset
9794
9795
9796 \family typewriter
9797 flags\SpecialChar ~
9798 |=\SpecialChar ~
9799 0x40;
9800 \family default
9801
9802 \begin_inset Quotes sld
9803 \end_inset
9804
9805  from within an interrupt routine might get lost if the interrupt occurs
9806  at the wrong time.
9807
9808 \begin_inset Quotes sld
9809 \end_inset
9810
9811
9812 \family typewriter
9813 counter\SpecialChar ~
9814 +=\SpecialChar ~
9815 8;
9816 \family default
9817
9818 \begin_inset Quotes srd
9819 \end_inset
9820
9821  is not atomic on the 8051 even if
9822 \family typewriter
9823 counter
9824 \family default
9825  is located in data memory.
9826  Bugs like these are hard to reproduce and can cause a lot of trouble.
9827
9828 \layout Standard
9829
9830 A special note here, int (16 bit) and long (32 bit) integer division
9831 \begin_inset LatexCommand \index{Division}
9832
9833 \end_inset
9834
9835 , multiplication
9836 \begin_inset LatexCommand \index{Multiplication}
9837
9838 \end_inset
9839
9840  & modulus
9841 \begin_inset LatexCommand \index{Modulus}
9842
9843 \end_inset
9844
9845  and floating-point
9846 \begin_inset LatexCommand \index{Floating point support}
9847
9848 \end_inset
9849
9850  operations are implemented using external support routines developed in
9851  ANSI-C.
9852  If an interrupt service routine needs to do any of these operations then
9853  the support routines (as mentioned in a following section) will have to
9854  be recompiled using the
9855 \emph on
9856  -
9857 \begin_inset ERT
9858 status Collapsed
9859
9860 \layout Standard
9861
9862 \backslash
9863 /
9864 \end_inset
9865
9866 -stack-auto
9867 \begin_inset LatexCommand \index{-\/-stack-auto}
9868
9869 \end_inset
9870
9871
9872 \emph default
9873  option and the source file will need to be compiled using the
9874 \emph on
9875 -
9876 \begin_inset ERT
9877 status Collapsed
9878
9879 \layout Standard
9880
9881 \backslash
9882 /
9883 \end_inset
9884
9885 -int-long-reent
9886 \emph default
9887
9888 \begin_inset LatexCommand \index{-\/-int-long-reent}
9889
9890 \end_inset
9891
9892  compiler option.
9893 \layout Standard
9894
9895 Calling other functions from an interrupt service routine is not recommended,
9896  avoid it if possible.
9897  Note that when some function is called from an interrupt service routine
9898  it should be preceded by a #pragma\SpecialChar ~
9899 nooverlay
9900 \begin_inset LatexCommand \index{\#pragma nooverlay}
9901
9902 \end_inset
9903
9904  if it is not reentrant.
9905  Furthermore nonreentrant functions should not be called from the main program
9906  while the interrupt service routine might be active.
9907
9908 \newline
9909
9910 \newline
9911 Also see section
9912 \begin_inset LatexCommand \ref{sub:Overlaying}
9913
9914 \end_inset
9915
9916 \SpecialChar ~
9917 about Overlaying and section
9918 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
9919
9920 \end_inset
9921
9922 \SpecialChar ~
9923 about Functions using private register banks.
9924 \layout Subsection
9925
9926 MCS51/DS390 Interrupt Service Routines
9927 \layout Standard
9928
9929 Interrupt numbers and the corresponding address & descriptions for the Standard
9930  8051/8052 are listed below.
9931  SDCC will automatically adjust the interrupt vector table to the maximum
9932  interrupt number specified.
9933 \newline
9934
9935 \layout Standard
9936 \align center
9937
9938 \begin_inset  Tabular
9939 <lyxtabular version="3" rows="7" columns="3">
9940 <features>
9941 <column alignment="center" valignment="top" leftline="true" width="0in">
9942 <column alignment="center" valignment="top" leftline="true" width="0in">
9943 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
9944 <row topline="true" bottomline="true">
9945 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9946 \begin_inset Text
9947
9948 \layout Standard
9949
9950 Interrupt #
9951 \end_inset
9952 </cell>
9953 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9954 \begin_inset Text
9955
9956 \layout Standard
9957
9958 Description
9959 \end_inset
9960 </cell>
9961 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9962 \begin_inset Text
9963
9964 \layout Standard
9965
9966 Vector Address
9967 \end_inset
9968 </cell>
9969 </row>
9970 <row topline="true">
9971 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9972 \begin_inset Text
9973
9974 \layout Standard
9975
9976 0
9977 \end_inset
9978 </cell>
9979 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9980 \begin_inset Text
9981
9982 \layout Standard
9983
9984 External 0
9985 \end_inset
9986 </cell>
9987 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
9988 \begin_inset Text
9989
9990 \layout Standard
9991
9992 0x0003
9993 \end_inset
9994 </cell>
9995 </row>
9996 <row topline="true">
9997 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
9998 \begin_inset Text
9999
10000 \layout Standard
10001
10002 1
10003 \end_inset
10004 </cell>
10005 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10006 \begin_inset Text
10007
10008 \layout Standard
10009
10010 Timer 0
10011 \end_inset
10012 </cell>
10013 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10014 \begin_inset Text
10015
10016 \layout Standard
10017
10018 0x000B
10019 \end_inset
10020 </cell>
10021 </row>
10022 <row topline="true">
10023 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10024 \begin_inset Text
10025
10026 \layout Standard
10027
10028 2
10029 \end_inset
10030 </cell>
10031 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10032 \begin_inset Text
10033
10034 \layout Standard
10035
10036 External 1
10037 \end_inset
10038 </cell>
10039 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10040 \begin_inset Text
10041
10042 \layout Standard
10043
10044 0x0013
10045 \end_inset
10046 </cell>
10047 </row>
10048 <row topline="true">
10049 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10050 \begin_inset Text
10051
10052 \layout Standard
10053
10054 3
10055 \end_inset
10056 </cell>
10057 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10058 \begin_inset Text
10059
10060 \layout Standard
10061
10062 Timer 1
10063 \end_inset
10064 </cell>
10065 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10066 \begin_inset Text
10067
10068 \layout Standard
10069
10070 0x001B
10071 \end_inset
10072 </cell>
10073 </row>
10074 <row topline="true">
10075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10076 \begin_inset Text
10077
10078 \layout Standard
10079
10080 4
10081 \end_inset
10082 </cell>
10083 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10084 \begin_inset Text
10085
10086 \layout Standard
10087
10088 Serial
10089 \end_inset
10090 </cell>
10091 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10092 \begin_inset Text
10093
10094 \layout Standard
10095
10096 0x0023
10097 \end_inset
10098 </cell>
10099 </row>
10100 <row topline="true" bottomline="true">
10101 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10102 \begin_inset Text
10103
10104 \layout Standard
10105
10106 5
10107 \end_inset
10108 </cell>
10109 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10110 \begin_inset Text
10111
10112 \layout Standard
10113
10114 Timer 2 (8052)
10115 \end_inset
10116 </cell>
10117 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10118 \begin_inset Text
10119
10120 \layout Standard
10121
10122 0x002B
10123 \end_inset
10124 </cell>
10125 </row>
10126 </lyxtabular>
10127
10128 \end_inset
10129
10130
10131 \newline
10132
10133 \layout Standard
10134
10135 If the interrupt service routine is defined without
10136 \emph on
10137 using
10138 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10139
10140 \end_inset
10141
10142
10143 \emph default
10144  a register bank or with register bank 0 (
10145 \emph on
10146 using
10147 \emph default
10148  0), the compiler will save the registers used by itself on the stack upon
10149  entry and restore them at exit, however if such an interrupt service routine
10150  calls another function then the entire register bank will be saved on the
10151  stack.
10152  This scheme may be advantageous for small interrupt service routines which
10153  have low register usage.
10154 \layout Standard
10155
10156 If the interrupt service routine is defined to be using a specific register
10157  bank then only
10158 \emph on
10159 a, b, dptr
10160 \emph default
10161  & psw are saved and restored, if such an interrupt service routine calls
10162  another function (using another register bank) then the entire register
10163  bank of the called function will be saved on the stack.
10164  This scheme is recommended for larger interrupt service routines.
10165 \layout Subsection
10166
10167 HC08 Interrupt Service Routines
10168 \layout Standard
10169
10170 Since the number of interrupts available is chip specific and the interrupt
10171  vector table always ends at the last byte of memory, the interrupt numbers
10172  corresponds to the interrupt vectors in reverse order of address.
10173  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
10174  2 will use the interrupt vector at 0xfffa, and so on.
10175  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
10176  this way; instead see section
10177 \begin_inset LatexCommand \ref{sub:Startup-Code}
10178
10179 \end_inset
10180
10181  for details on customizing startup.
10182 \layout Section
10183
10184 Enabling and Disabling Interrupts
10185 \layout Subsection
10186
10187 Critical Functions and Critical Statements
10188 \layout Standard
10189
10190 A special keyword may be associated with a block or a function declaring
10191  it as
10192 \emph on
10193 critical
10194 \emph default
10195 .
10196  SDCC will generate code to disable all interrupts
10197 \begin_inset LatexCommand \index{interrupt}
10198
10199 \end_inset
10200
10201  upon entry to a critical function and restore the interrupt enable to the
10202  previous state before returning.
10203  Nesting critical functions will need one additional byte on the stack
10204 \begin_inset LatexCommand \index{stack}
10205
10206 \end_inset
10207
10208  for each call.
10209 \layout Verse
10210
10211
10212 \family typewriter
10213 int foo () critical
10214 \begin_inset LatexCommand \index{critical}
10215
10216 \end_inset
10217
10218
10219 \newline
10220 {
10221 \newline
10222 \SpecialChar ~
10223 \SpecialChar ~
10224 \SpecialChar ~
10225 \SpecialChar ~
10226 ...
10227
10228 \newline
10229 \SpecialChar ~
10230 \SpecialChar ~
10231 \SpecialChar ~
10232 \SpecialChar ~
10233 ...
10234
10235 \newline
10236 }
10237 \layout Standard
10238
10239 The critical attribute maybe used with other attributes like
10240 \emph on
10241 reentrant.
10242 \emph default
10243
10244 \newline
10245 The keyword
10246 \emph on
10247 critical
10248 \emph default
10249  may also be used to disable interrupts more locally:
10250 \layout Verse
10251
10252
10253 \family typewriter
10254 critical{ i++; }
10255 \layout Standard
10256
10257 More than one statement could have been included in the block.
10258 \layout Subsection
10259
10260 Enabling and Disabling Interrupts directly
10261 \layout Standard
10262
10263 Interrupts
10264 \begin_inset LatexCommand \index{interrupt}
10265
10266 \end_inset
10267
10268  can also be disabled and enabled directly (8051):
10269 \layout Verse
10270
10271
10272 \family typewriter
10273 EA = 0;\SpecialChar ~
10274 \SpecialChar ~
10275 \SpecialChar ~
10276 \SpecialChar ~
10277 \SpecialChar ~
10278 \SpecialChar ~
10279 \SpecialChar ~
10280 \SpecialChar ~
10281 \SpecialChar ~
10282 \SpecialChar ~
10283 \SpecialChar ~
10284 \SpecialChar ~
10285 or:\SpecialChar ~
10286 \SpecialChar ~
10287 \SpecialChar ~
10288 \SpecialChar ~
10289 \SpecialChar ~
10290 \SpecialChar ~
10291 \SpecialChar ~
10292 \SpecialChar ~
10293 \SpecialChar ~
10294 \SpecialChar ~
10295 \SpecialChar ~
10296 EA_SAVE = EA;
10297 \layout Verse
10298
10299
10300 \family typewriter
10301 ...\SpecialChar ~
10302 \SpecialChar ~
10303 \SpecialChar ~
10304 \SpecialChar ~
10305 \SpecialChar ~
10306 \SpecialChar ~
10307 \SpecialChar ~
10308 \SpecialChar ~
10309 \SpecialChar ~
10310 \SpecialChar ~
10311 \SpecialChar ~
10312 \SpecialChar ~
10313 \SpecialChar ~
10314 \SpecialChar ~
10315 \SpecialChar ~
10316 \SpecialChar ~
10317 \SpecialChar ~
10318 \SpecialChar ~
10319 \SpecialChar ~
10320 \SpecialChar ~
10321 \SpecialChar ~
10322 \SpecialChar ~
10323 \SpecialChar ~
10324 \SpecialChar ~
10325 \SpecialChar ~
10326 \SpecialChar ~
10327 \SpecialChar ~
10328 \SpecialChar ~
10329 \SpecialChar ~
10330 \SpecialChar ~
10331 EA = 0;
10332 \layout Verse
10333
10334
10335 \family typewriter
10336 EA = 1;\SpecialChar ~
10337 \SpecialChar ~
10338 \SpecialChar ~
10339 \SpecialChar ~
10340 \SpecialChar ~
10341 \SpecialChar ~
10342 \SpecialChar ~
10343 \SpecialChar ~
10344 \SpecialChar ~
10345 \SpecialChar ~
10346 \SpecialChar ~
10347 \SpecialChar ~
10348 \SpecialChar ~
10349 \SpecialChar ~
10350 \SpecialChar ~
10351 \SpecialChar ~
10352 \SpecialChar ~
10353 \SpecialChar ~
10354 \SpecialChar ~
10355 \SpecialChar ~
10356 \SpecialChar ~
10357 \SpecialChar ~
10358 \SpecialChar ~
10359 \SpecialChar ~
10360 \SpecialChar ~
10361 \SpecialChar ~
10362 ...
10363 \layout Verse
10364
10365
10366 \family typewriter
10367 \SpecialChar ~
10368 \SpecialChar ~
10369 \SpecialChar ~
10370 \SpecialChar ~
10371 \SpecialChar ~
10372 \SpecialChar ~
10373 \SpecialChar ~
10374 \SpecialChar ~
10375 \SpecialChar ~
10376 \SpecialChar ~
10377 \SpecialChar ~
10378 \SpecialChar ~
10379 \SpecialChar ~
10380 \SpecialChar ~
10381 \SpecialChar ~
10382 \SpecialChar ~
10383 \SpecialChar ~
10384 \SpecialChar ~
10385 \SpecialChar ~
10386 \SpecialChar ~
10387 \SpecialChar ~
10388 \SpecialChar ~
10389 \SpecialChar ~
10390 \SpecialChar ~
10391 \SpecialChar ~
10392 \SpecialChar ~
10393 \SpecialChar ~
10394 \SpecialChar ~
10395 \SpecialChar ~
10396 \SpecialChar ~
10397 \SpecialChar ~
10398 \SpecialChar ~
10399 \SpecialChar ~
10400 EA = EA_SAVE;
10401 \layout Standard
10402
10403 On other architectures which have seperate opcodes for enabling and disabling
10404  interrupts you might want to make use of defines with inline assembly
10405 \begin_inset LatexCommand \index{Assembler routines}
10406
10407 \end_inset
10408
10409  (HC08):
10410 \layout Verse
10411
10412
10413 \family typewriter
10414 #define CLI _asm
10415 \begin_inset LatexCommand \index{\_asm}
10416
10417 \end_inset
10418
10419 \SpecialChar ~
10420 \SpecialChar ~
10421 cli\SpecialChar ~
10422 \SpecialChar ~
10423 _endasm
10424 \begin_inset LatexCommand \index{\_endasm}
10425
10426 \end_inset
10427
10428 ;
10429 \layout Verse
10430
10431
10432 \family typewriter
10433 #define SEI _asm\SpecialChar ~
10434 \SpecialChar ~
10435 sei\SpecialChar ~
10436 \SpecialChar ~
10437 _endasm;
10438 \layout Verse
10439
10440
10441 \family typewriter
10442 ...
10443 \layout Standard
10444
10445 Note: it is sometimes sufficient to disable only a specific interrupt source
10446  like f.e.
10447  a timer or serial interrupt by manipulating an
10448 \emph on
10449 interrupt mask
10450 \begin_inset LatexCommand \index{interrupt mask}
10451
10452 \end_inset
10453
10454
10455 \emph default
10456  register.
10457
10458 \layout Standard
10459
10460 Usually the time during which interrupts are disabled should be kept as
10461  short as possible.
10462  This minimizes both
10463 \emph on
10464 interrupt latency
10465 \emph default
10466
10467 \begin_inset LatexCommand \index{interrupt latency}
10468
10469 \end_inset
10470
10471  (the time between the occurrence of the interrupt and the execution of
10472  the first code in the interrupt routine) and
10473 \emph on
10474 interrupt jitter
10475 \emph default
10476
10477 \begin_inset LatexCommand \index{interrupt jitter}
10478
10479 \end_inset
10480
10481  (the difference between the shortest and the longest interrupt latency).
10482  These really are something different, f.e.
10483  a serial interrupt has to be served before its buffer overruns so it cares
10484  for the maximum interrupt latency, whereas it does not care about jitter.
10485  On a loudspeaker driven via a digital to analog converter which is fed
10486  by an interrupt a latency of a few milliseconds might be tolerable, whereas
10487  a much smaller jitter will be very audible.
10488 \layout Standard
10489
10490 You can reenable interrupts within an interrupt routine and on some architecture
10491 s you can make use of two (or more) levels of
10492 \emph on
10493 interrupt priorities
10494 \emph default
10495
10496 \begin_inset LatexCommand \index{interrupt priority}
10497
10498 \end_inset
10499
10500 .
10501  On some architectures which don't support interrupt priorities these can
10502  be implemented by manipulating the interrupt mask and reenabling interrupts
10503  within the interrupt routine.
10504  Don't add complexity unless you have to.
10505
10506 \layout Section
10507
10508 Functions using private register banks
10509 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
10510
10511 \end_inset
10512
10513  (mcs51/ds390)
10514 \layout Standard
10515
10516 Some architectures have support for quickly changing register sets.
10517  SDCC supports this feature with the
10518 \emph on
10519 using
10520 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10521
10522 \end_inset
10523
10524
10525 \emph default
10526  attribute (which tells the compiler to use a register bank
10527 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10528
10529 \end_inset
10530
10531  other than the default bank zero).
10532  It should only be applied to
10533 \emph on
10534 interrupt
10535 \begin_inset LatexCommand \index{interrupt}
10536
10537 \end_inset
10538
10539
10540 \emph default
10541  functions (see footnote below).
10542  This will in most circumstances make the generated ISR code more efficient
10543  since it will not have to save registers on the stack.
10544 \layout Standard
10545
10546 The
10547 \emph on
10548 using
10549 \emph default
10550  attribute will have no effect on the generated code for a
10551 \emph on
10552 non-interrupt
10553 \emph default
10554  function (but may occasionally be useful anyway
10555 \begin_inset Foot
10556 collapsed false
10557
10558 \layout Standard
10559
10560 possible exception: if a function is called ONLY from 'interrupt' functions
10561  using a particular bank, it can be declared with the same 'using' attribute
10562  as the calling 'interrupt' functions.
10563  For instance, if you have several ISRs using bank one, and all of them
10564  call memcpy(), it might make sense to create a specialized version of memcpy()
10565  'using 1', since this would prevent the ISR from having to save bank zero
10566  to the stack on entry and switch to bank zero before calling the function
10567 \end_inset
10568
10569 ).
10570 \newline
10571
10572 \emph on
10573 (pending: I don't think this has been done yet)
10574 \layout Standard
10575
10576 An
10577 \emph on
10578 interrupt
10579 \emph default
10580  function using a non-zero bank will assume that it can trash that register
10581  bank, and will not save it.
10582  Since high-priority interrupts
10583 \begin_inset LatexCommand \index{interrupt priority}
10584
10585 \end_inset
10586
10587  can interrupt low-priority ones on the 8051 and friends, this means that
10588  if a high-priority ISR
10589 \emph on
10590 using
10591 \emph default
10592  a particular bank occurs while processing a low-priority ISR
10593 \emph on
10594 using
10595 \emph default
10596  the same bank, terrible and bad things can happen.
10597  To prevent this, no single register bank should be
10598 \emph on
10599 used
10600 \emph default
10601  by both a high priority and a low priority ISR.
10602  This is probably most easily done by having all high priority ISRs use
10603  one bank and all low priority ISRs use another.
10604  If you have an ISR which can change priority at runtime, you're on your
10605  own: I suggest using the default bank zero and taking the small performance
10606  hit.
10607 \layout Standard
10608
10609 It is most efficient if your ISR calls no other functions.
10610  If your ISR must call other functions, it is most efficient if those functions
10611  use the same bank as the ISR (see note 1 below); the next best is if the
10612  called functions use bank zero.
10613  It is very inefficient to call a function using a different, non-zero bank
10614  from an ISR.
10615
10616 \layout Section
10617
10618 Startup Code
10619 \begin_inset LatexCommand \label{sub:Startup-Code}
10620
10621 \end_inset
10622
10623
10624 \begin_inset LatexCommand \index{Startup code}
10625
10626 \end_inset
10627
10628
10629 \layout Subsection
10630
10631 MCS51/DS390 Startup Code
10632 \layout Standard
10633
10634 The compiler inserts a call to the C routine
10635 \emph on
10636 _sdcc_external_startup()
10637 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
10638
10639 \end_inset
10640
10641
10642 \series bold
10643 \emph default
10644
10645 \series default
10646 at the start of the CODE area.
10647  This routine is in the runtime library
10648 \begin_inset LatexCommand \index{Runtime library}
10649
10650 \end_inset
10651
10652 .
10653  By default this routine returns 0, if this routine returns a non-zero value,
10654  the static & global variable initialization will be skipped and the function
10655  main will be invoked.
10656  Otherwise static & global variables will be initialized before the function
10657  main is invoked.
10658  You could add a
10659 \emph on
10660 _sdcc_external_startup()
10661 \emph default
10662  routine to your program to override the default if you need to setup hardware
10663  or perform some other critical operation prior to static & global variable
10664  initialization.
10665  On some mcs51 variants xdata has to be explicitly enabled before it can
10666  be accessed, this is the place to do it.
10667  See also the compiler option
10668 \emph on
10669 -
10670 \begin_inset ERT
10671 status Collapsed
10672
10673 \layout Standard
10674
10675 \backslash
10676 /
10677 \end_inset
10678
10679 -no-xinit
10680 \emph default
10681 -
10682 \emph on
10683 opt
10684 \emph default
10685
10686 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
10687
10688 \end_inset
10689
10690  and section
10691 \begin_inset LatexCommand \ref{sub:MCS51-variants}
10692
10693 \end_inset
10694
10695 \SpecialChar ~
10696 about MCS51-variants.
10697 \layout Subsection
10698
10699 HC08 Startup Code
10700 \layout Standard
10701
10702 The HC08 startup code follows the same scheme as the MCS51 startup code.
10703 \layout Subsection
10704
10705 Z80 Startup Code
10706 \layout Standard
10707
10708 On the Z80 the startup code is inserted by linking with crt0.o which is generated
10709  from sdcc/device/lib/z80/crt0.s.
10710  If you need a different startup code you can use the compiler option
10711 \emph on
10712 -
10713 \series bold
10714 \emph default
10715
10716 \begin_inset ERT
10717 status Collapsed
10718
10719 \layout Standard
10720
10721 \backslash
10722 /
10723 \end_inset
10724
10725
10726 \series default
10727 \emph on
10728 -no-std-crt0
10729 \emph default
10730
10731 \begin_inset LatexCommand \index{-\/-no-std-crt0}
10732
10733 \end_inset
10734
10735  and provide your own crt0.o.
10736
10737 \layout Section
10738
10739 Inline Assembler Code
10740 \begin_inset LatexCommand \index{Assembler routines}
10741
10742 \end_inset
10743
10744
10745 \layout Subsection
10746
10747 A Step by Step Introduction
10748 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
10749
10750 \end_inset
10751
10752
10753 \layout Standard
10754
10755 Starting from a small snippet of c-code this example shows for the MCS51
10756  how to use inline assembly, access variables, a function parameter and
10757  an array in xdata memory.
10758  The example uses an MCS51 here but is easily adapted for other architectures.
10759  This is a buffer routine which should be optimized:
10760 \layout Verse
10761
10762
10763 \family typewriter
10764 \size footnotesize
10765 unsigned char far
10766 \begin_inset LatexCommand \index{far (storage class)}
10767
10768 \end_inset
10769
10770  at
10771 \begin_inset LatexCommand \index{at}
10772
10773 \end_inset
10774
10775  0x7f00 buf[0x100];
10776 \begin_inset LatexCommand \index{Aligned array}
10777
10778 \end_inset
10779
10780
10781 \newline
10782 unsigned char head,tail;
10783 \newline
10784
10785 \newline
10786 void to_buffer( unsigned char c )
10787 \newline
10788 {
10789 \newline
10790 \SpecialChar ~
10791 \SpecialChar ~
10792 \SpecialChar ~
10793 \SpecialChar ~
10794 if( head != tail-1 )
10795 \newline
10796 \SpecialChar ~
10797 \SpecialChar ~
10798 \SpecialChar ~
10799 \SpecialChar ~
10800 \SpecialChar ~
10801 \SpecialChar ~
10802 \SpecialChar ~
10803 \SpecialChar ~
10804 buf[ head++ ] = c;
10805 \newline
10806 }
10807 \layout Standard
10808
10809 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
10810  then a corresponding buffer.asm file is generated.
10811  We define a new function
10812 \family typewriter
10813 to_buffer_asm()
10814 \family default
10815  in file buffer.c in which we cut and paste the generated code, removing
10816  unwanted comments and some ':'.
10817  Then add
10818 \begin_inset Quotes sld
10819 \end_inset
10820
10821 _asm
10822 \begin_inset Quotes srd
10823 \end_inset
10824
10825  and
10826 \begin_inset Quotes sld
10827 \end_inset
10828
10829 _endasm;
10830 \begin_inset Quotes srd
10831 \end_inset
10832
10833  to the beginning and the end of the function body:
10834 \layout Verse
10835
10836
10837 \family typewriter
10838 \size footnotesize
10839 /* With a cut and paste from the .asm file, we have something to start with.
10840 \newline
10841 \SpecialChar ~
10842 \SpecialChar ~
10843 \SpecialChar ~
10844 The function is not yet OK! (registers aren't saved) */
10845 \newline
10846 void to_buffer_asm( unsigned char c )
10847 \newline
10848 {
10849 \newline
10850 \SpecialChar ~
10851 \SpecialChar ~
10852 \SpecialChar ~
10853 \SpecialChar ~
10854 _asm
10855 \begin_inset LatexCommand \index{\_asm}
10856
10857 \end_inset
10858
10859
10860 \newline
10861 \SpecialChar ~
10862 \SpecialChar ~
10863 \SpecialChar ~
10864 \SpecialChar ~
10865 mov\SpecialChar ~
10866 \SpecialChar ~
10867 r2,dpl
10868 \newline
10869 ;buffer.c if( head != tail-1 )
10870 \newline
10871 \SpecialChar ~
10872 \SpecialChar ~
10873 \SpecialChar ~
10874 \SpecialChar ~
10875 mov\SpecialChar ~
10876 \SpecialChar ~
10877 a,_tail
10878 \newline
10879 \SpecialChar ~
10880 \SpecialChar ~
10881 \SpecialChar ~
10882 \SpecialChar ~
10883 dec\SpecialChar ~
10884 \SpecialChar ~
10885 a
10886 \newline
10887 \SpecialChar ~
10888 \SpecialChar ~
10889 \SpecialChar ~
10890 \SpecialChar ~
10891 mov\SpecialChar ~
10892 \SpecialChar ~
10893 r3,a
10894 \newline
10895 \SpecialChar ~
10896 \SpecialChar ~
10897 \SpecialChar ~
10898 \SpecialChar ~
10899 mov\SpecialChar ~
10900 \SpecialChar ~
10901 a,_head
10902 \newline
10903 \SpecialChar ~
10904 \SpecialChar ~
10905 \SpecialChar ~
10906 \SpecialChar ~
10907 cjne a,ar3,00106$
10908 \newline
10909 \SpecialChar ~
10910 \SpecialChar ~
10911 \SpecialChar ~
10912 \SpecialChar ~
10913 ret
10914 \newline
10915 00106$:
10916 \newline
10917 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
10918 \begin_inset LatexCommand \index{Aligned array}
10919
10920 \end_inset
10921
10922
10923 \newline
10924 \SpecialChar ~
10925 \SpecialChar ~
10926 \SpecialChar ~
10927 \SpecialChar ~
10928 mov\SpecialChar ~
10929 \SpecialChar ~
10930 r3,_head
10931 \newline
10932 \SpecialChar ~
10933 \SpecialChar ~
10934 \SpecialChar ~
10935 \SpecialChar ~
10936 inc\SpecialChar ~
10937 \SpecialChar ~
10938 _head
10939 \newline
10940 \SpecialChar ~
10941 \SpecialChar ~
10942 \SpecialChar ~
10943 \SpecialChar ~
10944 mov\SpecialChar ~
10945 \SpecialChar ~
10946 dpl,r3
10947 \newline
10948 \SpecialChar ~
10949 \SpecialChar ~
10950 \SpecialChar ~
10951 \SpecialChar ~
10952 mov\SpecialChar ~
10953 \SpecialChar ~
10954 dph,#(_buf >> 8)
10955 \newline
10956 \SpecialChar ~
10957 \SpecialChar ~
10958 \SpecialChar ~
10959 \SpecialChar ~
10960 mov\SpecialChar ~
10961 \SpecialChar ~
10962 a,r2
10963 \newline
10964 \SpecialChar ~
10965 \SpecialChar ~
10966 \SpecialChar ~
10967 \SpecialChar ~
10968 movx @dptr,a
10969 \newline
10970 00103$:
10971 \newline
10972 \SpecialChar ~
10973 \SpecialChar ~
10974 \SpecialChar ~
10975 \SpecialChar ~
10976 ret
10977 \newline
10978 \SpecialChar ~
10979 \SpecialChar ~
10980 \SpecialChar ~
10981 \SpecialChar ~
10982 _endasm;
10983 \newline
10984 }
10985 \layout Standard
10986
10987 The new file buffer.c should compile with only one warning about the unreferenced
10988  function argument 'c'.
10989  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
10990  (1) and finally have:
10991 \layout Verse
10992
10993
10994 \family typewriter
10995 \size footnotesize
10996 unsigned char far at 0x7f00 buf[0x100];
10997 \newline
10998 unsigned char head,tail;
10999 \newline
11000 #define USE_ASSEMBLY (1)
11001 \newline
11002
11003 \newline
11004 #if !USE_ASSEMBLY
11005 \newline
11006
11007 \newline
11008 void to_buffer( unsigned char c )
11009 \newline
11010 {
11011 \newline
11012 \SpecialChar ~
11013 \SpecialChar ~
11014 \SpecialChar ~
11015 \SpecialChar ~
11016 if( head != tail-1 )
11017 \newline
11018 \SpecialChar ~
11019 \SpecialChar ~
11020 \SpecialChar ~
11021 \SpecialChar ~
11022 \SpecialChar ~
11023 \SpecialChar ~
11024 \SpecialChar ~
11025 \SpecialChar ~
11026 buf[ head++ ] = c;
11027 \newline
11028 }
11029 \newline
11030
11031 \newline
11032 #else
11033 \newline
11034
11035 \newline
11036 void to_buffer( unsigned char c )
11037 \newline
11038 {
11039 \newline
11040 \SpecialChar ~
11041 \SpecialChar ~
11042 \SpecialChar ~
11043 \SpecialChar ~
11044 c; // to avoid warning: unreferenced function argument
11045 \newline
11046 \SpecialChar ~
11047 \SpecialChar ~
11048 \SpecialChar ~
11049 \SpecialChar ~
11050 _asm
11051 \begin_inset LatexCommand \index{\_asm}
11052
11053 \end_inset
11054
11055
11056 \newline
11057 \SpecialChar ~
11058 \SpecialChar ~
11059 \SpecialChar ~
11060 \SpecialChar ~
11061 \SpecialChar ~
11062 \SpecialChar ~
11063 \SpecialChar ~
11064 \SpecialChar ~
11065 ; save used registers here.
11066
11067 \newline
11068 \SpecialChar ~
11069 \SpecialChar ~
11070 \SpecialChar ~
11071 \SpecialChar ~
11072 \SpecialChar ~
11073 \SpecialChar ~
11074 \SpecialChar ~
11075 \SpecialChar ~
11076 ; If we were still using r2,r3 we would have to push them here.
11077
11078 \newline
11079 ; if( head != tail-1 )
11080 \newline
11081 \SpecialChar ~
11082 \SpecialChar ~
11083 \SpecialChar ~
11084 \SpecialChar ~
11085 \SpecialChar ~
11086 \SpecialChar ~
11087 \SpecialChar ~
11088 \SpecialChar ~
11089 mov\SpecialChar ~
11090  a,_tail
11091 \newline
11092 \SpecialChar ~
11093 \SpecialChar ~
11094 \SpecialChar ~
11095 \SpecialChar ~
11096 \SpecialChar ~
11097 \SpecialChar ~
11098 \SpecialChar ~
11099 \SpecialChar ~
11100 dec\SpecialChar ~
11101  a
11102 \newline
11103 \SpecialChar ~
11104 \SpecialChar ~
11105 \SpecialChar ~
11106 \SpecialChar ~
11107 \SpecialChar ~
11108 \SpecialChar ~
11109 \SpecialChar ~
11110 \SpecialChar ~
11111 xrl\SpecialChar ~
11112  a,_head
11113 \newline
11114 \SpecialChar ~
11115 \SpecialChar ~
11116 \SpecialChar ~
11117 \SpecialChar ~
11118 \SpecialChar ~
11119 \SpecialChar ~
11120 \SpecialChar ~
11121 \SpecialChar ~
11122 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
11123 \newline
11124 \SpecialChar ~
11125 \SpecialChar ~
11126 \SpecialChar ~
11127 \SpecialChar ~
11128 \SpecialChar ~
11129 \SpecialChar ~
11130 \SpecialChar ~
11131 \SpecialChar ~
11132 jz\SpecialChar ~
11133 \SpecialChar ~
11134  t_b_end$
11135 \newline
11136 \SpecialChar ~
11137 \SpecialChar ~
11138 \SpecialChar ~
11139 \SpecialChar ~
11140 \SpecialChar ~
11141 \SpecialChar ~
11142 \SpecialChar ~
11143 \SpecialChar ~
11144 ;
11145 \newline
11146 ; buf[ head++ ] = c;
11147 \newline
11148 \SpecialChar ~
11149 \SpecialChar ~
11150 \SpecialChar ~
11151 \SpecialChar ~
11152 \SpecialChar ~
11153 \SpecialChar ~
11154 \SpecialChar ~
11155 \SpecialChar ~
11156 mov\SpecialChar ~
11157  a,dpl \SpecialChar ~
11158 \SpecialChar ~
11159 \SpecialChar ~
11160 \SpecialChar ~
11161 \SpecialChar ~
11162 \SpecialChar ~
11163 \SpecialChar ~
11164 ; dpl holds lower byte of function argument
11165 \newline
11166 \SpecialChar ~
11167 \SpecialChar ~
11168 \SpecialChar ~
11169 \SpecialChar ~
11170 \SpecialChar ~
11171 \SpecialChar ~
11172 \SpecialChar ~
11173 \SpecialChar ~
11174 mov\SpecialChar ~
11175  dpl,_head \SpecialChar ~
11176 \SpecialChar ~
11177 \SpecialChar ~
11178 ; buf is 0x100 byte aligned so head can be used directly
11179 \newline
11180 \SpecialChar ~
11181 \SpecialChar ~
11182 \SpecialChar ~
11183 \SpecialChar ~
11184 \SpecialChar ~
11185 \SpecialChar ~
11186 \SpecialChar ~
11187 \SpecialChar ~
11188 mov\SpecialChar ~
11189  dph,#(_buf>>8)
11190 \newline
11191 \SpecialChar ~
11192 \SpecialChar ~
11193 \SpecialChar ~
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 \SpecialChar ~
11197 \SpecialChar ~
11198 \SpecialChar ~
11199 movx @dptr,a
11200 \newline
11201 \SpecialChar ~
11202 \SpecialChar ~
11203 \SpecialChar ~
11204 \SpecialChar ~
11205 \SpecialChar ~
11206 \SpecialChar ~
11207 \SpecialChar ~
11208 \SpecialChar ~
11209 inc \SpecialChar ~
11210 _head
11211 \newline
11212 \SpecialChar ~
11213 \SpecialChar ~
11214 \SpecialChar ~
11215 \SpecialChar ~
11216 \SpecialChar ~
11217 \SpecialChar ~
11218 \SpecialChar ~
11219 \SpecialChar ~
11220 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
11221 \newline
11222 t_b_end$:
11223 \newline
11224 \SpecialChar ~
11225 \SpecialChar ~
11226 \SpecialChar ~
11227 \SpecialChar ~
11228 \SpecialChar ~
11229 \SpecialChar ~
11230 \SpecialChar ~
11231 \SpecialChar ~
11232 ; restore used registers here
11233 \newline
11234 \SpecialChar ~
11235 \SpecialChar ~
11236 \SpecialChar ~
11237 \SpecialChar ~
11238 _endasm;
11239 \newline
11240 }
11241 \newline
11242 #endif
11243 \layout Standard
11244
11245 The inline assembler code can contain any valid code understood by the assembler
11246 , this includes any assembler directives and comment lines
11247 \begin_inset Foot
11248 collapsed false
11249
11250 \layout Standard
11251
11252 The assembler does not like some characters like ':' or ''' in comments.
11253  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
11254 \end_inset
11255
11256 .
11257  The compiler does not do any validation of the code within the
11258 \family typewriter
11259 _asm
11260 \begin_inset LatexCommand \index{\_asm}
11261
11262 \end_inset
11263
11264  ...
11265  _endasm;
11266 \family default
11267  keyword pair.
11268  Specifically it will not know which registers are used and thus register
11269  pushing/popping
11270 \begin_inset LatexCommand \index{push/pop}
11271
11272 \end_inset
11273
11274  has to be done manually.
11275
11276 \layout Standard
11277
11278 It is recommended that each assembly instruction (including labels) be placed
11279  in a separate line (as the example shows).
11280  When the -
11281 \begin_inset ERT
11282 status Collapsed
11283
11284 \layout Standard
11285
11286 \backslash
11287 /
11288 \end_inset
11289
11290 -
11291 \emph on
11292 peep-asm
11293 \begin_inset LatexCommand \index{-\/-peep-asm}
11294
11295 \end_inset
11296
11297
11298 \emph default
11299  command line option is used, the inline assembler code will be passed through
11300  the peephole optimizer
11301 \begin_inset LatexCommand \index{Peephole optimizer}
11302
11303 \end_inset
11304
11305 .
11306  There are only a few (if any) cases where this option makes sense, it might
11307  cause some unexpected changes in the inline assembler code.
11308  Please go through the peephole optimizer rules defined in file
11309 \emph on
11310 SDCCpeeph.def
11311 \emph default
11312  before using this option.
11313 \layout Subsection
11314
11315 Naked Functions
11316 \begin_inset LatexCommand \label{sub:Naked-Functions}
11317
11318 \end_inset
11319
11320
11321 \begin_inset LatexCommand \index{Naked functions}
11322
11323 \end_inset
11324
11325
11326 \layout Standard
11327
11328 A special keyword may be associated with a function declaring it as
11329 \emph on
11330 _naked
11331 \begin_inset LatexCommand \index{\_naked}
11332
11333 \end_inset
11334
11335 .
11336
11337 \emph default
11338 The
11339 \emph on
11340 _naked
11341 \emph default
11342  function modifier attribute prevents the compiler from generating prologue
11343 \begin_inset LatexCommand \index{function prologue}
11344
11345 \end_inset
11346
11347  and epilogue
11348 \begin_inset LatexCommand \index{function epilogue}
11349
11350 \end_inset
11351
11352  code for that function.
11353  This means that the user is entirely responsible for such things as saving
11354  any registers that may need to be preserved, selecting the proper register
11355  bank, generating the
11356 \emph on
11357 return
11358 \emph default
11359  instruction at the end, etc.
11360  Practically, this means that the contents of the function must be written
11361  in inline assembler.
11362  This is particularly useful for interrupt functions, which can have a large
11363  (and often unnecessary) prologue/epilogue.
11364  For example, compare the code generated by these two functions:
11365 \layout Verse
11366
11367
11368 \family typewriter
11369 volatile
11370 \begin_inset LatexCommand \index{volatile}
11371
11372 \end_inset
11373
11374  data unsigned char counter;
11375 \newline
11376
11377 \newline
11378 void simpleInterrupt(void) interrupt
11379 \begin_inset LatexCommand \index{interrupt}
11380
11381 \end_inset
11382
11383  1
11384 \newline
11385 {
11386 \newline
11387 \SpecialChar ~
11388 \SpecialChar ~
11389 \SpecialChar ~
11390 \SpecialChar ~
11391 counter++;
11392 \newline
11393 }
11394 \newline
11395
11396 \newline
11397 void nakedInterrupt(void) interrupt 2 _naked
11398 \newline
11399 {
11400 \newline
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 \SpecialChar ~
11405 _asm
11406 \begin_inset LatexCommand \index{\_asm}
11407
11408 \end_inset
11409
11410
11411 \newline
11412 \SpecialChar ~
11413 \SpecialChar ~
11414 \SpecialChar ~
11415 \SpecialChar ~
11416 \SpecialChar ~
11417 \SpecialChar ~
11418 inc\SpecialChar ~
11419 \SpecialChar ~
11420 \SpecialChar ~
11421 \SpecialChar ~
11422 \SpecialChar ~
11423 _counter ; does not change flags, no need to save psw
11424 \newline
11425 \SpecialChar ~
11426 \SpecialChar ~
11427 \SpecialChar ~
11428 \SpecialChar ~
11429 \SpecialChar ~
11430 \SpecialChar ~
11431 reti\SpecialChar ~
11432 \SpecialChar ~
11433 \SpecialChar ~
11434 \SpecialChar ~
11435 ; MUST explicitly include ret or reti in _naked function.
11436 \newline
11437 \SpecialChar ~
11438 \SpecialChar ~
11439 \SpecialChar ~
11440 \SpecialChar ~
11441 _endasm
11442 \begin_inset LatexCommand \index{\_endasm}
11443
11444 \end_inset
11445
11446 ;
11447 \newline
11448 }
11449 \layout Standard
11450
11451 For an 8051 target, the generated simpleInterrupt looks like:
11452 \layout Verse
11453
11454
11455 \family typewriter
11456 _simpleInterrupt:
11457 \newline
11458 \SpecialChar ~
11459 \SpecialChar ~
11460 \SpecialChar ~
11461 \SpecialChar ~
11462 push\SpecialChar ~
11463 \SpecialChar ~
11464 \SpecialChar ~
11465 \SpecialChar ~
11466 acc
11467 \newline
11468 \SpecialChar ~
11469 \SpecialChar ~
11470 \SpecialChar ~
11471 \SpecialChar ~
11472 push\SpecialChar ~
11473 \SpecialChar ~
11474 \SpecialChar ~
11475 \SpecialChar ~
11476 b
11477 \newline
11478 \SpecialChar ~
11479 \SpecialChar ~
11480 \SpecialChar ~
11481 \SpecialChar ~
11482 push\SpecialChar ~
11483 \SpecialChar ~
11484 \SpecialChar ~
11485 \SpecialChar ~
11486 dpl
11487 \newline
11488 \SpecialChar ~
11489 \SpecialChar ~
11490 \SpecialChar ~
11491 \SpecialChar ~
11492 push\SpecialChar ~
11493 \SpecialChar ~
11494 \SpecialChar ~
11495 \SpecialChar ~
11496 dph
11497 \newline
11498 \SpecialChar ~
11499 \SpecialChar ~
11500 \SpecialChar ~
11501 \SpecialChar ~
11502 push\SpecialChar ~
11503 \SpecialChar ~
11504 \SpecialChar ~
11505 \SpecialChar ~
11506 psw
11507 \newline
11508 \SpecialChar ~
11509 \SpecialChar ~
11510 \SpecialChar ~
11511 \SpecialChar ~
11512 mov\SpecialChar ~
11513 \SpecialChar ~
11514 \SpecialChar ~
11515 \SpecialChar ~
11516 \SpecialChar ~
11517 psw,#0x00
11518 \newline
11519 \SpecialChar ~
11520 \SpecialChar ~
11521 \SpecialChar ~
11522 \SpecialChar ~
11523 inc\SpecialChar ~
11524 \SpecialChar ~
11525 \SpecialChar ~
11526 \SpecialChar ~
11527 \SpecialChar ~
11528 _counter
11529 \newline
11530 \SpecialChar ~
11531 \SpecialChar ~
11532 \SpecialChar ~
11533 \SpecialChar ~
11534 pop\SpecialChar ~
11535 \SpecialChar ~
11536 \SpecialChar ~
11537 \SpecialChar ~
11538 \SpecialChar ~
11539 psw
11540 \newline
11541 \SpecialChar ~
11542 \SpecialChar ~
11543 \SpecialChar ~
11544 \SpecialChar ~
11545 pop\SpecialChar ~
11546 \SpecialChar ~
11547 \SpecialChar ~
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 dph
11551 \newline
11552 \SpecialChar ~
11553 \SpecialChar ~
11554 \SpecialChar ~
11555 \SpecialChar ~
11556 pop\SpecialChar ~
11557 \SpecialChar ~
11558 \SpecialChar ~
11559 \SpecialChar ~
11560 \SpecialChar ~
11561 dpl
11562 \newline
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 \SpecialChar ~
11566 \SpecialChar ~
11567 pop\SpecialChar ~
11568 \SpecialChar ~
11569 \SpecialChar ~
11570 \SpecialChar ~
11571 \SpecialChar ~
11572 b
11573 \newline
11574 \SpecialChar ~
11575 \SpecialChar ~
11576 \SpecialChar ~
11577 \SpecialChar ~
11578 pop\SpecialChar ~
11579 \SpecialChar ~
11580 \SpecialChar ~
11581 \SpecialChar ~
11582 \SpecialChar ~
11583 acc
11584 \newline
11585 \SpecialChar ~
11586 \SpecialChar ~
11587 \SpecialChar ~
11588 \SpecialChar ~
11589 reti
11590 \layout Standard
11591
11592 whereas nakedInterrupt looks like:
11593 \layout Verse
11594
11595
11596 \family typewriter
11597 _nakedInterrupt:
11598 \newline
11599 \SpecialChar ~
11600 \SpecialChar ~
11601 \SpecialChar ~
11602 \SpecialChar ~
11603 inc\SpecialChar ~
11604 \SpecialChar ~
11605 \SpecialChar ~
11606 \SpecialChar ~
11607 _counter ; does not change flags, no need to save psw
11608 \newline
11609 \SpecialChar ~
11610 \SpecialChar ~
11611 \SpecialChar ~
11612 \SpecialChar ~
11613 reti\SpecialChar ~
11614 \SpecialChar ~
11615 \SpecialChar ~
11616 \SpecialChar ~
11617 \SpecialChar ~
11618 \SpecialChar ~
11619 \SpecialChar ~
11620 \SpecialChar ~
11621 \SpecialChar ~
11622 \SpecialChar ~
11623 \SpecialChar ~
11624 \SpecialChar ~
11625 ; MUST explicitly include ret or reti in _naked function
11626 \layout Standard
11627
11628 The related directive #pragma exclude
11629 \begin_inset LatexCommand \index{\#pragma exclude}
11630
11631 \end_inset
11632
11633  allows a more fine grained control over pushing & popping
11634 \begin_inset LatexCommand \index{push/pop}
11635
11636 \end_inset
11637
11638  the registers.
11639 \layout Standard
11640
11641 While there is nothing preventing you from writing C code inside a
11642 \family typewriter
11643 _naked
11644 \family default
11645  function, there are many ways to shoot yourself in the foot doing this,
11646  and it is recommended that you stick to inline assembler.
11647 \layout Subsection
11648
11649 Use of Labels within Inline Assembler
11650 \layout Standard
11651
11652 SDCC allows the use of in-line assembler with a few restrictions regarding
11653  labels.
11654  In older versions of the compiler all labels defined within inline assembler
11655  code
11656 \emph on
11657 had to be
11658 \emph default
11659  of the form
11660 \emph on
11661 nnnnn$
11662 \emph default
11663  where nnnn is a number less than 100 (which implies a limit of utmost 100
11664  inline assembler labels
11665 \emph on
11666 per function
11667 \emph default
11668 \noun on
11669 )
11670 \noun default
11671 .
11672
11673 \layout Verse
11674
11675
11676 \family typewriter
11677 _asm
11678 \begin_inset LatexCommand \index{\_asm}
11679
11680 \end_inset
11681
11682
11683 \newline
11684 \SpecialChar ~
11685 \SpecialChar ~
11686 \SpecialChar ~
11687 \SpecialChar ~
11688 mov\SpecialChar ~
11689 \SpecialChar ~
11690 \SpecialChar ~
11691 \SpecialChar ~
11692 \SpecialChar ~
11693 b,#10
11694 \newline
11695 00001$:
11696 \newline
11697 \SpecialChar ~
11698 \SpecialChar ~
11699 \SpecialChar ~
11700 \SpecialChar ~
11701 djnz\SpecialChar ~
11702 \SpecialChar ~
11703 \SpecialChar ~
11704 \SpecialChar ~
11705 b,00001$
11706 \newline
11707 _endasm
11708 \begin_inset LatexCommand \index{\_endasm}
11709
11710 \end_inset
11711
11712  ;
11713 \layout Standard
11714
11715 Inline assembler code cannot reference any C-Labels, however it can reference
11716  labels
11717 \begin_inset LatexCommand \index{Labels}
11718
11719 \end_inset
11720
11721  defined by the inline assembler, e.g.:
11722 \layout Verse
11723
11724
11725 \family typewriter
11726 foo() {
11727 \newline
11728 \SpecialChar ~
11729 \SpecialChar ~
11730 \SpecialChar ~
11731 \SpecialChar ~
11732 /* some c code */
11733 \newline
11734 \SpecialChar ~
11735 \SpecialChar ~
11736 \SpecialChar ~
11737 \SpecialChar ~
11738 _asm
11739 \newline
11740 \SpecialChar ~
11741 \SpecialChar ~
11742 \SpecialChar ~
11743 \SpecialChar ~
11744 \SpecialChar ~
11745 \SpecialChar ~
11746 ; some assembler code
11747 \newline
11748 \SpecialChar ~
11749 \SpecialChar ~
11750 \SpecialChar ~
11751 \SpecialChar ~
11752 \SpecialChar ~
11753 \SpecialChar ~
11754 ljmp $0003
11755 \newline
11756 \SpecialChar ~
11757 \SpecialChar ~
11758 \SpecialChar ~
11759 \SpecialChar ~
11760 _endasm;
11761 \newline
11762 \SpecialChar ~
11763 \SpecialChar ~
11764 \SpecialChar ~
11765 \SpecialChar ~
11766 /* some more c code */
11767 \newline
11768 clabel:\SpecialChar ~
11769 \SpecialChar ~
11770 /* inline assembler cannot reference this label */
11771 \newline
11772 \SpecialChar ~
11773 \SpecialChar ~
11774 \SpecialChar ~
11775 \SpecialChar ~
11776 _asm
11777 \newline
11778 \SpecialChar ~
11779 \SpecialChar ~
11780 \SpecialChar ~
11781 \SpecialChar ~
11782 $0003: ;label (can be referenced by inline assembler only)
11783 \newline
11784 \SpecialChar ~
11785 \SpecialChar ~
11786 \SpecialChar ~
11787 \SpecialChar ~
11788 _endasm ;
11789 \newline
11790 \SpecialChar ~
11791 \SpecialChar ~
11792 \SpecialChar ~
11793 \SpecialChar ~
11794 /* some more c code */
11795 \newline
11796 }
11797 \layout Standard
11798
11799 In other words inline assembly code can access labels defined in inline
11800  assembly within the scope of the function.
11801  The same goes the other way, i.e.
11802  labels defines in inline assembly can not be accessed by C statements.
11803 \layout Section
11804
11805 Interfacing with Assembler Code
11806 \begin_inset LatexCommand \index{Assembler routines}
11807
11808 \end_inset
11809
11810
11811 \layout Subsection
11812
11813 Global Registers used for Parameter Passing
11814 \begin_inset LatexCommand \index{Parameter passing}
11815
11816 \end_inset
11817
11818
11819 \layout Standard
11820
11821 The compiler always uses the global registers
11822 \emph on
11823 DPL, DPH
11824 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
11825
11826 \end_inset
11827
11828
11829 \begin_inset LatexCommand \index{DPTR}
11830
11831 \end_inset
11832
11833 , B
11834 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
11835
11836 \end_inset
11837
11838
11839 \emph default
11840 and
11841 \emph on
11842  ACC
11843 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
11844
11845 \end_inset
11846
11847
11848 \emph default
11849  to pass the first parameter to a routine.
11850  The second parameter onwards is either allocated on the stack (for reentrant
11851  routines or if -
11852 \begin_inset ERT
11853 status Collapsed
11854
11855 \layout Standard
11856
11857 \backslash
11858 /
11859 \end_inset
11860
11861 -stack-auto is used) or in data / xdata memory (depending on the memory
11862  model).
11863
11864 \layout Subsection
11865
11866 Assembler Routine (non-reentrant)
11867 \layout Standard
11868
11869 In the following example
11870 \begin_inset LatexCommand \index{reentrant}
11871
11872 \end_inset
11873
11874
11875 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
11876
11877 \end_inset
11878
11879  the function c_func calls an assembler routine asm_func, which takes two
11880  parameters
11881 \begin_inset LatexCommand \index{function parameter}
11882
11883 \end_inset
11884
11885 .
11886 \layout Verse
11887
11888
11889 \family typewriter
11890 extern int asm_func(unsigned char, unsigned char);
11891 \newline
11892
11893 \newline
11894 int c_func (unsigned char i, unsigned char j)
11895 \newline
11896 {
11897 \newline
11898 \SpecialChar ~
11899 \SpecialChar ~
11900 \SpecialChar ~
11901 \SpecialChar ~
11902 return asm_func(i,j);
11903 \newline
11904 }
11905 \newline
11906
11907 \newline
11908 int main()
11909 \newline
11910 {
11911 \newline
11912 \SpecialChar ~
11913 \SpecialChar ~
11914 \SpecialChar ~
11915 \SpecialChar ~
11916 return c_func(10,9);
11917 \newline
11918 }
11919 \layout Standard
11920
11921 The corresponding assembler function is:
11922 \layout Verse
11923
11924
11925 \family typewriter
11926 .globl _asm_func_PARM_2
11927 \newline
11928 \SpecialChar ~
11929 \SpecialChar ~
11930 \SpecialChar ~
11931 \SpecialChar ~
11932 \SpecialChar ~
11933 \SpecialChar ~
11934 \SpecialChar ~
11935 \SpecialChar ~
11936 .globl _asm_func
11937 \newline
11938 \SpecialChar ~
11939 \SpecialChar ~
11940 \SpecialChar ~
11941 \SpecialChar ~
11942 \SpecialChar ~
11943 \SpecialChar ~
11944 \SpecialChar ~
11945 \SpecialChar ~
11946 .area OSEG
11947 \newline
11948 _asm_func_PARM_2:
11949 \newline
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 \SpecialChar ~
11954 \SpecialChar ~
11955 \SpecialChar ~
11956 \SpecialChar ~
11957 \SpecialChar ~
11958 .ds    1
11959 \newline
11960 \SpecialChar ~
11961 \SpecialChar ~
11962 \SpecialChar ~
11963 \SpecialChar ~
11964 \SpecialChar ~
11965 \SpecialChar ~
11966 \SpecialChar ~
11967 \SpecialChar ~
11968 .area CSEG
11969 \newline
11970 _asm_func:
11971 \newline
11972 \SpecialChar ~
11973 \SpecialChar ~
11974 \SpecialChar ~
11975 \SpecialChar ~
11976 \SpecialChar ~
11977 \SpecialChar ~
11978 \SpecialChar ~
11979 \SpecialChar ~
11980 mov\SpecialChar ~
11981 \SpecialChar ~
11982 \SpecialChar ~
11983 \SpecialChar ~
11984 a,dpl
11985 \newline
11986 \SpecialChar ~
11987 \SpecialChar ~
11988 \SpecialChar ~
11989 \SpecialChar ~
11990 \SpecialChar ~
11991 \SpecialChar ~
11992 \SpecialChar ~
11993 \SpecialChar ~
11994 add\SpecialChar ~
11995 \SpecialChar ~
11996 \SpecialChar ~
11997 \SpecialChar ~
11998 a,_asm_func_PARM_2
11999 \newline
12000 \SpecialChar ~
12001 \SpecialChar ~
12002 \SpecialChar ~
12003 \SpecialChar ~
12004 \SpecialChar ~
12005 \SpecialChar ~
12006 \SpecialChar ~
12007 \SpecialChar ~
12008 mov\SpecialChar ~
12009 \SpecialChar ~
12010 \SpecialChar ~
12011 \SpecialChar ~
12012 dpl,a
12013 \newline
12014 \SpecialChar ~
12015 \SpecialChar ~
12016 \SpecialChar ~
12017 \SpecialChar ~
12018 \SpecialChar ~
12019 \SpecialChar ~
12020 \SpecialChar ~
12021 \SpecialChar ~
12022 mov\SpecialChar ~
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 \SpecialChar ~
12026 dph
12027 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12028
12029 \end_inset
12030
12031 ,#0x00
12032 \newline
12033 \SpecialChar ~
12034 \SpecialChar ~
12035 \SpecialChar ~
12036 \SpecialChar ~
12037 \SpecialChar ~
12038 \SpecialChar ~
12039 \SpecialChar ~
12040 \SpecialChar ~
12041 ret
12042 \layout Standard
12043
12044 Note here that the return values
12045 \begin_inset LatexCommand \index{return value}
12046
12047 \end_inset
12048
12049  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
12050  two byte values.
12051  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12052 b' & 'acc' for four byte values.
12053 \layout Standard
12054
12055 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12056  the parameter number starting from 1, and counting from the left.
12057  The first parameter is passed in
12058 \begin_inset Quotes eld
12059 \end_inset
12060
12061 dpl
12062 \begin_inset Quotes erd
12063 \end_inset
12064
12065  for a one byte parameter,
12066 \begin_inset Quotes eld
12067 \end_inset
12068
12069 dptr
12070 \begin_inset Quotes erd
12071 \end_inset
12072
12073  for two bytes,
12074 \begin_inset Quotes eld
12075 \end_inset
12076
12077 b,dptr
12078 \begin_inset Quotes erd
12079 \end_inset
12080
12081  for three bytes and
12082 \begin_inset Quotes eld
12083 \end_inset
12084
12085 acc,b,dptr
12086 \begin_inset Quotes erd
12087 \end_inset
12088
12089  for a four bytes parameter.
12090  The variable name for the second parameter will be _<function_name>_PARM_2.
12091 \newline
12092
12093 \newline
12094 Assemble the assembler routine with the following command:
12095 \newline
12096
12097 \newline
12098
12099 \family sans
12100 \series bold
12101 asx8051 -losg asmfunc.asm
12102 \newline
12103
12104 \newline
12105
12106 \family default
12107 \series default
12108 Then compile and link the assembler routine to the C source file with the
12109  following command:
12110 \newline
12111
12112 \newline
12113
12114 \family sans
12115 \series bold
12116 sdcc cfunc.c asmfunc.rel
12117 \layout Subsection
12118
12119 Assembler Routine (reentrant)
12120 \layout Standard
12121
12122 In this case
12123 \begin_inset LatexCommand \index{reentrant}
12124
12125 \end_inset
12126
12127
12128 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12129
12130 \end_inset
12131
12132  the second parameter
12133 \begin_inset LatexCommand \index{function parameter}
12134
12135 \end_inset
12136
12137  onwards will be passed on the stack, the parameters are pushed from right
12138  to left i.e.
12139  after the call the leftmost parameter will be on the top of the stack.
12140  Here is an example:
12141 \layout Verse
12142
12143
12144 \family typewriter
12145 extern int asm_func(unsigned char, unsigned char);
12146 \newline
12147
12148 \newline
12149 int c_func (unsigned char i, unsigned char j) reentrant
12150 \newline
12151 {
12152 \newline
12153 \SpecialChar ~
12154 \SpecialChar ~
12155 \SpecialChar ~
12156 \SpecialChar ~
12157 return asm_func(i,j);
12158 \newline
12159 }
12160 \newline
12161
12162 \newline
12163 int main()
12164 \newline
12165 {
12166 \newline
12167 \SpecialChar ~
12168 \SpecialChar ~
12169 \SpecialChar ~
12170 \SpecialChar ~
12171 return c_func(10,9);
12172 \newline
12173 }
12174 \layout Standard
12175
12176 The corresponding assembler routine is:
12177 \layout Verse
12178
12179
12180 \family typewriter
12181 .globl _asm_func
12182 \newline
12183 _asm_func:
12184 \newline
12185 \SpecialChar ~
12186 \SpecialChar ~
12187 \SpecialChar ~
12188 \SpecialChar ~
12189 push  _bp
12190 \newline
12191 \SpecialChar ~
12192 \SpecialChar ~
12193 \SpecialChar ~
12194 \SpecialChar ~
12195 mov _bp,sp
12196 \newline
12197 \SpecialChar ~
12198 \SpecialChar ~
12199 \SpecialChar ~
12200 \SpecialChar ~
12201 mov r2,dpl
12202 \newline
12203 \SpecialChar ~
12204 \SpecialChar ~
12205 \SpecialChar ~
12206 \SpecialChar ~
12207 mov a,_bp
12208 \newline
12209 \SpecialChar ~
12210 \SpecialChar ~
12211 \SpecialChar ~
12212 \SpecialChar ~
12213 add a,#0xfd
12214 \newline
12215 \SpecialChar ~
12216 \SpecialChar ~
12217 \SpecialChar ~
12218 \SpecialChar ~
12219 mov r0,a
12220 \newline
12221 \SpecialChar ~
12222 \SpecialChar ~
12223 \SpecialChar ~
12224 \SpecialChar ~
12225 add  a,#0xfc ;?
12226 \newline
12227 \SpecialChar ~
12228 \SpecialChar ~
12229 \SpecialChar ~
12230 \SpecialChar ~
12231 mov  r1,a
12232 \newline
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 \SpecialChar ~
12236 \SpecialChar ~
12237 mov  a,@r0
12238 \newline
12239 \SpecialChar ~
12240 \SpecialChar ~
12241 \SpecialChar ~
12242 \SpecialChar ~
12243 add  a,r2 ;?
12244 \newline
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 \SpecialChar ~
12249 mov  dpl,a
12250 \newline
12251 \SpecialChar ~
12252 \SpecialChar ~
12253 \SpecialChar ~
12254 \SpecialChar ~
12255 mov  dph,#0x00
12256 \newline
12257 \SpecialChar ~
12258 \SpecialChar ~
12259 \SpecialChar ~
12260 \SpecialChar ~
12261 mov  sp,_bp
12262 \newline
12263 \SpecialChar ~
12264 \SpecialChar ~
12265 \SpecialChar ~
12266 \SpecialChar ~
12267 pop  _bp
12268 \newline
12269 \SpecialChar ~
12270 \SpecialChar ~
12271 \SpecialChar ~
12272 \SpecialChar ~
12273 ret
12274 \layout Standard
12275
12276 The compiling and linking procedure remains the same, however note the extra
12277  entry & exit linkage required for the assembler code, _bp is the stack
12278  frame pointer and is used to compute the offset into the stack for parameters
12279  and local variables.
12280 \layout Section
12281
12282 int (16 bit)
12283 \begin_inset LatexCommand \index{int (16 bit)}
12284
12285 \end_inset
12286
12287  and long (32 bit)
12288 \begin_inset LatexCommand \index{long (32 bit)}
12289
12290 \end_inset
12291
12292  Support
12293 \layout Standard
12294
12295 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
12296  multiplication and modulus operations are implemented by support routines.
12297  These support routines are all developed in ANSI-C to facilitate porting
12298  to other MCUs, although some model specific assembler optimizations are
12299  used.
12300  The following files contain the described routines, all of them can be
12301  found in <installdir>/share/sdcc/lib.
12302 \newline
12303
12304 \layout Standard
12305 \align center
12306
12307 \begin_inset  Tabular
12308 <lyxtabular version="3" rows="11" columns="2">
12309 <features>
12310 <column alignment="center" valignment="top" leftline="true" width="0(null)">
12311 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
12312 <row topline="true" bottomline="true">
12313 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12314 \begin_inset Text
12315
12316 \layout Standard
12317
12318
12319 \series bold
12320 Function
12321 \end_inset
12322 </cell>
12323 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12324 \begin_inset Text
12325
12326 \layout Standard
12327
12328
12329 \series bold
12330 Description
12331 \end_inset
12332 </cell>
12333 </row>
12334 <row topline="true">
12335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12336 \begin_inset Text
12337
12338 \layout Standard
12339
12340 _mulint.c
12341 \end_inset
12342 </cell>
12343 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12344 \begin_inset Text
12345
12346 \layout Standard
12347
12348 16 bit multiplication
12349 \end_inset
12350 </cell>
12351 </row>
12352 <row topline="true">
12353 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12354 \begin_inset Text
12355
12356 \layout Standard
12357
12358 _divsint.c
12359 \end_inset
12360 </cell>
12361 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12362 \begin_inset Text
12363
12364 \layout Standard
12365
12366  signed 16 bit division (calls _divuint)
12367 \end_inset
12368 </cell>
12369 </row>
12370 <row topline="true">
12371 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12372 \begin_inset Text
12373
12374 \layout Standard
12375
12376 _divuint.c
12377 \end_inset
12378 </cell>
12379 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12380 \begin_inset Text
12381
12382 \layout Standard
12383
12384  unsigned 16 bit division
12385 \end_inset
12386 </cell>
12387 </row>
12388 <row topline="true">
12389 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12390 \begin_inset Text
12391
12392 \layout Standard
12393
12394 _modsint.c
12395 \end_inset
12396 </cell>
12397 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12398 \begin_inset Text
12399
12400 \layout Standard
12401
12402 signed 16 bit modulus (calls _moduint)
12403 \end_inset
12404 </cell>
12405 </row>
12406 <row topline="true">
12407 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12408 \begin_inset Text
12409
12410 \layout Standard
12411
12412 _moduint.c
12413 \end_inset
12414 </cell>
12415 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12416 \begin_inset Text
12417
12418 \layout Standard
12419
12420 unsigned 16 bit modulus
12421 \end_inset
12422 </cell>
12423 </row>
12424 <row topline="true">
12425 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12426 \begin_inset Text
12427
12428 \layout Standard
12429
12430 _mullong.c
12431 \end_inset
12432 </cell>
12433 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12434 \begin_inset Text
12435
12436 \layout Standard
12437
12438 32 bit multiplication
12439 \end_inset
12440 </cell>
12441 </row>
12442 <row topline="true">
12443 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12444 \begin_inset Text
12445
12446 \layout Standard
12447
12448 _divslong.c
12449 \end_inset
12450 </cell>
12451 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12452 \begin_inset Text
12453
12454 \layout Standard
12455
12456  signed 32 division (calls _divulong)
12457 \end_inset
12458 </cell>
12459 </row>
12460 <row topline="true">
12461 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12462 \begin_inset Text
12463
12464 \layout Standard
12465
12466 _divulong.c
12467 \end_inset
12468 </cell>
12469 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12470 \begin_inset Text
12471
12472 \layout Standard
12473
12474 unsigned 32 division
12475 \end_inset
12476 </cell>
12477 </row>
12478 <row topline="true">
12479 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12480 \begin_inset Text
12481
12482 \layout Standard
12483
12484 _modslong.c
12485 \end_inset
12486 </cell>
12487 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12488 \begin_inset Text
12489
12490 \layout Standard
12491
12492  signed 32 bit modulus (calls _modulong)
12493 \end_inset
12494 </cell>
12495 </row>
12496 <row topline="true" bottomline="true">
12497 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12498 \begin_inset Text
12499
12500 \layout Standard
12501
12502 _modulong.c
12503 \end_inset
12504 </cell>
12505 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12506 \begin_inset Text
12507
12508 \layout Standard
12509
12510 unsigned 32 bit modulus
12511 \end_inset
12512 </cell>
12513 </row>
12514 </lyxtabular>
12515
12516 \end_inset
12517
12518
12519 \newline
12520
12521 \layout Standard
12522
12523 Since they are compiled as
12524 \emph on
12525 non-reentrant
12526 \emph default
12527
12528 \begin_inset LatexCommand \index{reentrant}
12529
12530 \end_inset
12531
12532 , interrupt
12533 \begin_inset LatexCommand \index{interrupt}
12534
12535 \end_inset
12536
12537  service routines should not do any of the above operations.
12538  If this is unavoidable then the above routines will need to be compiled
12539  with the
12540 \emph on
12541 -
12542 \begin_inset ERT
12543 status Collapsed
12544
12545 \layout Standard
12546
12547 \backslash
12548 /
12549 \end_inset
12550
12551 -stack-auto
12552 \begin_inset LatexCommand \index{-\/-stack-auto}
12553
12554 \end_inset
12555
12556
12557 \emph default
12558  option, after which the source program will have to be compiled with
12559 \emph on
12560 -
12561 \begin_inset ERT
12562 status Collapsed
12563
12564 \layout Standard
12565
12566 \backslash
12567 /
12568 \end_inset
12569
12570 -int-long-reent
12571 \begin_inset LatexCommand \index{-\/-int-long-reent}
12572
12573 \end_inset
12574
12575
12576 \emph default
12577  option.
12578  Notice that you don't have to call these routines directly.
12579  The compiler will use them automatically every time an integer operation
12580  is required.
12581 \layout Section
12582
12583 Floating Point Support
12584 \begin_inset LatexCommand \index{Floating point support}
12585
12586 \end_inset
12587
12588
12589 \layout Standard
12590
12591 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
12592  floating point support routines are derived from gcc's floatlib.c and consist
12593  of the following routines:
12594 \newline
12595
12596 \layout Standard
12597 \align center
12598
12599 \size footnotesize
12600
12601 \begin_inset  Tabular
12602 <lyxtabular version="3" rows="17" columns="2">
12603 <features>
12604 <column alignment="center" valignment="top" leftline="true" width="0(null)">
12605 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
12606 <row topline="true" bottomline="true">
12607 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12608 \begin_inset Text
12609
12610 \layout Standard
12611
12612
12613 \family roman
12614 \series medium
12615 \shape up
12616 \size normal
12617 \emph off
12618 \bar no
12619 \noun off
12620 \color none
12621 Function
12622 \end_inset
12623 </cell>
12624 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12625 \begin_inset Text
12626
12627 \layout Standard
12628
12629 Description
12630 \end_inset
12631 </cell>
12632 </row>
12633 <row topline="true">
12634 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12635 \begin_inset Text
12636
12637 \layout Standard
12638
12639
12640 \family roman
12641 \series medium
12642 \shape up
12643 \size normal
12644 \emph off
12645 \bar no
12646 \noun off
12647 \color none
12648 _fsadd.c
12649 \end_inset
12650 </cell>
12651 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12652 \begin_inset Text
12653
12654 \layout Standard
12655
12656
12657 \family roman
12658 \series medium
12659 \shape up
12660 \size normal
12661 \emph off
12662 \bar no
12663 \noun off
12664 \color none
12665 add floating point numbers
12666 \end_inset
12667 </cell>
12668 </row>
12669 <row topline="true">
12670 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12671 \begin_inset Text
12672
12673 \layout Standard
12674
12675
12676 \family roman
12677 \series medium
12678 \shape up
12679 \size normal
12680 \emph off
12681 \bar no
12682 \noun off
12683 \color none
12684 _fssub.c
12685 \end_inset
12686 </cell>
12687 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12688 \begin_inset Text
12689
12690 \layout Standard
12691
12692
12693 \family roman
12694 \series medium
12695 \shape up
12696 \size normal
12697 \emph off
12698 \bar no
12699 \noun off
12700 \color none
12701 subtract floating point numbers
12702 \end_inset
12703 </cell>
12704 </row>
12705 <row topline="true">
12706 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12707 \begin_inset Text
12708
12709 \layout Standard
12710
12711
12712 \family roman
12713 \series medium
12714 \shape up
12715 \size normal
12716 \emph off
12717 \bar no
12718 \noun off
12719 \color none
12720 _fsdiv.c
12721 \end_inset
12722 </cell>
12723 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12724 \begin_inset Text
12725
12726 \layout Standard
12727
12728
12729 \family roman
12730 \series medium
12731 \shape up
12732 \size normal
12733 \emph off
12734 \bar no
12735 \noun off
12736 \color none
12737 divide floating point numbers
12738 \end_inset
12739 </cell>
12740 </row>
12741 <row topline="true">
12742 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12743 \begin_inset Text
12744
12745 \layout Standard
12746
12747
12748 \family roman
12749 \series medium
12750 \shape up
12751 \size normal
12752 \emph off
12753 \bar no
12754 \noun off
12755 \color none
12756 _fsmul.c
12757 \end_inset
12758 </cell>
12759 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12760 \begin_inset Text
12761
12762 \layout Standard
12763
12764
12765 \family roman
12766 \series medium
12767 \shape up
12768 \size normal
12769 \emph off
12770 \bar no
12771 \noun off
12772 \color none
12773 multiply floating point numbers
12774 \end_inset
12775 </cell>
12776 </row>
12777 <row topline="true">
12778 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12779 \begin_inset Text
12780
12781 \layout Standard
12782
12783
12784 \family roman
12785 \series medium
12786 \shape up
12787 \size normal
12788 \emph off
12789 \bar no
12790 \noun off
12791 \color none
12792 _fs2uchar.c
12793 \end_inset
12794 </cell>
12795 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12796 \begin_inset Text
12797
12798 \layout Standard
12799
12800
12801 \family roman
12802 \series medium
12803 \shape up
12804 \size normal
12805 \emph off
12806 \bar no
12807 \noun off
12808 \color none
12809 convert floating point to unsigned char
12810 \end_inset
12811 </cell>
12812 </row>
12813 <row topline="true">
12814 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12815 \begin_inset Text
12816
12817 \layout Standard
12818
12819
12820 \family roman
12821 \series medium
12822 \shape up
12823 \size normal
12824 \emph off
12825 \bar no
12826 \noun off
12827 \color none
12828 _fs2char.c
12829 \end_inset
12830 </cell>
12831 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12832 \begin_inset Text
12833
12834 \layout Standard
12835
12836
12837 \family roman
12838 \series medium
12839 \shape up
12840 \size normal
12841 \emph off
12842 \bar no
12843 \noun off
12844 \color none
12845 convert floating point to signed char
12846 \end_inset
12847 </cell>
12848 </row>
12849 <row topline="true">
12850 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12851 \begin_inset Text
12852
12853 \layout Standard
12854
12855
12856 \family roman
12857 \series medium
12858 \shape up
12859 \size normal
12860 \emph off
12861 \bar no
12862 \noun off
12863 \color none
12864 _fs2uint.c
12865 \end_inset
12866 </cell>
12867 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12868 \begin_inset Text
12869
12870 \layout Standard
12871
12872
12873 \family roman
12874 \series medium
12875 \shape up
12876 \size normal
12877 \emph off
12878 \bar no
12879 \noun off
12880 \color none
12881 convert floating point to unsigned int
12882 \end_inset
12883 </cell>
12884 </row>
12885 <row topline="true">
12886 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12887 \begin_inset Text
12888
12889 \layout Standard
12890
12891
12892 \family roman
12893 \series medium
12894 \shape up
12895 \size normal
12896 \emph off
12897 \bar no
12898 \noun off
12899 \color none
12900 _fs2int.c
12901 \end_inset
12902 </cell>
12903 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12904 \begin_inset Text
12905
12906 \layout Standard
12907
12908
12909 \family roman
12910 \series medium
12911 \shape up
12912 \size normal
12913 \emph off
12914 \bar no
12915 \noun off
12916 \color none
12917 convert floating point to signed int
12918 \end_inset
12919 </cell>
12920 </row>
12921 <row topline="true">
12922 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12923 \begin_inset Text
12924
12925 \layout Standard
12926
12927
12928 \family roman
12929 \series medium
12930 \shape up
12931 \size normal
12932 \emph off
12933 \bar no
12934 \noun off
12935 \color none
12936 _fs2ulong.
12937 \family default
12938 \series default
12939 \shape default
12940 \size default
12941 \emph default
12942 \bar default
12943 \noun default
12944 \color default
12945 c
12946 \end_inset
12947 </cell>
12948 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12949 \begin_inset Text
12950
12951 \layout Standard
12952
12953
12954 \family roman
12955 \series medium
12956 \shape up
12957 \size normal
12958 \emph off
12959 \bar no
12960 \noun off
12961 \color none
12962 convert floating point to unsigned long
12963 \end_inset
12964 </cell>
12965 </row>
12966 <row topline="true">
12967 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12968 \begin_inset Text
12969
12970 \layout Standard
12971
12972
12973 \family roman
12974 \series medium
12975 \shape up
12976 \size normal
12977 \emph off
12978 \bar no
12979 \noun off
12980 \color none
12981 _fs2long.c
12982 \end_inset
12983 </cell>
12984 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12985 \begin_inset Text
12986
12987 \layout Standard
12988
12989
12990 \family roman
12991 \series medium
12992 \shape up
12993 \size normal
12994 \emph off
12995 \bar no
12996 \noun off
12997 \color none
12998 convert floating point to signed long
12999 \end_inset
13000 </cell>
13001 </row>
13002 <row topline="true">
13003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13004 \begin_inset Text
13005
13006 \layout Standard
13007
13008
13009 \family roman
13010 \series medium
13011 \shape up
13012 \size normal
13013 \emph off
13014 \bar no
13015 \noun off
13016 \color none
13017 _uchar2fs.c
13018 \end_inset
13019 </cell>
13020 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13021 \begin_inset Text
13022
13023 \layout Standard
13024
13025
13026 \family roman
13027 \series medium
13028 \shape up
13029 \size normal
13030 \emph off
13031 \bar no
13032 \noun off
13033 \color none
13034 convert unsigned char to floating point
13035 \end_inset
13036 </cell>
13037 </row>
13038 <row topline="true">
13039 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13040 \begin_inset Text
13041
13042 \layout Standard
13043
13044
13045 \family roman
13046 \series medium
13047 \shape up
13048 \size normal
13049 \emph off
13050 \bar no
13051 \noun off
13052 \color none
13053 _char2fs.c
13054 \end_inset
13055 </cell>
13056 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13057 \begin_inset Text
13058
13059 \layout Standard
13060
13061
13062 \family roman
13063 \series medium
13064 \shape up
13065 \size normal
13066 \emph off
13067 \bar no
13068 \noun off
13069 \color none
13070 convert char to floating point number
13071 \end_inset
13072 </cell>
13073 </row>
13074 <row topline="true">
13075 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13076 \begin_inset Text
13077
13078 \layout Standard
13079
13080
13081 \family roman
13082 \series medium
13083 \shape up
13084 \size normal
13085 \emph off
13086 \bar no
13087 \noun off
13088 \color none
13089 _uint2fs.c
13090 \end_inset
13091 </cell>
13092 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13093 \begin_inset Text
13094
13095 \layout Standard
13096
13097
13098 \family roman
13099 \series medium
13100 \shape up
13101 \size normal
13102 \emph off
13103 \bar no
13104 \noun off
13105 \color none
13106 convert unsigned int to floating point
13107 \end_inset
13108 </cell>
13109 </row>
13110 <row topline="true">
13111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13112 \begin_inset Text
13113
13114 \layout Standard
13115
13116
13117 \family roman
13118 \series medium
13119 \shape up
13120 \size normal
13121 \emph off
13122 \bar no
13123 \noun off
13124 \color none
13125 _int2fs.c
13126 \end_inset
13127 </cell>
13128 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13129 \begin_inset Text
13130
13131 \layout Standard
13132
13133
13134 \family roman
13135 \series medium
13136 \shape up
13137 \size normal
13138 \emph off
13139 \bar no
13140 \noun off
13141 \color none
13142 convert int to floating point numbers
13143 \end_inset
13144 </cell>
13145 </row>
13146 <row topline="true">
13147 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13148 \begin_inset Text
13149
13150 \layout Standard
13151
13152
13153 \family roman
13154 \series medium
13155 \shape up
13156 \size normal
13157 \emph off
13158 \bar no
13159 \noun off
13160 \color none
13161 _ulong2fs.c
13162 \end_inset
13163 </cell>
13164 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13165 \begin_inset Text
13166
13167 \layout Standard
13168
13169
13170 \family roman
13171 \series medium
13172 \shape up
13173 \size normal
13174 \emph off
13175 \bar no
13176 \noun off
13177 \color none
13178 convert unsigned long to floating point number
13179 \end_inset
13180 </cell>
13181 </row>
13182 <row topline="true" bottomline="true">
13183 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13184 \begin_inset Text
13185
13186 \layout Standard
13187
13188
13189 \family roman
13190 \series medium
13191 \shape up
13192 \size normal
13193 \emph off
13194 \bar no
13195 \noun off
13196 \color none
13197 _long2fs.c
13198 \end_inset
13199 </cell>
13200 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13201 \begin_inset Text
13202
13203 \layout Standard
13204
13205
13206 \family roman
13207 \series medium
13208 \shape up
13209 \size normal
13210 \emph off
13211 \bar no
13212 \noun off
13213 \color none
13214 convert long to floating point number
13215 \end_inset
13216 </cell>
13217 </row>
13218 </lyxtabular>
13219
13220 \end_inset
13221
13222
13223 \newline
13224
13225 \layout Standard
13226
13227 These support routines are developed in ANSI-C so there is room for space
13228  and speed improvement.
13229  Note if all these routines are used simultaneously the data space might
13230  overflow.
13231  For serious floating point usage it is recommended that the large model
13232  be used.
13233  Also notice that you don't have to call this routines directly.
13234  The compiler will use them automatically every time a floating point operation
13235  is required.
13236 \layout Section
13237
13238 Library Routines
13239 \begin_inset LatexCommand \index{Libraries}
13240
13241 \end_inset
13242
13243
13244 \layout Standard
13245
13246
13247 \emph on
13248 <pending: this is messy and incomplete - a little more information is in
13249  sdcc/doc/libdoc.txt
13250 \emph default
13251  >
13252 \layout Subsection
13253
13254 Compiler support routines (_gptrget, _mulint etc.)
13255 \layout Subsection
13256
13257 Stdclib functions (puts, printf, strcat etc.)
13258 \layout Subsubsection
13259
13260 <stdio.h>
13261 \layout Standard
13262
13263
13264 \begin_inset LatexCommand \index{<stdio.h>}
13265
13266 \end_inset
13267
13268 As usual on embedded systems you have to provide your own
13269 \family typewriter
13270 getchar()
13271 \begin_inset LatexCommand \index{getchar()}
13272
13273 \end_inset
13274
13275
13276 \family default
13277 and
13278 \family typewriter
13279 putchar()
13280 \begin_inset LatexCommand \index{putchar()}
13281
13282 \end_inset
13283
13284
13285 \family default
13286  routines.
13287  SDCC does not know whether the system connects to a serial line with or
13288  without handshake, LCD, keyboard or other device.
13289  You'll find examples for serial routines f.e.
13290  in sdcc/device/lib.
13291 \layout Standard
13292
13293 If you're short on memory you might want to use
13294 \family typewriter
13295 printf_small()
13296 \family default
13297
13298 \emph on
13299 instead
13300 \emph default
13301  of
13302 \family typewriter
13303  printf()
13304 \begin_inset LatexCommand \index{printf()}
13305
13306 \end_inset
13307
13308 .
13309
13310 \family default
13311  For the mcs51 there is an assembly version
13312 \family typewriter
13313 printf_fast()
13314 \family default
13315  which should fit the requirements of many embedded systems (by unsetting
13316  #defines it can be customized to
13317 \emph on
13318 not
13319 \emph default
13320  support long variables and field widths).
13321 \layout Subsection
13322
13323 Math functions (sin, pow, sqrt etc.)
13324 \layout Subsection
13325
13326 Other libraries
13327 \layout Standard
13328
13329 Libraries
13330 \begin_inset LatexCommand \index{Libraries}
13331
13332 \end_inset
13333
13334  included in SDCC should have a license at least as liberal as the GNU Lesser
13335  General Public License
13336 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
13337
13338 \end_inset
13339
13340
13341 \emph on
13342 LGPL
13343 \emph default
13344 .
13345 \layout Comment
13346
13347 license statements for the libraries are missing.
13348  sdcc/device/lib/ser_ir.c
13349 \layout Comment
13350
13351 or _decdptr f.e.
13352  come with a GPL (as opposed to LGPL) License - this will not be liberal
13353  enough for many embedded programmers.
13354 \layout Standard
13355
13356 If you have ported some library or want to share experience about some code
13357  which f.e.
13358  falls into any of these categories Busses (I
13359 \begin_inset Formula $^{\textrm{2}}$
13360 \end_inset
13361
13362 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
13363  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
13364  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
13365 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
13366
13367 \end_inset
13368
13369 \SpecialChar ~
13370 would certainly like to hear about it.
13371  Programmers coding for embedded systems are not especially famous for being
13372  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
13373 e these references are very valuable.
13374  Let's help to create a climate where information is shared.
13375 \layout Section
13376
13377 Memory Models
13378 \layout Subsection
13379
13380 MCS51 Memory Models
13381 \begin_inset LatexCommand \index{Memory model}
13382
13383 \end_inset
13384
13385
13386 \begin_inset LatexCommand \index{MCS51 memory model}
13387
13388 \end_inset
13389
13390
13391 \layout Subsubsection
13392
13393 Small and Large
13394 \layout Standard
13395
13396 SDCC allows two memory models for MCS51 code,
13397 \shape slanted
13398 small
13399 \shape default
13400  and
13401 \shape slanted
13402 large
13403 \shape default
13404 .
13405  Modules compiled with different memory models should
13406 \emph on
13407 never
13408 \emph default
13409  be combined together or the results would be unpredictable.
13410  The library routines supplied with the compiler are compiled as both small
13411  and large.
13412  The compiled library modules are contained in separate directories as small
13413  and large so that you can link to either set.
13414
13415 \layout Standard
13416
13417 When the large model is used all variables declared without a storage class
13418  will be allocated into the external ram, this includes all parameters and
13419  local variables (for non-reentrant
13420 \begin_inset LatexCommand \index{reentrant}
13421
13422 \end_inset
13423
13424  functions).
13425  When the small model is used variables without storage class are allocated
13426  in the internal ram.
13427 \layout Standard
13428
13429 Judicious usage of the processor specific storage classes
13430 \begin_inset LatexCommand \index{Storage class}
13431
13432 \end_inset
13433
13434  and the 'reentrant' function type will yield much more efficient code,
13435  than using the large model.
13436  Several optimizations are disabled when the program is compiled using the
13437  large model, it is therefore recommended that the small model be used unless
13438  absolutely required.
13439 \layout Subsubsection
13440
13441 External Stack
13442 \begin_inset LatexCommand \label{sub:External-Stack}
13443
13444 \end_inset
13445
13446
13447 \begin_inset LatexCommand \index{stack}
13448
13449 \end_inset
13450
13451
13452 \begin_inset LatexCommand \index{External stack (mcs51)}
13453
13454 \end_inset
13455
13456
13457 \layout Standard
13458
13459
13460 \series bold
13461 Attention
13462 \series default
13463 : this option wasn't maintained for a long time and is quite buggy.
13464  Small programs might work.
13465  You've been warned!
13466 \layout Standard
13467
13468 The external stack (-
13469 \begin_inset ERT
13470 status Collapsed
13471
13472 \layout Standard
13473
13474 \backslash
13475 /
13476 \end_inset
13477
13478 -xstack option
13479 \begin_inset LatexCommand \index{-\/-xstack}
13480
13481 \end_inset
13482
13483 ) is located in pdata
13484 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
13485
13486 \end_inset
13487
13488  memory (usually at the start of the external ram segment) and is 256 bytes
13489  in size.
13490  When -
13491 \begin_inset ERT
13492 status Collapsed
13493
13494 \layout Standard
13495
13496 \backslash
13497 /
13498 \end_inset
13499
13500 -xstack option is used to compile the program, the parameters and local
13501  variables
13502 \begin_inset LatexCommand \index{local variables}
13503
13504 \end_inset
13505
13506  of all reentrant functions are allocated in this area.
13507  This option is provided for programs with large stack space requirements.
13508  When used with the -
13509 \begin_inset ERT
13510 status Collapsed
13511
13512 \layout Standard
13513
13514 \backslash
13515 /
13516 \end_inset
13517
13518 -stack-auto
13519 \begin_inset LatexCommand \index{-\/-stack-auto}
13520
13521 \end_inset
13522
13523  option, all parameters and local variables are allocated on the external
13524  stack (note: support libraries will need to be recompiled with the same
13525  options).
13526 \layout Standard
13527
13528 The compiler outputs the higher order address byte of the external ram segment
13529  into port P2
13530 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
13531
13532 \end_inset
13533
13534  (see also section
13535 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13536
13537 \end_inset
13538
13539 ), therefore when using the External Stack option, this port
13540 \emph on
13541 may not
13542 \emph default
13543  be used by the application program.
13544 \layout Subsection
13545
13546 DS390 Memory Model
13547 \begin_inset LatexCommand \index{Memory model}
13548
13549 \end_inset
13550
13551
13552 \begin_inset LatexCommand \index{DS390 memory model}
13553
13554 \end_inset
13555
13556
13557 \layout Standard
13558
13559 The only model supported is Flat 24
13560 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
13561
13562 \end_inset
13563
13564 .
13565  This generates code for the 24 bit contiguous addressing mode of the Dallas
13566  DS80C390 part.
13567  In this mode, up to four meg of external RAM or code space can be directly
13568  addressed.
13569  See the data sheets at www.dalsemi.com for further information on this part.
13570 \newline
13571
13572 \newline
13573 Note that the compiler does not generate any code to place the processor
13574  into 24 bitmode (although
13575 \emph on
13576 tinibios
13577 \emph default
13578  in the ds390 libraries will do that for you).
13579  If you don't use
13580 \emph on
13581 tinibios
13582 \emph default
13583
13584 \begin_inset LatexCommand \index{Tinibios (DS390)}
13585
13586 \end_inset
13587
13588 , the boot loader or similar code must ensure that the processor is in 24
13589  bit contiguous addressing mode before calling the SDCC startup code.
13590 \newline
13591
13592 \newline
13593 Like the
13594 \emph on
13595 -
13596 \begin_inset ERT
13597 status Collapsed
13598
13599 \layout Standard
13600
13601 \backslash
13602 /
13603 \end_inset
13604
13605 -model-large
13606 \emph default
13607  option, variables will by default be placed into the XDATA segment.
13608
13609 \newline
13610
13611 \newline
13612 Segments may be placed anywhere in the 4 meg address space using the usual
13613  -
13614 \begin_inset ERT
13615 status Collapsed
13616
13617 \layout Standard
13618
13619 \backslash
13620 /
13621 \end_inset
13622
13623 -*-loc options.
13624  Note that if any segments are located above 64K, the -r flag must be passed
13625  to the linker to generate the proper segment relocations, and the Intel
13626  HEX output format must be used.
13627  The -r flag can be passed to the linker by using the option
13628 \emph on
13629 -Wl-r
13630 \emph default
13631  on the SDCC command line.
13632  However, currently the linker can not handle code segments > 64k.
13633 \layout Section
13634
13635 Pragmas
13636 \begin_inset LatexCommand \index{Pragmas}
13637
13638 \end_inset
13639
13640
13641 \layout Standard
13642
13643 SDCC supports the following #pragma directives:
13644 \layout Itemize
13645
13646 save
13647 \begin_inset LatexCommand \index{\#pragma save}
13648
13649 \end_inset
13650
13651  - this will save all current options to the save/restore stack.
13652  See restore.
13653 \layout Itemize
13654
13655 restore
13656 \begin_inset LatexCommand \index{\#pragma restore}
13657
13658 \end_inset
13659
13660  - will restore saved options from the last save.
13661  saves & restores can be nested.
13662  SDCC uses a save/restore stack: save pushes current options to the stack,
13663  restore pulls current options from the stack.
13664  See save.
13665 \layout Itemize
13666
13667 nogcse
13668 \begin_inset LatexCommand \index{\#pragma nogcse}
13669
13670 \end_inset
13671
13672  - will stop global common subexpression elimination.
13673 \layout Itemize
13674
13675 noinduction
13676 \begin_inset LatexCommand \index{\#pragma noinduction}
13677
13678 \end_inset
13679
13680  - will stop loop induction optimizations.
13681 \layout Itemize
13682
13683 nojtbound
13684 \begin_inset LatexCommand \index{\#pragma nojtbound}
13685
13686 \end_inset
13687
13688  - will not generate code for boundary value checking, when switch statements
13689  are turned into jump-tables (dangerous).
13690  For more details see section
13691 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
13692
13693 \end_inset
13694
13695 .
13696 \layout Itemize
13697
13698 nooverlay
13699 \begin_inset LatexCommand \index{\#pragma nooverlay}
13700
13701 \end_inset
13702
13703  - the compiler will not overlay the parameters and local variables of a
13704  function.
13705 \layout Itemize
13706
13707 less_pedantic
13708 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
13709
13710 \end_inset
13711
13712  - the compiler will not warn you anymore for obvious mistakes, you'r on
13713  your own now ;-(
13714 \layout Itemize
13715
13716 noloopreverse
13717 \begin_inset LatexCommand \index{\#pragma noloopreverse}
13718
13719 \end_inset
13720
13721  - Will not do loop reversal optimization
13722 \layout Itemize
13723
13724 exclude
13725 \begin_inset LatexCommand \index{\#pragma exclude}
13726
13727 \end_inset
13728
13729  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables generation of
13730  pair of push/pop
13731 \begin_inset LatexCommand \index{push/pop}
13732
13733 \end_inset
13734
13735  instruction in ISR function (using interrupt
13736 \begin_inset LatexCommand \index{interrupt}
13737
13738 \end_inset
13739
13740  keyword).
13741  The directive should be placed immediately before the ISR function definition
13742  and it affects ALL ISR functions following it.
13743  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
13744 exclude\SpecialChar ~
13745 none
13746 \begin_inset LatexCommand \index{\#pragma exclude}
13747
13748 \end_inset
13749
13750 .
13751 \layout Itemize
13752
13753 noiv
13754 \begin_inset LatexCommand \index{\#pragma noiv}
13755
13756 \end_inset
13757
13758  - Do not generate interrupt
13759 \begin_inset LatexCommand \index{interrupt}
13760
13761 \end_inset
13762
13763  vector table entries for all ISR functions defined after the pragma.
13764  This is useful in cases where the interrupt vector table must be defined
13765  manually, or when there is a secondary, manually defined interrupt vector
13766  table (e.g.
13767  for the autovector feature of the Cypress EZ-USB FX2).
13768  More elegantly this can be achieved by obmitting the optional interrupt
13769  number after the interrupt keyword, see section
13770 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
13771
13772 \end_inset
13773
13774 \SpecialChar ~
13775 about interrupts.
13776 \layout Itemize
13777
13778 callee_saves
13779 \begin_inset LatexCommand \index{\#pragma callee\_saves}
13780
13781 \end_inset
13782
13783
13784 \begin_inset LatexCommand \index{function prologue}
13785
13786 \end_inset
13787
13788  function1[,function2[,function3...]] - The compiler by default uses a caller
13789  saves convention for register saving across function calls, however this
13790  can cause unnecessary register pushing & popping
13791 \begin_inset LatexCommand \index{push/pop}
13792
13793 \end_inset
13794
13795  when calling small functions from larger functions.
13796  This option can be used to switch off the register saving convention for
13797  the function names specified.
13798  The compiler will not save registers when calling these functions, extra
13799  code need to be manually inserted at the entry & exit for these functions
13800  to save & restore the registers used by these functions, this can SUBSTANTIALLY
13801  reduce code & improve run time performance of the generated code.
13802  In the future the compiler (with inter procedural analysis) may be able
13803  to determine the appropriate scheme to use for each function call.
13804  If -
13805 \begin_inset ERT
13806 status Collapsed
13807
13808 \layout Standard
13809
13810 \backslash
13811 /
13812 \end_inset
13813
13814 -callee-saves command line option is used, the function names specified
13815  in #pragma\SpecialChar ~
13816 callee_saves
13817 \begin_inset LatexCommand \index{\#pragma callee\_saves}
13818
13819 \end_inset
13820
13821  is appended to the list of functions specified in the command line.
13822 \layout Standard
13823
13824 SDCPP supports the following #pragma directives:
13825 \layout Itemize
13826
13827 preproc_asm
13828 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
13829
13830 \end_inset
13831
13832  (+ | -) - switch _asm _endasm block preprocessing on / off.
13833  Default is on.
13834 \layout Standard
13835
13836 The pragma's are intended to be used to turn-on or off certain optimizations
13837  which might cause the compiler to generate extra stack / data space to
13838  store compiler generated temporary variables.
13839  This usually happens in large functions.
13840  Pragma directives should be used as shown in the following example, they
13841  are used to control options & optimizations for a given function; pragmas
13842  should be placed before and/or after a function, placing pragma's inside
13843  a function body could have unpredictable results.
13844 \layout Verse
13845
13846
13847 \family typewriter
13848 #pragma save
13849 \begin_inset LatexCommand \index{\#pragma save}
13850
13851 \end_inset
13852
13853  \SpecialChar ~
13854 \SpecialChar ~
13855 \SpecialChar ~
13856 \SpecialChar ~
13857 \SpecialChar ~
13858 \SpecialChar ~
13859 \SpecialChar ~
13860 /* save the current settings */
13861 \newline
13862 #pragma nogcse
13863 \begin_inset LatexCommand \index{\#pragma nogcse}
13864
13865 \end_inset
13866
13867  \SpecialChar ~
13868 \SpecialChar ~
13869 \SpecialChar ~
13870 \SpecialChar ~
13871 \SpecialChar ~
13872 /* turnoff global subexpression elimination */
13873 \newline
13874 #pragma noinduction
13875 \begin_inset LatexCommand \index{\#pragma noinduction}
13876
13877 \end_inset
13878
13879  /* turn off induction optimizations */
13880 \newline
13881 int foo ()
13882 \newline
13883 {
13884 \newline
13885 \SpecialChar ~
13886  \SpecialChar ~
13887  ...
13888
13889 \newline
13890 \SpecialChar ~
13891  \SpecialChar ~
13892  /* large code */
13893 \newline
13894 \SpecialChar ~
13895  \SpecialChar ~
13896  ...
13897
13898 \newline
13899 }
13900 \newline
13901 #pragma restore
13902 \begin_inset LatexCommand \index{\#pragma restore}
13903
13904 \end_inset
13905
13906  /* turn the optimizations back on */
13907 \layout Standard
13908
13909 The compiler will generate a warning message when extra space is allocated.
13910  It is strongly recommended that the save and restore pragma's be used when
13911  changing options for a function.
13912 \layout Section
13913
13914 Defines Created by the Compiler
13915 \layout Standard
13916
13917 The compiler creates the following #defines
13918 \begin_inset LatexCommand \index{\#defines}
13919
13920 \end_inset
13921
13922
13923 \begin_inset LatexCommand \index{Defines created by the compiler}
13924
13925 \end_inset
13926
13927 :
13928 \newline
13929
13930 \layout Standard
13931
13932
13933 \begin_inset  Tabular
13934 <lyxtabular version="3" rows="10" columns="2">
13935 <features>
13936 <column alignment="center" valignment="top" leftline="true" width="0(null)">
13937 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
13938 <row topline="true" bottomline="true">
13939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13940 \begin_inset Text
13941
13942 \layout Standard
13943
13944
13945 \series bold
13946 #define
13947 \end_inset
13948 </cell>
13949 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13950 \begin_inset Text
13951
13952 \layout Standard
13953
13954
13955 \series bold
13956 Description
13957 \end_inset
13958 </cell>
13959 </row>
13960 <row topline="true">
13961 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13962 \begin_inset Text
13963
13964 \layout Standard
13965
13966 SDCC
13967 \begin_inset LatexCommand \index{SDCC}
13968
13969 \end_inset
13970
13971
13972 \end_inset
13973 </cell>
13974 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13975 \begin_inset Text
13976
13977 \layout Standard
13978
13979 this Symbol is always defined
13980 \end_inset
13981 </cell>
13982 </row>
13983 <row topline="true">
13984 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13985 \begin_inset Text
13986
13987 \layout Standard
13988
13989 SDCC_mcs51
13990 \begin_inset LatexCommand \index{SDCC\_mcs51}
13991
13992 \end_inset
13993
13994  or SDCC_ds390
13995 \begin_inset LatexCommand \index{SDCC\_ds390}
13996
13997 \end_inset
13998
13999  or SDCC_z80
14000 \begin_inset LatexCommand \index{SDCC\_z80}
14001
14002 \end_inset
14003
14004 , etc
14005 \end_inset
14006 </cell>
14007 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14008 \begin_inset Text
14009
14010 \layout Standard
14011
14012 depending on the model used (e.g.: -mds390
14013 \end_inset
14014 </cell>
14015 </row>
14016 <row topline="true">
14017 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14018 \begin_inset Text
14019
14020 \layout Standard
14021
14022 __mcs51
14023 \begin_inset LatexCommand \index{\_\_mcs51}
14024
14025 \end_inset
14026
14027 , __ds390
14028 \begin_inset LatexCommand \index{\_\_ds390}
14029
14030 \end_inset
14031
14032 , __hc08
14033 \begin_inset LatexCommand \index{\_\_hc08}
14034
14035 \end_inset
14036
14037 , __z80
14038 \begin_inset LatexCommand \index{\_\_z80}
14039
14040 \end_inset
14041
14042 , etc
14043 \end_inset
14044 </cell>
14045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14046 \begin_inset Text
14047
14048 \layout Standard
14049
14050 depending on the model used (e.g.
14051  -mz80)
14052 \end_inset
14053 </cell>
14054 </row>
14055 <row topline="true">
14056 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14057 \begin_inset Text
14058
14059 \layout Standard
14060
14061 SDCC_STACK_AUTO
14062 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
14063
14064 \end_inset
14065
14066
14067 \end_inset
14068 </cell>
14069 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14070 \begin_inset Text
14071
14072 \layout Standard
14073
14074 when
14075 \emph on
14076 -
14077 \begin_inset ERT
14078 status Collapsed
14079
14080 \layout Standard
14081
14082 \backslash
14083 /
14084 \end_inset
14085
14086 -stack-auto
14087 \emph default
14088  option is used
14089 \end_inset
14090 </cell>
14091 </row>
14092 <row topline="true">
14093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14094 \begin_inset Text
14095
14096 \layout Standard
14097
14098 SDCC_MODEL_SMALL
14099 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
14100
14101 \end_inset
14102
14103
14104 \end_inset
14105 </cell>
14106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14107 \begin_inset Text
14108
14109 \layout Standard
14110
14111 when
14112 \emph on
14113 -
14114 \begin_inset ERT
14115 status Collapsed
14116
14117 \layout Standard
14118
14119 \backslash
14120 /
14121 \end_inset
14122
14123 -model-small
14124 \emph default
14125  is used
14126 \end_inset
14127 </cell>
14128 </row>
14129 <row topline="true">
14130 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14131 \begin_inset Text
14132
14133 \layout Standard
14134
14135 SDCC_MODEL_LARGE
14136 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
14137
14138 \end_inset
14139
14140
14141 \end_inset
14142 </cell>
14143 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14144 \begin_inset Text
14145
14146 \layout Standard
14147
14148 when
14149 \emph on
14150 -
14151 \begin_inset ERT
14152 status Collapsed
14153
14154 \layout Standard
14155
14156 \backslash
14157 /
14158 \end_inset
14159
14160 -model-large
14161 \emph default
14162  is used
14163 \end_inset
14164 </cell>
14165 </row>
14166 <row topline="true">
14167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14168 \begin_inset Text
14169
14170 \layout Standard
14171
14172 SDCC_USE_XSTACK
14173 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
14174
14175 \end_inset
14176
14177
14178 \end_inset
14179 </cell>
14180 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14181 \begin_inset Text
14182
14183 \layout Standard
14184
14185 when
14186 \emph on
14187 -
14188 \begin_inset ERT
14189 status Collapsed
14190
14191 \layout Standard
14192
14193 \backslash
14194 /
14195 \end_inset
14196
14197 -xstack
14198 \emph default
14199  option is used
14200 \end_inset
14201 </cell>
14202 </row>
14203 <row topline="true">
14204 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14205 \begin_inset Text
14206
14207 \layout Standard
14208
14209 SDCC_STACK_TENBIT
14210 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
14211
14212 \end_inset
14213
14214
14215 \end_inset
14216 </cell>
14217 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14218 \begin_inset Text
14219
14220 \layout Standard
14221
14222 when
14223 \emph on
14224 -mds390
14225 \emph default
14226  is used
14227 \end_inset
14228 </cell>
14229 </row>
14230 <row topline="true" bottomline="true">
14231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14232 \begin_inset Text
14233
14234 \layout Standard
14235
14236 SDCC_MODEL_FLAT24
14237 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
14238
14239 \end_inset
14240
14241
14242 \end_inset
14243 </cell>
14244 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14245 \begin_inset Text
14246
14247 \layout Standard
14248
14249 when
14250 \emph on
14251 -mds390
14252 \emph default
14253  is used
14254 \end_inset
14255 </cell>
14256 </row>
14257 </lyxtabular>
14258
14259 \end_inset
14260
14261
14262 \layout Chapter
14263
14264 Notes on supported Processors
14265 \layout Section
14266
14267 MCS51 variants
14268 \begin_inset LatexCommand \label{sub:MCS51-variants}
14269
14270 \end_inset
14271
14272
14273 \begin_inset LatexCommand \index{MCS51 variants}
14274
14275 \end_inset
14276
14277
14278 \layout Standard
14279
14280 MCS51 processors are available from many vendors and come in many different
14281  flavours.
14282  While they might differ considerably in respect to Special Function Registers
14283  the core MCS51 is usually not modified or is kept compatible.
14284
14285 \layout Subsection
14286
14287 pdata access by SFR
14288 \layout Standard
14289
14290 With the upcome of devices with internal xdata and flash memory devices
14291  using port P2
14292 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14293
14294 \end_inset
14295
14296  as dedicated I/O port is becoming more popular.
14297  Switching the high byte for pdata
14298 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14299
14300 \end_inset
14301
14302  access which was formerly done by port P2 is then achieved by a Special
14303  Function Register
14304 \begin_inset LatexCommand \index{sfr}
14305
14306 \end_inset
14307
14308 .
14309  In well-established MCS51 tradition the address of this
14310 \emph on
14311 sfr
14312 \emph default
14313  is where the chip designers decided to put it.
14314  Needless to say that they didn't agree on a common name either.
14315  So that the startup code can correctly initialize xdata variables, you
14316  should define an sfr with the name _XPAGE at the appropriate location if
14317  the default, port P2, is not used for this.
14318  Some examples are:
14319 \layout Verse
14320
14321
14322 \family typewriter
14323 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
14324 \layout Verse
14325
14326
14327 \family typewriter
14328 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
14329 \layout Verse
14330
14331
14332 \family typewriter
14333 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
14334 \layout Standard
14335
14336 For more exotic implementations further customizations may be needed.
14337  See section
14338 \begin_inset LatexCommand \ref{sub:Startup-Code}
14339
14340 \end_inset
14341
14342  for other possibilities.
14343 \layout Subsection
14344
14345 Other Features available by SFR
14346 \layout Standard
14347
14348 Some MCS51 variants offer features like Double DPTR
14349 \begin_inset LatexCommand \index{DPTR}
14350
14351 \end_inset
14352
14353 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
14354  These are currently not used for the MCS51 port.
14355  If you absolutely need them you can fall back to inline assembly or submit
14356  a patch to SDCC.
14357 \layout Section
14358
14359 The Z80 and gbz80 port
14360 \layout Standard
14361
14362 SDCC can target both the Zilog
14363 \begin_inset LatexCommand \index{Z80}
14364
14365 \end_inset
14366
14367  and the Nintendo Gameboy's Z80-like gbz80
14368 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
14369
14370 \end_inset
14371
14372 .
14373  The Z80 port is passed through the same
14374 \emph on
14375 regressions tests
14376 \begin_inset LatexCommand \index{Regression test}
14377
14378 \end_inset
14379
14380
14381 \emph default
14382  as the MCS51 and DS390 ports, so floating point support, support for long
14383  variables and bitfield support is fine.
14384  See mailing lists and forums about interrupt routines.
14385 \layout Standard
14386
14387 As always, the code is the authoritative reference - see z80/ralloc.c and
14388  z80/gen.c.
14389  The stack
14390 \begin_inset LatexCommand \index{stack}
14391
14392 \end_inset
14393
14394  frame is similar to that generated by the IAR Z80 compiler.
14395  IX is used as the base pointer, HL and IY are used as a temporary registers,
14396  and BC and DE are available for holding variables.
14397  Return values
14398 \begin_inset LatexCommand \index{return value}
14399
14400 \end_inset
14401
14402  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
14403  bytes).
14404  The gbz80 port use the same set of registers for the return values, but
14405  in a different order of significance: E (one byte), DE (two bytes), or
14406  HLDE (four bytes).
14407 \layout Section
14408
14409 The HC08 port
14410 \layout Standard
14411
14412 The port to the Motorola HC08
14413 \begin_inset LatexCommand \index{HC08}
14414
14415 \end_inset
14416
14417  family has been added in October 2003, and is still undergoing some basic
14418  development.
14419  The code generator is complete, but the register allocation is still quite
14420  unoptimized.
14421  Some of the SDCC's standard C library functions have embedded non-HC08
14422  inline assembly and so are not yet usable.
14423 \newline
14424
14425 \newline
14426
14427 \layout Section
14428
14429 The PIC14 port
14430 \layout Standard
14431
14432 The 14bit PIC
14433 \begin_inset LatexCommand \index{PIC14}
14434
14435 \end_inset
14436
14437  port still requires a major effort from the development community.
14438  However it can work for very simple code.
14439 \layout Subsection
14440
14441 C code and 14bit PIC code page
14442 \begin_inset LatexCommand \index{code page (pic14)}
14443
14444 \end_inset
14445
14446  and RAM banks
14447 \begin_inset LatexCommand \index{RAM bank (pic14)}
14448
14449 \end_inset
14450
14451
14452 \layout Standard
14453
14454 The linker organizes allocation for the code page and RAM banks.
14455  It does not have intimate knowledge of the code flow.
14456  It will put all the code section of a single asm file into a single code
14457  page.
14458  In order to make use of multiple code pages, separate asm files must be
14459  used.
14460  The compiler treats all functions of a single C file as being in the same
14461  code page unless it is non static.
14462  The compiler treats all local variables of a single C file as being in
14463  the same RAM bank unless it is an extern.
14464 \newline
14465
14466 \newline
14467 To get the best follow these guide lines:
14468 \layout Enumerate
14469
14470 make local functions static, as non static functions require code page selection
14471  overhead.
14472 \layout Enumerate
14473
14474 Make local variables static as extern variables require RAM bank selection
14475  overhead.
14476 \layout Enumerate
14477
14478 For devices that have multiple code pages it is more efficient to use the
14479  same number of files as pages, i.e.
14480  for the 16F877 use 4 separate files and i.e.
14481  for the 16F874 use 2 separate files.
14482  This way the linker can put the code for each file into different code
14483  pages and the compiler can allocate reusable variables more efficiently
14484  and there's less page selection overhead.
14485  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
14486  instruction set) use 'unsigned char' whereever possible instead of 'int'.
14487 \layout Subsection
14488
14489 Creating a device include file
14490 \layout Standard
14491
14492 For generating a device include file use the support perl script inc2h.pl
14493  kept in directory support/script.
14494 \layout Subsection
14495
14496 Interrupt code
14497 \layout Standard
14498
14499 For the interrupt function, use the keyword 'interrupt'
14500 \begin_inset LatexCommand \index{interrupt}
14501
14502 \end_inset
14503
14504  with level number of 0 (PIC14 only has 1 interrupt so this number is only
14505  there to avoid a syntax error - it ought to be fixed).
14506  E.g.:
14507 \layout Verse
14508
14509
14510 \family typewriter
14511 void Intr(void) interrupt 0
14512 \newline
14513 {
14514 \newline
14515 \SpecialChar ~
14516 \SpecialChar ~
14517 T0IF = 0; /* Clear timer interrupt */
14518 \newline
14519 }
14520 \layout Standard
14521
14522 Linking and assembling
14523 \newline
14524 For assembling you can use either GPUTILS'
14525 \begin_inset LatexCommand \index{gputils (pic tools)}
14526
14527 \end_inset
14528
14529  gpasm.exe or MPLAB's mpasmwin.exe.
14530  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
14531  If you use MPLAB and an interrupt function then the linker script file
14532  vectors section will need to be enlarged to link with mplink.
14533 \newline
14534
14535 \newline
14536 Here is a
14537 \family typewriter
14538 Makefile
14539 \family default
14540  using GPUTILS:
14541 \layout Verse
14542
14543
14544 \family typewriter
14545 .c.o:
14546 \newline
14547 \SpecialChar ~
14548 \SpecialChar ~
14549 \SpecialChar ~
14550 \SpecialChar ~
14551 \SpecialChar ~
14552 \SpecialChar ~
14553 \SpecialChar ~
14554 \SpecialChar ~
14555 sdcc -S -V -mpic14 -p16F877 $<
14556 \newline
14557 \SpecialChar ~
14558 \SpecialChar ~
14559 \SpecialChar ~
14560 \SpecialChar ~
14561 \SpecialChar ~
14562 \SpecialChar ~
14563 \SpecialChar ~
14564 \SpecialChar ~
14565 gpasm -c $*.asm
14566 \newline
14567
14568 \newline
14569 $(PRJ).hex: $(OBJS)
14570 \newline
14571 \SpecialChar ~
14572 \SpecialChar ~
14573 \SpecialChar ~
14574 \SpecialChar ~
14575 \SpecialChar ~
14576 \SpecialChar ~
14577 \SpecialChar ~
14578 \SpecialChar ~
14579 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
14580 \layout Standard
14581
14582 Here is a
14583 \family typewriter
14584 Makefile
14585 \family default
14586  using MPLAB:
14587 \layout Verse
14588
14589
14590 \family typewriter
14591 .c.o:
14592 \newline
14593 \SpecialChar ~
14594 \SpecialChar ~
14595 \SpecialChar ~
14596 \SpecialChar ~
14597 \SpecialChar ~
14598 \SpecialChar ~
14599 \SpecialChar ~
14600 \SpecialChar ~
14601 sdcc -S -V -mpic14 -p16F877 $<
14602 \newline
14603 \SpecialChar ~
14604 \SpecialChar ~
14605 \SpecialChar ~
14606 \SpecialChar ~
14607 \SpecialChar ~
14608 \SpecialChar ~
14609 \SpecialChar ~
14610 \SpecialChar ~
14611 mpasmwin /q /o $*.asm
14612 \newline
14613
14614 \newline
14615 $(PRJ).hex: $(OBJS)
14616 \newline
14617 \SpecialChar ~
14618 \SpecialChar ~
14619 \SpecialChar ~
14620 \SpecialChar ~
14621 \SpecialChar ~
14622 \SpecialChar ~
14623 \SpecialChar ~
14624 \SpecialChar ~
14625 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
14626 \layout Section
14627
14628 The PIC16
14629 \begin_inset LatexCommand \index{PIC16}
14630
14631 \end_inset
14632
14633  port
14634 \layout Standard
14635
14636 The PIC16
14637 \begin_inset LatexCommand \index{PIC16}
14638
14639 \end_inset
14640
14641  port is the portion of SDCC that is responsible to produce code for the
14642  Microchip
14643 \begin_inset LatexCommand \index{Microchip}
14644
14645 \end_inset
14646
14647 (TM) microcontrollers with 16 bit core.
14648  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
14649 \layout Subsection
14650
14651 Global Options
14652 \layout Standard
14653
14654 PIC16 port supports the standard command line arguments as supposed, with
14655  the exception of certain cases that will be mentioned in the following
14656  list:
14657 \layout List
14658 \labelwidthstring 00.00.0000
14659
14660 -
14661 \begin_inset ERT
14662 status Collapsed
14663
14664 \layout Standard
14665
14666 \backslash
14667 /
14668 \end_inset
14669
14670 -stack-auto Auto variables that are function parameters, will be saved on
14671  stack by default.
14672
14673 \emph on
14674 There is no need to specify this in the command line.
14675 \layout List
14676 \labelwidthstring 00.00.0000
14677
14678 -
14679 \begin_inset ERT
14680 status Collapsed
14681
14682 \layout Standard
14683
14684 \backslash
14685 /
14686 \end_inset
14687
14688 -float-reent All floating point functions are reentrant by default.
14689
14690 \emph on
14691 There is no need to specifiy this in the command line.
14692 \layout List
14693 \labelwidthstring 00.00.0000
14694
14695 -
14696 \begin_inset ERT
14697 status Collapsed
14698
14699 \layout Standard
14700
14701 \backslash
14702 /
14703 \end_inset
14704
14705 -callee-saves See -
14706 \begin_inset ERT
14707 status Collapsed
14708
14709 \layout Standard
14710
14711 \backslash
14712 /
14713 \end_inset
14714
14715 -all-callee-saves
14716 \layout List
14717 \labelwidthstring 00.00.0000
14718
14719 -
14720 \begin_inset ERT
14721 status Collapsed
14722
14723 \layout Standard
14724
14725 \backslash
14726 /
14727 \end_inset
14728
14729 -all-callee-saves All function arguments are passed on stack by default.
14730
14731 \emph on
14732 There is no need to specify this in the command line.
14733 \layout List
14734 \labelwidthstring 00.00.0000
14735
14736 -
14737 \begin_inset ERT
14738 status Collapsed
14739
14740 \layout Standard
14741
14742 \backslash
14743 /
14744 \end_inset
14745
14746 -fommit-frame-pointer Frame pointer will be omitted when the function uses
14747  no local variables.
14748 \layout Subsection
14749
14750 Port Specific Options
14751 \layout Standard
14752
14753 The port specific options appear after the global options in the sdcc --help
14754  output.
14755 \layout Subsubsection
14756
14757 General Options
14758 \layout Standard
14759
14760 General options enable certain port features and optimizations.
14761 \layout List
14762 \labelwidthstring 00.00.0000
14763
14764 -
14765 \begin_inset ERT
14766 status Collapsed
14767
14768 \layout Standard
14769
14770 \backslash
14771 /
14772 \end_inset
14773
14774 -pgen-bank Instructs the port to insert BANKSEL directives before instructions
14775  that use the Bank Select Register (BSR).
14776 \layout List
14777 \labelwidthstring 00.00.0000
14778
14779 -
14780 \begin_inset ERT
14781 status Collapsed
14782
14783 \layout Standard
14784
14785 \backslash
14786 /
14787 \end_inset
14788
14789 -pomit-config-words Instructs the port to omit the generation of the configurati
14790 on words.
14791 \layout List
14792 \labelwidthstring 00.00.0000
14793
14794 -
14795 \begin_inset ERT
14796 status Collapsed
14797
14798 \layout Standard
14799
14800 \backslash
14801 /
14802 \end_inset
14803
14804 -pomit-ivt Instructs the port to omit the generation of the interrupt vectors
14805 \layout List
14806 \labelwidthstring 00.00.0000
14807
14808 -
14809 \begin_inset ERT
14810 status Collapsed
14811
14812 \layout Standard
14813
14814 \backslash
14815 /
14816 \end_inset
14817
14818 -pleave-reset-vector Used in conjuction with the previous command, instructs
14819  the port NOT to omit the reset vector.
14820 \layout List
14821 \labelwidthstring 00.00.0000
14822
14823 -
14824 \begin_inset ERT
14825 status Collapsed
14826
14827 \layout Standard
14828
14829 \backslash
14830 /
14831 \end_inset
14832
14833 -stack-model=[model] Used in conjuction with the command above.
14834  Defines the stack model to be used, valid stack models are :
14835 \begin_deeper
14836 \layout List
14837 \labelwidthstring 00.00.0000
14838
14839
14840 \emph on
14841 small
14842 \emph default
14843  Selects small stack model.
14844  8 bit stack and frame pointers.
14845  Supports 256 bytes stack size.
14846 \layout List
14847 \labelwidthstring 00.00.0000
14848
14849
14850 \emph on
14851 large
14852 \emph default
14853  Selects large stack model.
14854  16 bit stack and frame pointers.
14855  Supports 65536 bytes stack size.
14856 \end_deeper
14857 \layout List
14858 \labelwidthstring 00.00.0000
14859
14860 -
14861 \begin_inset ERT
14862 status Collapsed
14863
14864 \layout Standard
14865
14866 \backslash
14867 /
14868 \end_inset
14869
14870 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
14871  unitialized data variables with [kword].
14872  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
14873 \layout Subsubsection
14874
14875 Debugging Options
14876 \layout Standard
14877
14878 Debugging options enable extra debugging information in the output files.
14879 \layout List
14880 \labelwidthstring 00.00.0000
14881
14882 -
14883 \begin_inset ERT
14884 status Collapsed
14885
14886 \layout Standard
14887
14888 \backslash
14889 /
14890 \end_inset
14891
14892 -debug-xtra Similar to --debug, but dumps more information.
14893 \layout List
14894 \labelwidthstring 00.00.0000
14895
14896 -
14897 \begin_inset ERT
14898 status Collapsed
14899
14900 \layout Standard
14901
14902 \backslash
14903 /
14904 \end_inset
14905
14906 -debug-ralloc Force register allocator to dump <source>.d file with debugging
14907  information.
14908  <source> is the name of the file compiled.
14909 \layout List
14910 \labelwidthstring 00.00.0000
14911
14912 -
14913 \begin_inset ERT
14914 status Collapsed
14915
14916 \layout Standard
14917
14918 \backslash
14919 /
14920 \end_inset
14921
14922 -pcode-verbose Enable pcode debugging information in translation.
14923 \layout Subsection
14924
14925 Preprocessor Macros
14926 \layout Standard
14927
14928 PIC16 port defines the following preprocessor macros while translating a
14929  source.
14930 \layout Standard
14931 \align center
14932
14933 \begin_inset  Tabular
14934 <lyxtabular version="3" rows="2" columns="2">
14935 <features>
14936 <column alignment="center" valignment="top" leftline="true" width="0(null)">
14937 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
14938 <row topline="true" bottomline="true">
14939 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14940 \begin_inset Text
14941
14942 \layout Standard
14943
14944 Macro
14945 \end_inset
14946 </cell>
14947 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14948 \begin_inset Text
14949
14950 \layout Standard
14951
14952 Description
14953 \end_inset
14954 </cell>
14955 </row>
14956 <row topline="true" bottomline="true">
14957 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14958 \begin_inset Text
14959
14960 \layout Standard
14961
14962 pic18fxxxx
14963 \end_inset
14964 </cell>
14965 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14966 \begin_inset Text
14967
14968 \layout Standard
14969
14970 MCU Identification.
14971
14972 \emph on
14973 xxxx
14974 \emph default
14975  is the microcontrol identification number, i.e.
14976  452, 6620, etc
14977 \end_inset
14978 </cell>
14979 </row>
14980 </lyxtabular>
14981
14982 \end_inset
14983
14984
14985 \layout Subsection
14986
14987 Directories
14988 \layout Standard
14989
14990 PIC16 port uses the following directories for searching header files and
14991  libraries.
14992 \layout Standard
14993 \align center
14994
14995 \begin_inset  Tabular
14996 <lyxtabular version="3" rows="3" columns="4">
14997 <features>
14998 <column alignment="center" valignment="top" leftline="true" width="0(null)">
14999 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
15000 <column alignment="center" valignment="top" width="0(null)">
15001 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
15002 <row topline="true" bottomline="true">
15003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15004 \begin_inset Text
15005
15006 \layout Standard
15007
15008 Directory
15009 \end_inset
15010 </cell>
15011 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15012 \begin_inset Text
15013
15014 \layout Standard
15015
15016 Description
15017 \end_inset
15018 </cell>
15019 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15020 \begin_inset Text
15021
15022 \layout Standard
15023
15024 Target
15025 \end_inset
15026 </cell>
15027 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15028 \begin_inset Text
15029
15030 \layout Standard
15031
15032 Command prefix
15033 \end_inset
15034 </cell>
15035 </row>
15036 <row topline="true">
15037 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15038 \begin_inset Text
15039
15040 \layout Standard
15041
15042 PREFIX/sdcc/include/pic16
15043 \end_inset
15044 </cell>
15045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15046 \begin_inset Text
15047
15048 \layout Standard
15049
15050 PIC16 specific headers
15051 \end_inset
15052 </cell>
15053 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15054 \begin_inset Text
15055
15056 \layout Standard
15057
15058 Compiler
15059 \end_inset
15060 </cell>
15061 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15062 \begin_inset Text
15063
15064 \layout Standard
15065
15066 -I
15067 \end_inset
15068 </cell>
15069 </row>
15070 <row topline="true" bottomline="true">
15071 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15072 \begin_inset Text
15073
15074 \layout Standard
15075
15076 PREFIX/sdcc/lib/pic16
15077 \end_inset
15078 </cell>
15079 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15080 \begin_inset Text
15081
15082 \layout Standard
15083
15084 PIC16 specific libraries
15085 \end_inset
15086 </cell>
15087 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15088 \begin_inset Text
15089
15090 \layout Standard
15091
15092 Linker
15093 \end_inset
15094 </cell>
15095 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15096 \begin_inset Text
15097
15098 \layout Standard
15099
15100 -L
15101 \end_inset
15102 </cell>
15103 </row>
15104 </lyxtabular>
15105
15106 \end_inset
15107
15108
15109 \layout Subsection
15110
15111 Pragmas
15112 \layout Standard
15113
15114 PIC16 port currently supports the following pragmas:
15115 \layout List
15116 \labelwidthstring 00.00.0000
15117
15118 stack pragma stack forces the code generator to initialize the stack & frame
15119  pointers at a specific address.
15120  This is an adhoc solution since gplink does not support yet stack.
15121  When the gplink issue is resolved the pragma will be deprecated
15122 \begin_inset Foot
15123 collapsed true
15124
15125 \layout Standard
15126
15127
15128 \emph on
15129 It is important to initialize the stack, otherwise strange things can happen.
15130  Stack is not initialized by default because there are some sources that
15131  do not require it.
15132  (like library sources)
15133 \end_inset
15134
15135 .
15136 \newline
15137 The stack pragma should be used only once in a project.
15138  Multiple pragmas may result in indeterminate behaviour of the program.
15139 \newline
15140 If you omit setting the pragma the port emits a warning message before linking.
15141  If not initializing the stack is desired ignore the message.
15142 \layout LyX-Code
15143
15144 Example:
15145 \layout LyX-Code
15146
15147 \layout LyX-Code
15148
15149 /* initializes stack at RAM address 0x5ff*/
15150 \layout LyX-Code
15151
15152 #pragma stack 0x5ff
15153 \layout LyX-Code
15154
15155 \layout Subsection
15156
15157 Header Files
15158 \layout Standard
15159
15160 There is one main header file that can be included to the source files using
15161  the pic16 port.
15162  That file is the
15163 \series bold
15164 pic18fregs.h
15165 \series default
15166 .
15167  This header file contains the definitions for the processor special registers,
15168  so it is necessery if the soruce accesses them.
15169  It can be included by adding the following line in the beginning of the
15170  file:
15171 \layout LyX-Code
15172
15173 #include <pic18fregs.h>
15174 \layout Standard
15175
15176 The specific microcontroller is selected within the pic18fregs.h automatically,
15177  so the same source can be used with a variety of devices.
15178 \layout Subsection
15179
15180 Libraries
15181 \layout Standard
15182
15183 The libraries that pic16 port depends on are the microcontroller device
15184  libraries which contain the symbol definitions for the microcontroller
15185  special function registers.
15186  These libraries have the format pic18fxxxx.lib, where
15187 \emph on
15188 xxxx
15189 \emph default
15190  is the microcontroller identification number.
15191  The specific library is selected automatically by the compiler at link
15192  stage according to the selected device.
15193 \layout Standard
15194
15195 Libraries are created with gplib which is part of the gputils package
15196 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
15197
15198 \end_inset
15199
15200 .
15201 \layout Subsection
15202
15203 Memory Models
15204 \layout Standard
15205
15206 The following memory models are supported by PIC16 port:
15207 \layout Itemize
15208
15209 small model
15210 \layout Itemize
15211
15212 large model
15213 \layout Standard
15214
15215 Memory model affects the default size of pointers within the source.
15216  The sizes are shown in the next table:
15217 \layout Standard
15218 \align center
15219
15220 \begin_inset  Tabular
15221 <lyxtabular version="3" rows="3" columns="3">
15222 <features>
15223 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
15224 <column alignment="center" valignment="top" leftline="true" width="0(null)">
15225 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
15226 <row topline="true" bottomline="true">
15227 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15228 \begin_inset Text
15229
15230 \layout Standard
15231
15232 Pointer sizes according to memory model
15233 \end_inset
15234 </cell>
15235 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15236 \begin_inset Text
15237
15238 \layout Standard
15239
15240 small model
15241 \end_inset
15242 </cell>
15243 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15244 \begin_inset Text
15245
15246 \layout Standard
15247
15248 large model
15249 \end_inset
15250 </cell>
15251 </row>
15252 <row topline="true" bottomline="true">
15253 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15254 \begin_inset Text
15255
15256 \layout Standard
15257
15258 code pointers
15259 \end_inset
15260 </cell>
15261 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15262 \begin_inset Text
15263
15264 \layout Standard
15265
15266 16-bits
15267 \end_inset
15268 </cell>
15269 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15270 \begin_inset Text
15271
15272 \layout Standard
15273
15274 24-bits
15275 \end_inset
15276 </cell>
15277 </row>
15278 <row topline="true" bottomline="true">
15279 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15280 \begin_inset Text
15281
15282 \layout Standard
15283
15284 data pointers
15285 \end_inset
15286 </cell>
15287 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
15288 \begin_inset Text
15289
15290 \layout Standard
15291
15292 16-bits
15293 \end_inset
15294 </cell>
15295 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15296 \begin_inset Text
15297
15298 \layout Standard
15299
15300 16-bits
15301 \end_inset
15302 </cell>
15303 </row>
15304 </lyxtabular>
15305
15306 \end_inset
15307
15308
15309 \layout Standard
15310
15311 It is advisable that all sources within a project are compiled with the
15312  same memory model.
15313  If one wants to override the default memory model, this can be done by
15314  declaring a pointer as
15315 \series bold
15316 far
15317 \series default
15318  or
15319 \series bold
15320 near
15321 \series default
15322 .
15323  Far selects large memory model's pointers, while near selects small memory
15324  model's pointers.
15325 \layout Standard
15326
15327 The standard device libraries (see 4.5.6) contain no reference to pointers,
15328  so they can be used with both memory models.
15329 \layout Subsection
15330
15331 Stack
15332 \layout Standard
15333
15334 The stack implementation for the PIC16 port uses two indirect registers,
15335  FSR1 and FSR2.
15336 \layout List
15337 \labelwidthstring 00.00.0000
15338
15339 FSR1 is assigned as stack pointer
15340 \layout List
15341 \labelwidthstring 00.00.0000
15342
15343 FSR2 is assigned as frame pointer
15344 \layout Standard
15345
15346 The following stack models are supported by PIC16 port
15347 \layout Itemize
15348
15349 small model
15350 \layout Itemize
15351
15352 large model
15353 \layout Standard
15354
15355
15356 \noun on
15357 Small
15358 \noun default
15359  model means that only the FSRxL byte is used to access stack and frame,
15360  while
15361 \emph on
15362 \noun on
15363 large
15364 \emph default
15365 \noun default
15366  uses both FSRxL and FSRxH registers.
15367  The following table shows the stack/frame pointers sizes according to stack
15368  model and the maximum space they can address:
15369 \layout Standard
15370 \align center
15371
15372 \begin_inset  Tabular
15373 <lyxtabular version="3" rows="3" columns="3">
15374 <features>
15375 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
15376 <column alignment="center" valignment="top" leftline="true" width="0(null)">
15377 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
15378 <row topline="true" bottomline="true">
15379 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15380 \begin_inset Text
15381
15382 \layout Standard
15383
15384 Stack & Frame pointer sizes according to stack model
15385 \end_inset
15386 </cell>
15387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15388 \begin_inset Text
15389
15390 \layout Standard
15391
15392 small
15393 \end_inset
15394 </cell>
15395 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15396 \begin_inset Text
15397
15398 \layout Standard
15399
15400 large
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 Stack pointer FSR1
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 8-bits
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 16-bits
15427 \end_inset
15428 </cell>
15429 </row>
15430 <row topline="true" bottomline="true">
15431 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15432 \begin_inset Text
15433
15434 \layout Standard
15435
15436 Frame pointer FSR2
15437 \end_inset
15438 </cell>
15439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15440 \begin_inset Text
15441
15442 \layout Standard
15443
15444 8-bits
15445 \end_inset
15446 </cell>
15447 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15448 \begin_inset Text
15449
15450 \layout Standard
15451
15452 16-bits
15453 \end_inset
15454 </cell>
15455 </row>
15456 </lyxtabular>
15457
15458 \end_inset
15459
15460
15461 \layout Standard
15462
15463
15464 \series bold
15465 Currently stack and frame pointers should be initialized explicit by the
15466  user at the desired Data RAM position (see 4.5.5 Pragma Stack).
15467  Uninitialized stack and frame pointers can result in unexpected behavior
15468  of the resulting binary.
15469 \layout Subsection
15470
15471 Function return values
15472 \layout Standard
15473
15474 Return values from functions are placed to the appropriate registers following
15475  a modified Microchip policy optimized for SDCC.
15476  The following table shows these registers:
15477 \layout Standard
15478 \align center
15479
15480 \begin_inset  Tabular
15481 <lyxtabular version="3" rows="6" columns="2">
15482 <features>
15483 <column alignment="center" valignment="top" leftline="true" width="0(null)">
15484 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0(null)">
15485 <row topline="true" bottomline="true">
15486 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15487 \begin_inset Text
15488
15489 \layout Standard
15490
15491 size
15492 \end_inset
15493 </cell>
15494 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15495 \begin_inset Text
15496
15497 \layout Standard
15498
15499 destination register
15500 \end_inset
15501 </cell>
15502 </row>
15503 <row topline="true">
15504 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15505 \begin_inset Text
15506
15507 \layout Standard
15508
15509 8 bits
15510 \end_inset
15511 </cell>
15512 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15513 \begin_inset Text
15514
15515 \layout Standard
15516
15517 WREG
15518 \end_inset
15519 </cell>
15520 </row>
15521 <row topline="true">
15522 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15523 \begin_inset Text
15524
15525 \layout Standard
15526
15527 16 bits
15528 \end_inset
15529 </cell>
15530 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15531 \begin_inset Text
15532
15533 \layout Standard
15534
15535 PRODL:WREG
15536 \end_inset
15537 </cell>
15538 </row>
15539 <row topline="true">
15540 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15541 \begin_inset Text
15542
15543 \layout Standard
15544
15545 24 bits
15546 \end_inset
15547 </cell>
15548 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15549 \begin_inset Text
15550
15551 \layout Standard
15552
15553 PRODH:PRODL:WREG
15554 \end_inset
15555 </cell>
15556 </row>
15557 <row topline="true">
15558 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15559 \begin_inset Text
15560
15561 \layout Standard
15562
15563 32 bits
15564 \end_inset
15565 </cell>
15566 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15567 \begin_inset Text
15568
15569 \layout Standard
15570
15571 FSR0L:PRODH:PRODL:WREG
15572 \end_inset
15573 </cell>
15574 </row>
15575 <row topline="true" bottomline="true">
15576 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15577 \begin_inset Text
15578
15579 \layout Standard
15580
15581 >32 bits
15582 \end_inset
15583 </cell>
15584 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15585 \begin_inset Text
15586
15587 \layout Standard
15588
15589 on stack, FSR0 points to the beginning
15590 \end_inset
15591 </cell>
15592 </row>
15593 </lyxtabular>
15594
15595 \end_inset
15596
15597
15598 \layout Subsection
15599
15600 Interrupts
15601 \layout Standard
15602
15603 When entering an interrupt, currently the PIC16 port automatically saves
15604  the following registers:
15605 \layout Itemize
15606
15607 WREG
15608 \layout Itemize
15609
15610 STATUS
15611 \layout Itemize
15612
15613 BSR
15614 \layout Itemize
15615
15616 PROD (PRODL and PRODH)
15617 \layout Itemize
15618
15619 FSR0 (FSR0L and FSR0H)
15620 \layout Standard
15621
15622 These registers are restored upon return from the interrupt routine
15623 \begin_inset Foot
15624 collapsed false
15625
15626 \layout Standard
15627
15628 NOTE that when the _naked attribute is specified for an interrupt routine,
15629  then NO registers are stored or restored.
15630 \end_inset
15631
15632 .
15633 \layout Chapter
15634
15635 Debugging with SDCDB
15636 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
15637
15638 \end_inset
15639
15640
15641 \begin_inset LatexCommand \index{sdcdb (debugger)}
15642
15643 \end_inset
15644
15645
15646 \layout Standard
15647
15648 SDCC is distributed with a source level debugger
15649 \begin_inset LatexCommand \index{Debugger}
15650
15651 \end_inset
15652
15653 .
15654  The debugger uses a command line interface, the command repertoire of the
15655  debugger has been kept as close to gdb
15656 \begin_inset LatexCommand \index{gdb}
15657
15658 \end_inset
15659
15660  (the GNU debugger) as possible.
15661  The configuration and build process is part of the standard compiler installati
15662 on, which also builds and installs the debugger in the target directory
15663  specified during configuration.
15664  The debugger allows you debug BOTH at the C source and at the ASM source
15665  level.
15666  Sdcdb is available on Unix platforms only.
15667 \layout Section
15668
15669 Compiling for Debugging
15670 \layout Standard
15671
15672 The \SpecialChar \-
15673 \SpecialChar \-
15674 debug option must be specified for all files for which debug information
15675  is to be generated.
15676  The complier generates a .adb file for each of these files.
15677  The linker creates the .cdb
15678 \begin_inset LatexCommand \index{<file>.cdb}
15679
15680 \end_inset
15681
15682  file from the .adb
15683 \begin_inset LatexCommand \index{<file>.adb}
15684
15685 \end_inset
15686
15687  files and the address information.
15688  This .cdb is used by the debugger.
15689 \layout Section
15690
15691 How the Debugger Works
15692 \layout Standard
15693
15694 When the -
15695 \begin_inset ERT
15696 status Collapsed
15697
15698 \layout Standard
15699
15700 \backslash
15701 /
15702 \end_inset
15703
15704 -debug option is specified the compiler generates extra symbol information
15705  some of which are put into the assembler source and some are put into the
15706  .adb file.
15707   Then the linker creates the .cdb file from the individual .adb files with
15708  the address information for the symbols.
15709  The debugger reads the symbolic information generated by the compiler &
15710  the address information generated by the linker.
15711  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
15712  execution is controlled by the debugger.
15713  When a command is issued for the debugger, it translates it into appropriate
15714  commands for the simulator.
15715 \layout Section
15716
15717 Starting the Debugger
15718 \layout Standard
15719
15720 The debugger can be started using the following command line.
15721  (Assume the file you are debugging has the file name foo).
15722 \newline
15723
15724 \newline
15725
15726 \family sans
15727 \series bold
15728 sdcdb foo
15729 \newline
15730
15731 \family default
15732 \series default
15733
15734 \newline
15735 The debugger will look for the following files.
15736 \layout Itemize
15737
15738 foo.c - the source file.
15739 \layout Itemize
15740
15741 foo.cdb - the debugger symbol information file.
15742 \layout Itemize
15743
15744 foo.ihx - the Intel hex format
15745 \begin_inset LatexCommand \index{Intel hex format}
15746
15747 \end_inset
15748
15749  object file.
15750 \layout Section
15751
15752 Command Line Options.
15753 \layout Itemize
15754
15755 -
15756 \begin_inset ERT
15757 status Collapsed
15758
15759 \layout Standard
15760
15761 \backslash
15762 /
15763 \end_inset
15764
15765 -directory=<source file directory> this option can used to specify the directory
15766  search list.
15767  The debugger will look into the directory list specified for source, cdb
15768  & ihx files.
15769  The items in the directory list must be separated by ':', e.g.
15770  if the source files can be in the directories /home/src1 and /home/src2,
15771  the -
15772 \begin_inset ERT
15773 status Collapsed
15774
15775 \layout Standard
15776
15777 \backslash
15778 /
15779 \end_inset
15780
15781 -directory option should be -
15782 \begin_inset ERT
15783 status Collapsed
15784
15785 \layout Standard
15786
15787 \backslash
15788 /
15789 \end_inset
15790
15791 -directory=/home/src1:/home/src2.
15792  Note there can be no spaces in the option.
15793
15794 \layout Itemize
15795
15796 -cd <directory> - change to the <directory>.
15797 \layout Itemize
15798
15799 -fullname - used by GUI front ends.
15800 \layout Itemize
15801
15802 -cpu <cpu-type> - this argument is passed to the simulator please see the
15803  simulator docs for details.
15804 \layout Itemize
15805
15806 -X <Clock frequency > this options is passed to the simulator please see
15807  the simulator docs for details.
15808 \layout Itemize
15809
15810 -s <serial port file> passed to simulator see the simulator docs for details.
15811 \layout Itemize
15812
15813 -S <serial in,out> passed to simulator see the simulator docs for details.
15814 \layout Itemize
15815
15816 -k <port number> passed to simulator see the simulator docs for details.
15817 \layout Section
15818
15819 Debugger Commands.
15820 \layout Standard
15821
15822 As mentioned earlier the command interface for the debugger has been deliberatel
15823 y kept as close the GNU debugger gdb, as possible.
15824  This will help the integration with existing graphical user interfaces
15825  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
15826  If you use a graphical user interface for the debugger you can skip the
15827  next sections.
15828 \layout Subsubsection*
15829
15830 break [line | file:line | function | file:function]
15831 \layout Standard
15832
15833 Set breakpoint at specified line or function:
15834 \newline
15835
15836 \newline
15837
15838 \family sans
15839 \series bold
15840 sdcdb>break 100
15841 \newline
15842 sdcdb>break foo.c:100
15843 \newline
15844 sdcdb>break funcfoo
15845 \newline
15846 sdcdb>break foo.c:funcfoo
15847 \layout Subsubsection*
15848
15849 clear [line | file:line | function | file:function ]
15850 \layout Standard
15851
15852 Clear breakpoint at specified line or function:
15853 \newline
15854
15855 \newline
15856
15857 \family sans
15858 \series bold
15859 sdcdb>clear 100
15860 \newline
15861 sdcdb>clear foo.c:100
15862 \newline
15863 sdcdb>clear funcfoo
15864 \newline
15865 sdcdb>clear foo.c:funcfoo
15866 \layout Subsubsection*
15867
15868 continue
15869 \layout Standard
15870
15871 Continue program being debugged, after breakpoint.
15872 \layout Subsubsection*
15873
15874 finish
15875 \layout Standard
15876
15877 Execute till the end of the current function.
15878 \layout Subsubsection*
15879
15880 delete [n]
15881 \layout Standard
15882
15883 Delete breakpoint number 'n'.
15884  If used without any option clear ALL user defined break points.
15885 \layout Subsubsection*
15886
15887 info [break | stack | frame | registers ]
15888 \layout Itemize
15889
15890 info break - list all breakpoints
15891 \layout Itemize
15892
15893 info stack - show the function call stack.
15894 \layout Itemize
15895
15896 info frame - show information about the current execution frame.
15897 \layout Itemize
15898
15899 info registers - show content of all registers.
15900 \layout Subsubsection*
15901
15902 step
15903 \layout Standard
15904
15905 Step program until it reaches a different source line.
15906  Note: pressing <return> repeats the last command.
15907 \layout Subsubsection*
15908
15909 next
15910 \layout Standard
15911
15912 Step program, proceeding through subroutine calls.
15913 \layout Subsubsection*
15914
15915 run
15916 \layout Standard
15917
15918 Start debugged program.
15919 \layout Subsubsection*
15920
15921 ptype variable
15922 \layout Standard
15923
15924 Print type information of the variable.
15925 \layout Subsubsection*
15926
15927 print variable
15928 \layout Standard
15929
15930 print value of variable.
15931 \layout Subsubsection*
15932
15933 file filename
15934 \layout Standard
15935
15936 load the given file name.
15937  Note this is an alternate method of loading file for debugging.
15938 \layout Subsubsection*
15939
15940 frame
15941 \layout Standard
15942
15943 print information about current frame.
15944 \layout Subsubsection*
15945
15946 set srcmode
15947 \layout Standard
15948
15949 Toggle between C source & assembly source.
15950 \layout Subsubsection*
15951
15952 ! simulator command
15953 \layout Standard
15954
15955 Send the string following '!' to the simulator, the simulator response is
15956  displayed.
15957  Note the debugger does not interpret the command being sent to the simulator,
15958  so if a command like 'go' is sent the debugger can loose its execution
15959  context and may display incorrect values.
15960 \layout Subsubsection*
15961
15962 quit
15963 \layout Standard
15964
15965 "Watch me now.
15966  Iam going Down.
15967  My name is Bobby Brown"
15968 \layout Section
15969
15970 Interfacing with XEmacs
15971 \begin_inset LatexCommand \index{XEmacs}
15972
15973 \end_inset
15974
15975
15976 \begin_inset LatexCommand \index{Emacs}
15977
15978 \end_inset
15979
15980 .
15981 \layout Standard
15982
15983 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
15984  sdcdb.el and sdcdbsrc.el.
15985  These two files can be found in the $(prefix)/bin directory after the installat
15986 ion is complete.
15987  These files need to be loaded into XEmacs for the interface to work.
15988  This can be done at XEmacs startup time by inserting the following into
15989  your '.xemacs' file (which can be found in your HOME directory):
15990 \newline
15991
15992 \newline
15993
15994 \family typewriter
15995 (load-file sdcdbsrc.el)
15996 \family default
15997
15998 \newline
15999
16000 \newline
16001 .xemacs is a lisp file so the () around the command is REQUIRED.
16002  The files can also be loaded dynamically while XEmacs is running, set the
16003  environment variable 'EMACSLOADPATH' to the installation bin directory
16004  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
16005  To start the interface enter the following command:
16006 \newline
16007
16008 \newline
16009
16010 \family sans
16011 \series bold
16012 ESC-x sdcdbsrc
16013 \family default
16014 \series default
16015
16016 \newline
16017
16018 \newline
16019 You will prompted to enter the file name to be debugged.
16020
16021 \newline
16022
16023 \newline
16024 The command line options that are passed to the simulator directly are bound
16025  to default values in the file sdcdbsrc.el.
16026  The variables are listed below, these values maybe changed as required.
16027 \layout Itemize
16028
16029 sdcdbsrc-cpu-type '51
16030 \layout Itemize
16031
16032 sdcdbsrc-frequency '11059200
16033 \layout Itemize
16034
16035 sdcdbsrc-serial nil
16036 \layout Standard
16037
16038 The following is a list of key mapping for the debugger interface.
16039 \layout Standard
16040
16041 \SpecialChar ~
16042
16043 \family typewriter
16044
16045 \newline
16046 ;; Current Listing ::
16047 \newline
16048 ;;key\SpecialChar ~
16049 \SpecialChar ~
16050 \SpecialChar ~
16051 \SpecialChar ~
16052 \SpecialChar ~
16053 \SpecialChar ~
16054 \SpecialChar ~
16055 \SpecialChar ~
16056 \SpecialChar ~
16057 \SpecialChar ~
16058 \SpecialChar ~
16059 \SpecialChar ~
16060 \SpecialChar ~
16061 \SpecialChar ~
16062 \SpecialChar ~
16063 binding\SpecialChar ~
16064 \SpecialChar ~
16065 \SpecialChar ~
16066 \SpecialChar ~
16067 \SpecialChar ~
16068 \SpecialChar ~
16069 \SpecialChar ~
16070 \SpecialChar ~
16071 \SpecialChar ~
16072 \SpecialChar ~
16073 \SpecialChar ~
16074 \SpecialChar ~
16075 \SpecialChar ~
16076 \SpecialChar ~
16077 \SpecialChar ~
16078 \SpecialChar ~
16079 \SpecialChar ~
16080 \SpecialChar ~
16081 \SpecialChar ~
16082 \SpecialChar ~
16083 \SpecialChar ~
16084 \SpecialChar ~
16085 Comment
16086 \newline
16087 ;;---\SpecialChar ~
16088 \SpecialChar ~
16089 \SpecialChar ~
16090 \SpecialChar ~
16091 \SpecialChar ~
16092 \SpecialChar ~
16093 \SpecialChar ~
16094 \SpecialChar ~
16095 \SpecialChar ~
16096 \SpecialChar ~
16097 \SpecialChar ~
16098 \SpecialChar ~
16099 \SpecialChar ~
16100 \SpecialChar ~
16101 \SpecialChar ~
16102 ------\SpecialChar ~
16103 \SpecialChar ~
16104 \SpecialChar ~
16105 \SpecialChar ~
16106 \SpecialChar ~
16107 \SpecialChar ~
16108 \SpecialChar ~
16109 \SpecialChar ~
16110 \SpecialChar ~
16111 \SpecialChar ~
16112 \SpecialChar ~
16113 \SpecialChar ~
16114 \SpecialChar ~
16115 \SpecialChar ~
16116 \SpecialChar ~
16117 \SpecialChar ~
16118 \SpecialChar ~
16119 \SpecialChar ~
16120 \SpecialChar ~
16121 \SpecialChar ~
16122 \SpecialChar ~
16123 \SpecialChar ~
16124 --------
16125 \newline
16126 ;;
16127 \newline
16128 ;; n\SpecialChar ~
16129 \SpecialChar ~
16130 \SpecialChar ~
16131 \SpecialChar ~
16132 \SpecialChar ~
16133 \SpecialChar ~
16134 \SpecialChar ~
16135 \SpecialChar ~
16136 \SpecialChar ~
16137 \SpecialChar ~
16138 \SpecialChar ~
16139 \SpecialChar ~
16140 \SpecialChar ~
16141 \SpecialChar ~
16142  sdcdb-next-from-src\SpecialChar ~
16143 \SpecialChar ~
16144 \SpecialChar ~
16145 \SpecialChar ~
16146 \SpecialChar ~
16147 \SpecialChar ~
16148 \SpecialChar ~
16149 \SpecialChar ~
16150 \SpecialChar ~
16151 \SpecialChar ~
16152 SDCDB next command
16153 \newline
16154 ;; b\SpecialChar ~
16155 \SpecialChar ~
16156 \SpecialChar ~
16157 \SpecialChar ~
16158 \SpecialChar ~
16159 \SpecialChar ~
16160 \SpecialChar ~
16161 \SpecialChar ~
16162 \SpecialChar ~
16163 \SpecialChar ~
16164 \SpecialChar ~
16165 \SpecialChar ~
16166 \SpecialChar ~
16167 \SpecialChar ~
16168  sdcdb-back-from-src\SpecialChar ~
16169 \SpecialChar ~
16170 \SpecialChar ~
16171 \SpecialChar ~
16172 \SpecialChar ~
16173 \SpecialChar ~
16174 \SpecialChar ~
16175 \SpecialChar ~
16176 \SpecialChar ~
16177 \SpecialChar ~
16178 SDCDB back command
16179 \newline
16180 ;; c\SpecialChar ~
16181 \SpecialChar ~
16182 \SpecialChar ~
16183 \SpecialChar ~
16184 \SpecialChar ~
16185 \SpecialChar ~
16186 \SpecialChar ~
16187 \SpecialChar ~
16188 \SpecialChar ~
16189 \SpecialChar ~
16190 \SpecialChar ~
16191 \SpecialChar ~
16192 \SpecialChar ~
16193 \SpecialChar ~
16194  sdcdb-cont-from-src\SpecialChar ~
16195 \SpecialChar ~
16196 \SpecialChar ~
16197 \SpecialChar ~
16198 \SpecialChar ~
16199 \SpecialChar ~
16200 \SpecialChar ~
16201 \SpecialChar ~
16202 \SpecialChar ~
16203 \SpecialChar ~
16204 SDCDB continue command
16205 \newline
16206 ;; s\SpecialChar ~
16207 \SpecialChar ~
16208 \SpecialChar ~
16209 \SpecialChar ~
16210 \SpecialChar ~
16211 \SpecialChar ~
16212 \SpecialChar ~
16213 \SpecialChar ~
16214 \SpecialChar ~
16215 \SpecialChar ~
16216 \SpecialChar ~
16217 \SpecialChar ~
16218 \SpecialChar ~
16219 \SpecialChar ~
16220  sdcdb-step-from-src\SpecialChar ~
16221 \SpecialChar ~
16222 \SpecialChar ~
16223 \SpecialChar ~
16224 \SpecialChar ~
16225 \SpecialChar ~
16226 \SpecialChar ~
16227 \SpecialChar ~
16228 \SpecialChar ~
16229 \SpecialChar ~
16230 SDCDB step command
16231 \newline
16232 ;; ?\SpecialChar ~
16233 \SpecialChar ~
16234 \SpecialChar ~
16235 \SpecialChar ~
16236 \SpecialChar ~
16237 \SpecialChar ~
16238 \SpecialChar ~
16239 \SpecialChar ~
16240 \SpecialChar ~
16241 \SpecialChar ~
16242 \SpecialChar ~
16243 \SpecialChar ~
16244 \SpecialChar ~
16245 \SpecialChar ~
16246  sdcdb-whatis-c-sexp\SpecialChar ~
16247 \SpecialChar ~
16248 \SpecialChar ~
16249 \SpecialChar ~
16250 \SpecialChar ~
16251 \SpecialChar ~
16252 \SpecialChar ~
16253 \SpecialChar ~
16254 \SpecialChar ~
16255 \SpecialChar ~
16256 SDCDB ptypecommand for data at
16257 \newline
16258 ;;\SpecialChar ~
16259 \SpecialChar ~
16260 \SpecialChar ~
16261 \SpecialChar ~
16262 \SpecialChar ~
16263 \SpecialChar ~
16264 \SpecialChar ~
16265 \SpecialChar ~
16266 \SpecialChar ~
16267 \SpecialChar ~
16268 \SpecialChar ~
16269 \SpecialChar ~
16270 \SpecialChar ~
16271 \SpecialChar ~
16272 \SpecialChar ~
16273 \SpecialChar ~
16274 \SpecialChar ~
16275 \SpecialChar ~
16276 \SpecialChar ~
16277 \SpecialChar ~
16278 \SpecialChar ~
16279 \SpecialChar ~
16280 \SpecialChar ~
16281 \SpecialChar ~
16282 \SpecialChar ~
16283 \SpecialChar ~
16284 \SpecialChar ~
16285 \SpecialChar ~
16286 \SpecialChar ~
16287 \SpecialChar ~
16288 \SpecialChar ~
16289 \SpecialChar ~
16290 \SpecialChar ~
16291 \SpecialChar ~
16292 \SpecialChar ~
16293 \SpecialChar ~
16294 \SpecialChar ~
16295 \SpecialChar ~
16296 \SpecialChar ~
16297 \SpecialChar ~
16298 \SpecialChar ~
16299 \SpecialChar ~
16300 \SpecialChar ~
16301 \SpecialChar ~
16302 \SpecialChar ~
16303 \SpecialChar ~
16304  buffer point
16305 \newline
16306 ;; x\SpecialChar ~
16307 \SpecialChar ~
16308 \SpecialChar ~
16309 \SpecialChar ~
16310 \SpecialChar ~
16311 \SpecialChar ~
16312 \SpecialChar ~
16313 \SpecialChar ~
16314 \SpecialChar ~
16315 \SpecialChar ~
16316 \SpecialChar ~
16317 \SpecialChar ~
16318 \SpecialChar ~
16319 \SpecialChar ~
16320  sdcdbsrc-delete\SpecialChar ~
16321 \SpecialChar ~
16322 \SpecialChar ~
16323 \SpecialChar ~
16324 \SpecialChar ~
16325 \SpecialChar ~
16326 \SpecialChar ~
16327 \SpecialChar ~
16328 \SpecialChar ~
16329 \SpecialChar ~
16330 \SpecialChar ~
16331 \SpecialChar ~
16332 \SpecialChar ~
16333 \SpecialChar ~
16334 SDCDB Delete all breakpoints if no arg
16335 \newline
16336 ;;\SpecialChar ~
16337 \SpecialChar ~
16338 \SpecialChar ~
16339 \SpecialChar ~
16340 \SpecialChar ~
16341 \SpecialChar ~
16342 \SpecialChar ~
16343 \SpecialChar ~
16344 \SpecialChar ~
16345 \SpecialChar ~
16346 \SpecialChar ~
16347 \SpecialChar ~
16348 \SpecialChar ~
16349 \SpecialChar ~
16350 \SpecialChar ~
16351 \SpecialChar ~
16352 \SpecialChar ~
16353 \SpecialChar ~
16354 \SpecialChar ~
16355 \SpecialChar ~
16356 \SpecialChar ~
16357 \SpecialChar ~
16358 \SpecialChar ~
16359 \SpecialChar ~
16360 \SpecialChar ~
16361 \SpecialChar ~
16362 \SpecialChar ~
16363 \SpecialChar ~
16364 \SpecialChar ~
16365 \SpecialChar ~
16366 \SpecialChar ~
16367 \SpecialChar ~
16368 \SpecialChar ~
16369 \SpecialChar ~
16370 \SpecialChar ~
16371 \SpecialChar ~
16372 \SpecialChar ~
16373 \SpecialChar ~
16374 \SpecialChar ~
16375 \SpecialChar ~
16376 \SpecialChar ~
16377 \SpecialChar ~
16378 \SpecialChar ~
16379 \SpecialChar ~
16380 \SpecialChar ~
16381 \SpecialChar ~
16382 given or delete arg (C-u arg x)
16383 \newline
16384 ;; m\SpecialChar ~
16385 \SpecialChar ~
16386 \SpecialChar ~
16387 \SpecialChar ~
16388 \SpecialChar ~
16389 \SpecialChar ~
16390 \SpecialChar ~
16391 \SpecialChar ~
16392 \SpecialChar ~
16393 \SpecialChar ~
16394 \SpecialChar ~
16395 \SpecialChar ~
16396 \SpecialChar ~
16397 \SpecialChar ~
16398  sdcdbsrc-frame\SpecialChar ~
16399 \SpecialChar ~
16400 \SpecialChar ~
16401 \SpecialChar ~
16402 \SpecialChar ~
16403 \SpecialChar ~
16404 \SpecialChar ~
16405 \SpecialChar ~
16406 \SpecialChar ~
16407 \SpecialChar ~
16408 \SpecialChar ~
16409 \SpecialChar ~
16410 \SpecialChar ~
16411 \SpecialChar ~
16412 \SpecialChar ~
16413 SDCDB Display current frame if no arg,
16414 \newline
16415 ;;\SpecialChar ~
16416 \SpecialChar ~
16417 \SpecialChar ~
16418 \SpecialChar ~
16419 \SpecialChar ~
16420 \SpecialChar ~
16421 \SpecialChar ~
16422 \SpecialChar ~
16423 \SpecialChar ~
16424 \SpecialChar ~
16425 \SpecialChar ~
16426 \SpecialChar ~
16427 \SpecialChar ~
16428 \SpecialChar ~
16429 \SpecialChar ~
16430 \SpecialChar ~
16431 \SpecialChar ~
16432 \SpecialChar ~
16433 \SpecialChar ~
16434 \SpecialChar ~
16435 \SpecialChar ~
16436 \SpecialChar ~
16437 \SpecialChar ~
16438 \SpecialChar ~
16439 \SpecialChar ~
16440 \SpecialChar ~
16441 \SpecialChar ~
16442 \SpecialChar ~
16443 \SpecialChar ~
16444 \SpecialChar ~
16445 \SpecialChar ~
16446 \SpecialChar ~
16447 \SpecialChar ~
16448 \SpecialChar ~
16449 \SpecialChar ~
16450 \SpecialChar ~
16451 \SpecialChar ~
16452 \SpecialChar ~
16453 \SpecialChar ~
16454 \SpecialChar ~
16455 \SpecialChar ~
16456 \SpecialChar ~
16457 \SpecialChar ~
16458 \SpecialChar ~
16459 \SpecialChar ~
16460 \SpecialChar ~
16461 \SpecialChar ~
16462 given or display frame arg
16463 \newline
16464 ;;\SpecialChar ~
16465 \SpecialChar ~
16466 \SpecialChar ~
16467 \SpecialChar ~
16468 \SpecialChar ~
16469 \SpecialChar ~
16470 \SpecialChar ~
16471 \SpecialChar ~
16472 \SpecialChar ~
16473 \SpecialChar ~
16474 \SpecialChar ~
16475 \SpecialChar ~
16476 \SpecialChar ~
16477 \SpecialChar ~
16478 \SpecialChar ~
16479 \SpecialChar ~
16480 \SpecialChar ~
16481 \SpecialChar ~
16482 \SpecialChar ~
16483 \SpecialChar ~
16484 \SpecialChar ~
16485 \SpecialChar ~
16486 \SpecialChar ~
16487 \SpecialChar ~
16488 \SpecialChar ~
16489 \SpecialChar ~
16490 \SpecialChar ~
16491 \SpecialChar ~
16492 \SpecialChar ~
16493 \SpecialChar ~
16494 \SpecialChar ~
16495 \SpecialChar ~
16496 \SpecialChar ~
16497 \SpecialChar ~
16498 \SpecialChar ~
16499 \SpecialChar ~
16500 \SpecialChar ~
16501 \SpecialChar ~
16502 \SpecialChar ~
16503 \SpecialChar ~
16504 \SpecialChar ~
16505 \SpecialChar ~
16506 \SpecialChar ~
16507 \SpecialChar ~
16508 \SpecialChar ~
16509 \SpecialChar ~
16510 \SpecialChar ~
16511 buffer point
16512 \newline
16513 ;; !\SpecialChar ~
16514 \SpecialChar ~
16515 \SpecialChar ~
16516 \SpecialChar ~
16517 \SpecialChar ~
16518 \SpecialChar ~
16519 \SpecialChar ~
16520 \SpecialChar ~
16521 \SpecialChar ~
16522 \SpecialChar ~
16523 \SpecialChar ~
16524 \SpecialChar ~
16525 \SpecialChar ~
16526 \SpecialChar ~
16527  sdcdbsrc-goto-sdcdb\SpecialChar ~
16528 \SpecialChar ~
16529 \SpecialChar ~
16530 \SpecialChar ~
16531 \SpecialChar ~
16532 \SpecialChar ~
16533 \SpecialChar ~
16534 \SpecialChar ~
16535 \SpecialChar ~
16536 \SpecialChar ~
16537 Goto the SDCDB output buffer
16538 \newline
16539 ;; p\SpecialChar ~
16540 \SpecialChar ~
16541 \SpecialChar ~
16542 \SpecialChar ~
16543 \SpecialChar ~
16544 \SpecialChar ~
16545 \SpecialChar ~
16546 \SpecialChar ~
16547 \SpecialChar ~
16548 \SpecialChar ~
16549 \SpecialChar ~
16550 \SpecialChar ~
16551 \SpecialChar ~
16552 \SpecialChar ~
16553  sdcdb-print-c-sexp\SpecialChar ~
16554 \SpecialChar ~
16555 \SpecialChar ~
16556 \SpecialChar ~
16557 \SpecialChar ~
16558 \SpecialChar ~
16559 \SpecialChar ~
16560 \SpecialChar ~
16561 \SpecialChar ~
16562 \SpecialChar ~
16563 \SpecialChar ~
16564 SDCDB print command for data at
16565 \newline
16566 ;;\SpecialChar ~
16567 \SpecialChar ~
16568 \SpecialChar ~
16569 \SpecialChar ~
16570 \SpecialChar ~
16571 \SpecialChar ~
16572 \SpecialChar ~
16573 \SpecialChar ~
16574 \SpecialChar ~
16575 \SpecialChar ~
16576 \SpecialChar ~
16577 \SpecialChar ~
16578 \SpecialChar ~
16579 \SpecialChar ~
16580 \SpecialChar ~
16581 \SpecialChar ~
16582 \SpecialChar ~
16583 \SpecialChar ~
16584 \SpecialChar ~
16585 \SpecialChar ~
16586 \SpecialChar ~
16587 \SpecialChar ~
16588 \SpecialChar ~
16589 \SpecialChar ~
16590 \SpecialChar ~
16591 \SpecialChar ~
16592 \SpecialChar ~
16593 \SpecialChar ~
16594 \SpecialChar ~
16595 \SpecialChar ~
16596 \SpecialChar ~
16597 \SpecialChar ~
16598 \SpecialChar ~
16599 \SpecialChar ~
16600 \SpecialChar ~
16601 \SpecialChar ~
16602 \SpecialChar ~
16603 \SpecialChar ~
16604 \SpecialChar ~
16605 \SpecialChar ~
16606 \SpecialChar ~
16607 \SpecialChar ~
16608 \SpecialChar ~
16609 \SpecialChar ~
16610 \SpecialChar ~
16611 \SpecialChar ~
16612  buffer point
16613 \newline
16614 ;; g\SpecialChar ~
16615 \SpecialChar ~
16616 \SpecialChar ~
16617 \SpecialChar ~
16618 \SpecialChar ~
16619 \SpecialChar ~
16620 \SpecialChar ~
16621 \SpecialChar ~
16622 \SpecialChar ~
16623 \SpecialChar ~
16624 \SpecialChar ~
16625 \SpecialChar ~
16626 \SpecialChar ~
16627 \SpecialChar ~
16628  sdcdbsrc-goto-sdcdb\SpecialChar ~
16629 \SpecialChar ~
16630 \SpecialChar ~
16631 \SpecialChar ~
16632 \SpecialChar ~
16633 \SpecialChar ~
16634 \SpecialChar ~
16635 \SpecialChar ~
16636 \SpecialChar ~
16637 \SpecialChar ~
16638 Goto the SDCDB output buffer
16639 \newline
16640 ;; t\SpecialChar ~
16641 \SpecialChar ~
16642 \SpecialChar ~
16643 \SpecialChar ~
16644 \SpecialChar ~
16645 \SpecialChar ~
16646 \SpecialChar ~
16647 \SpecialChar ~
16648 \SpecialChar ~
16649 \SpecialChar ~
16650 \SpecialChar ~
16651 \SpecialChar ~
16652 \SpecialChar ~
16653 \SpecialChar ~
16654  sdcdbsrc-mode\SpecialChar ~
16655 \SpecialChar ~
16656 \SpecialChar ~
16657 \SpecialChar ~
16658 \SpecialChar ~
16659 \SpecialChar ~
16660 \SpecialChar ~
16661 \SpecialChar ~
16662 \SpecialChar ~
16663 \SpecialChar ~
16664 \SpecialChar ~
16665 \SpecialChar ~
16666 \SpecialChar ~
16667 \SpecialChar ~
16668 \SpecialChar ~
16669 \SpecialChar ~
16670 Toggles Sdcdbsrc mode (turns it off)
16671 \newline
16672 ;;
16673 \newline
16674 ;; C-c C-f\SpecialChar ~
16675 \SpecialChar ~
16676 \SpecialChar ~
16677 \SpecialChar ~
16678 \SpecialChar ~
16679 \SpecialChar ~
16680 \SpecialChar ~
16681 \SpecialChar ~
16682  sdcdb-finish-from-src\SpecialChar ~
16683 \SpecialChar ~
16684 \SpecialChar ~
16685 \SpecialChar ~
16686 \SpecialChar ~
16687 \SpecialChar ~
16688 \SpecialChar ~
16689 \SpecialChar ~
16690 SDCDB finish command
16691 \newline
16692 ;;
16693 \newline
16694 ;; C-x SPC\SpecialChar ~
16695 \SpecialChar ~
16696 \SpecialChar ~
16697 \SpecialChar ~
16698 \SpecialChar ~
16699 \SpecialChar ~
16700 \SpecialChar ~
16701 \SpecialChar ~
16702  sdcdb-break\SpecialChar ~
16703 \SpecialChar ~
16704 \SpecialChar ~
16705 \SpecialChar ~
16706 \SpecialChar ~
16707 \SpecialChar ~
16708 \SpecialChar ~
16709 \SpecialChar ~
16710 \SpecialChar ~
16711 \SpecialChar ~
16712 \SpecialChar ~
16713 \SpecialChar ~
16714 \SpecialChar ~
16715 \SpecialChar ~
16716 \SpecialChar ~
16717 \SpecialChar ~
16718 \SpecialChar ~
16719 \SpecialChar ~
16720 Set break for line with point
16721 \newline
16722 ;; ESC t\SpecialChar ~
16723 \SpecialChar ~
16724 \SpecialChar ~
16725 \SpecialChar ~
16726 \SpecialChar ~
16727 \SpecialChar ~
16728 \SpecialChar ~
16729 \SpecialChar ~
16730 \SpecialChar ~
16731 \SpecialChar ~
16732  sdcdbsrc-mode\SpecialChar ~
16733 \SpecialChar ~
16734 \SpecialChar ~
16735 \SpecialChar ~
16736 \SpecialChar ~
16737 \SpecialChar ~
16738 \SpecialChar ~
16739 \SpecialChar ~
16740 \SpecialChar ~
16741 \SpecialChar ~
16742 \SpecialChar ~
16743 \SpecialChar ~
16744 \SpecialChar ~
16745 \SpecialChar ~
16746 \SpecialChar ~
16747 \SpecialChar ~
16748 Toggle Sdcdbsrc mode
16749 \newline
16750 ;; ESC m\SpecialChar ~
16751 \SpecialChar ~
16752 \SpecialChar ~
16753 \SpecialChar ~
16754 \SpecialChar ~
16755 \SpecialChar ~
16756 \SpecialChar ~
16757 \SpecialChar ~
16758 \SpecialChar ~
16759 \SpecialChar ~
16760  sdcdbsrc-srcmode\SpecialChar ~
16761 \SpecialChar ~
16762 \SpecialChar ~
16763 \SpecialChar ~
16764 \SpecialChar ~
16765 \SpecialChar ~
16766 \SpecialChar ~
16767 \SpecialChar ~
16768 \SpecialChar ~
16769 \SpecialChar ~
16770 \SpecialChar ~
16771 \SpecialChar ~
16772  Toggle list mode
16773 \newline
16774 ;;
16775 \newline
16776
16777 \layout Chapter
16778 \pagebreak_top
16779 TIPS
16780 \layout Standard
16781
16782 Here are a few guidelines that will help the compiler generate more efficient
16783  code, some of the tips are specific to this compiler others are generally
16784  good programming practice.
16785 \layout Itemize
16786
16787 Use the smallest data type to represent your data-value.
16788  If it is known in advance that the value is going to be less than 256 then
16789  use an 'unsigned char' instead of a 'short' or 'int'.
16790  Please note, that ANSI C requires both signed and unsigned chars to be
16791  promoted to 'signed int' before doing any operation.
16792  This promotion can be omitted, if the result is the same.
16793  The effect of the promotion rules together with the sign-extension is often
16794  supprising:
16795 \begin_deeper
16796 \layout Verse
16797
16798
16799 \family typewriter
16800 unsigned char uc = 0xfe;
16801 \newline
16802 if (uc * uc < 0) /* this is true! */
16803 \newline
16804 {
16805 \newline
16806 \SpecialChar ~
16807 \SpecialChar ~
16808 \SpecialChar ~
16809 \SpecialChar ~
16810 ....
16811 \newline
16812 }
16813 \layout Standard
16814
16815
16816 \family typewriter
16817 uc * uc
16818 \family default
16819  is evaluated as
16820 \family typewriter
16821 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
16822 \family default
16823 .
16824
16825 \newline
16826 Another one:
16827 \layout Verse
16828
16829
16830 \family typewriter
16831 (unsigned char) -12 / (signed char) -3 = ...
16832 \layout Standard
16833
16834 No, the result is not 4:
16835 \layout Verse
16836
16837
16838 \family typewriter
16839 (int) (unsigned char) -12 / (int) (signed char) -3 =
16840 \newline
16841 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
16842 \newline
16843 (int) 0x00f4 / (int) 0xfffd =
16844 \newline
16845 (int) 0x00f4 / (int) 0xfffd =
16846 \newline
16847 (int) 244 / (int) -3 =
16848 \newline
16849 (int) -81 = (int) 0xffaf;
16850 \layout Standard
16851
16852 Don't complain, that gcc gives you a different result.
16853  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
16854  Therefore the results are different.
16855 \newline
16856 From
16857 \begin_inset Quotes sld
16858 \end_inset
16859
16860 comp.lang.c FAQ
16861 \begin_inset Quotes srd
16862 \end_inset
16863
16864 :
16865 \layout Quote
16866
16867 If well-defined overflow characteristics are important and negative values
16868  are not, or if you want to steer clear of sign-extension problems when
16869  manipulating bits or bytes, use one of the corresponding unsigned types.
16870  (Beware when mixing signed and unsigned values in expressions, though.)
16871 \newline
16872 Although character types (especially unsigned char) can be used as "tiny"
16873  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
16874 ble sign extension and increased code size.
16875 \end_deeper
16876 \layout Itemize
16877
16878 Use unsigned when it is known in advance that the value is not going to
16879  be negative.
16880  This helps especially if you are doing division or multiplication, bit-shifting
16881  or are using an array index.
16882 \layout Itemize
16883
16884 NEVER jump into a LOOP.
16885 \layout Itemize
16886
16887 Declare the variables to be local
16888 \begin_inset LatexCommand \index{local variables}
16889
16890 \end_inset
16891
16892  whenever possible, especially loop control variables (induction).
16893 \layout Itemize
16894
16895 Since the compiler does not always do implicit integral promotion, the programme
16896 r should do an explicit cast when integral promotion is required.
16897 \layout Itemize
16898
16899 Reducing the size of division, multiplication & modulus operations can reduce
16900  code size substantially.
16901  Take the following code for example.
16902 \begin_deeper
16903 \layout Verse
16904
16905
16906 \family typewriter
16907 foobar(unsigned int p1, unsigned char ch)
16908 \newline
16909 {
16910 \newline
16911 \SpecialChar ~
16912 \SpecialChar ~
16913 \SpecialChar ~
16914 \SpecialChar ~
16915 unsigned char ch1 = p1 % ch ;
16916 \newline
16917 \SpecialChar ~
16918 \SpecialChar ~
16919 \SpecialChar ~
16920 \SpecialChar ~
16921 ....
16922 \newline
16923 }
16924 \layout Standard
16925
16926 For the modulus operation the variable ch will be promoted to unsigned int
16927  first then the modulus operation will be performed (this will lead to a
16928  call to support routine _moduint()), and the result will be casted to a
16929  char.
16930  If the code is changed to
16931 \layout Verse
16932
16933
16934 \family typewriter
16935 foobar(unsigned int p1, unsigned char ch)
16936 \newline
16937 {
16938 \newline
16939 \SpecialChar ~
16940 \SpecialChar ~
16941 \SpecialChar ~
16942 \SpecialChar ~
16943 unsigned char ch1 = (unsigned char)p1 % ch ;
16944 \newline
16945 \SpecialChar ~
16946 \SpecialChar ~
16947 \SpecialChar ~
16948 \SpecialChar ~
16949 ....
16950 \newline
16951 }
16952 \layout Standard
16953
16954 It would substantially reduce the code generated (future versions of the
16955  compiler will be smart enough to detect such optimization opportunities).
16956 \end_deeper
16957 \layout Itemize
16958
16959 Have a look at the assembly listing to get a
16960 \begin_inset Quotes sld
16961 \end_inset
16962
16963 feeling
16964 \begin_inset Quotes srd
16965 \end_inset
16966
16967  for the code generation.
16968 \layout Section
16969
16970 Tools
16971 \begin_inset LatexCommand \index{Tools}
16972
16973 \end_inset
16974
16975  included in the distribution
16976 \layout Standard
16977 \align center
16978
16979 \begin_inset  Tabular
16980 <lyxtabular version="3" rows="12" columns="3">
16981 <features>
16982 <column alignment="center" valignment="top" leftline="true" width="0pt">
16983 <column alignment="center" valignment="top" leftline="true" width="0pt">
16984 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
16985 <row topline="true" bottomline="true">
16986 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16987 \begin_inset Text
16988
16989 \layout Standard
16990
16991 Name
16992 \end_inset
16993 </cell>
16994 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16995 \begin_inset Text
16996
16997 \layout Standard
16998
16999 Purpose
17000 \end_inset
17001 </cell>
17002 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17003 \begin_inset Text
17004
17005 \layout Standard
17006
17007 Directory
17008 \end_inset
17009 </cell>
17010 </row>
17011 <row topline="true">
17012 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17013 \begin_inset Text
17014
17015 \layout Standard
17016
17017 uCsim
17018 \end_inset
17019 </cell>
17020 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17021 \begin_inset Text
17022
17023 \layout Standard
17024
17025 Simulator for various architectures
17026 \end_inset
17027 </cell>
17028 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17029 \begin_inset Text
17030
17031 \layout Standard
17032
17033 sdcc/sim/ucsim
17034 \end_inset
17035 </cell>
17036 </row>
17037 <row topline="true">
17038 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17039 \begin_inset Text
17040
17041 \layout Standard
17042
17043 keil2sdcc.pl
17044 \end_inset
17045 </cell>
17046 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17047 \begin_inset Text
17048
17049 \layout Standard
17050
17051 header file conversion
17052 \end_inset
17053 </cell>
17054 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17055 \begin_inset Text
17056
17057 \layout Standard
17058
17059 sdcc/support/scripts
17060 \end_inset
17061 </cell>
17062 </row>
17063 <row topline="true">
17064 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17065 \begin_inset Text
17066
17067 \layout Standard
17068
17069 mh2h.c
17070 \end_inset
17071 </cell>
17072 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17073 \begin_inset Text
17074
17075 \layout Standard
17076
17077 header file conversion
17078 \end_inset
17079 </cell>
17080 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17081 \begin_inset Text
17082
17083 \layout Standard
17084
17085 sdcc/support/scripts
17086 \end_inset
17087 </cell>
17088 </row>
17089 <row topline="true">
17090 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17091 \begin_inset Text
17092
17093 \layout Standard
17094
17095 as-gbz80
17096 \end_inset
17097 </cell>
17098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17099 \begin_inset Text
17100
17101 \layout Standard
17102
17103 Assembler
17104 \end_inset
17105 </cell>
17106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17107 \begin_inset Text
17108
17109 \layout Standard
17110
17111
17112 \family roman
17113 \series medium
17114 \shape up
17115 \size normal
17116 \emph off
17117 \bar no
17118 \noun off
17119 \color none
17120 sdcc/bin
17121 \end_inset
17122 </cell>
17123 </row>
17124 <row topline="true">
17125 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17126 \begin_inset Text
17127
17128 \layout Standard
17129
17130 as-z80
17131 \end_inset
17132 </cell>
17133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17134 \begin_inset Text
17135
17136 \layout Standard
17137
17138 Assembler
17139 \end_inset
17140 </cell>
17141 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17142 \begin_inset Text
17143
17144 \layout Standard
17145
17146
17147 \family roman
17148 \series medium
17149 \shape up
17150 \size normal
17151 \emph off
17152 \bar no
17153 \noun off
17154 \color none
17155 sdcc/bin
17156 \end_inset
17157 </cell>
17158 </row>
17159 <row topline="true">
17160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17161 \begin_inset Text
17162
17163 \layout Standard
17164
17165 asx8051
17166 \end_inset
17167 </cell>
17168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17169 \begin_inset Text
17170
17171 \layout Standard
17172
17173 Assembler
17174 \end_inset
17175 </cell>
17176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17177 \begin_inset Text
17178
17179 \layout Standard
17180
17181
17182 \family roman
17183 \series medium
17184 \shape up
17185 \size normal
17186 \emph off
17187 \bar no
17188 \noun off
17189 \color none
17190 sdcc/bin
17191 \end_inset
17192 </cell>
17193 </row>
17194 <row topline="true">
17195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17196 \begin_inset Text
17197
17198 \layout Standard
17199
17200 sdcdb
17201 \end_inset
17202 </cell>
17203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17204 \begin_inset Text
17205
17206 \layout Standard
17207
17208 Simulator
17209 \end_inset
17210 </cell>
17211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17212 \begin_inset Text
17213
17214 \layout Standard
17215
17216
17217 \family roman
17218 \series medium
17219 \shape up
17220 \size normal
17221 \emph off
17222 \bar no
17223 \noun off
17224 \color none
17225 sdcc/bin
17226 \end_inset
17227 </cell>
17228 </row>
17229 <row topline="true">
17230 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17231 \begin_inset Text
17232
17233 \layout Standard
17234
17235 aslink
17236 \end_inset
17237 </cell>
17238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17239 \begin_inset Text
17240
17241 \layout Standard
17242
17243 Linker
17244 \end_inset
17245 </cell>
17246 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17247 \begin_inset Text
17248
17249 \layout Standard
17250
17251
17252 \family roman
17253 \series medium
17254 \shape up
17255 \size normal
17256 \emph off
17257 \bar no
17258 \noun off
17259 \color none
17260 sdcc/bin
17261 \end_inset
17262 </cell>
17263 </row>
17264 <row topline="true">
17265 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17266 \begin_inset Text
17267
17268 \layout Standard
17269
17270 link-z80
17271 \end_inset
17272 </cell>
17273 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17274 \begin_inset Text
17275
17276 \layout Standard
17277
17278 Linker
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
17287 \family roman
17288 \series medium
17289 \shape up
17290 \size normal
17291 \emph off
17292 \bar no
17293 \noun off
17294 \color none
17295 sdcc/bin
17296 \end_inset
17297 </cell>
17298 </row>
17299 <row topline="true">
17300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17301 \begin_inset Text
17302
17303 \layout Standard
17304
17305 link-gbz80
17306 \end_inset
17307 </cell>
17308 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17309 \begin_inset Text
17310
17311 \layout Standard
17312
17313 Linker
17314 \end_inset
17315 </cell>
17316 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17317 \begin_inset Text
17318
17319 \layout Standard
17320
17321
17322 \family roman
17323 \series medium
17324 \shape up
17325 \size normal
17326 \emph off
17327 \bar no
17328 \noun off
17329 \color none
17330 sdcc/bin
17331 \end_inset
17332 </cell>
17333 </row>
17334 <row topline="true" bottomline="true">
17335 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17336 \begin_inset Text
17337
17338 \layout Standard
17339
17340 packihx
17341 \end_inset
17342 </cell>
17343 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17344 \begin_inset Text
17345
17346 \layout Standard
17347
17348 ihx packer
17349 \end_inset
17350 </cell>
17351 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17352 \begin_inset Text
17353
17354 \layout Standard
17355
17356
17357 \family roman
17358 \series medium
17359 \shape up
17360 \size normal
17361 \emph off
17362 \bar no
17363 \noun off
17364 \color none
17365 sdcc/bin
17366 \end_inset
17367 </cell>
17368 </row>
17369 </lyxtabular>
17370
17371 \end_inset
17372
17373
17374 \newline
17375
17376 \layout Section
17377
17378 Documentation
17379 \begin_inset LatexCommand \index{Documentation}
17380
17381 \end_inset
17382
17383  included in the distribution
17384 \layout Standard
17385 \align center
17386
17387 \begin_inset  Tabular
17388 <lyxtabular version="3" rows="10" columns="2">
17389 <features>
17390 <column alignment="left" valignment="top" leftline="true" width="0(null)">
17391 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
17392 <row topline="true" bottomline="true">
17393 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17394 \begin_inset Text
17395
17396 \layout Standard
17397
17398 Subject / Title
17399 \end_inset
17400 </cell>
17401 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17402 \begin_inset Text
17403
17404 \layout Standard
17405
17406 Where to get / filename
17407 \end_inset
17408 </cell>
17409 </row>
17410 <row topline="true">
17411 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17412 \begin_inset Text
17413
17414 \layout Standard
17415
17416 SDCC Compiler User Guide
17417 \end_inset
17418 </cell>
17419 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17420 \begin_inset Text
17421
17422 \layout Standard
17423
17424 You're reading it right now
17425 \end_inset
17426 </cell>
17427 </row>
17428 <row topline="true">
17429 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17430 \begin_inset Text
17431
17432 \layout Standard
17433
17434 Changelog of SDCC
17435 \end_inset
17436 </cell>
17437 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17438 \begin_inset Text
17439
17440 \layout Standard
17441
17442 sdcc/Changelog
17443 \end_inset
17444 </cell>
17445 </row>
17446 <row topline="true">
17447 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17448 \begin_inset Text
17449
17450 \layout Standard
17451
17452 ASXXXX Assemblers and ASLINK Relocating Linker
17453 \end_inset
17454 </cell>
17455 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17456 \begin_inset Text
17457
17458 \layout Standard
17459
17460 sdcc/as/doc/asxhtm.html
17461 \end_inset
17462 </cell>
17463 </row>
17464 <row topline="true">
17465 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17466 \begin_inset Text
17467
17468 \layout Standard
17469
17470 SDCC regression test
17471 \begin_inset LatexCommand \index{Regression test}
17472
17473 \end_inset
17474
17475
17476 \end_inset
17477 </cell>
17478 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17479 \begin_inset Text
17480
17481 \layout Standard
17482
17483 sdcc/doc/test_suite_spec.pdf
17484 \end_inset
17485 </cell>
17486 </row>
17487 <row topline="true">
17488 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17489 \begin_inset Text
17490
17491 \layout Standard
17492
17493 Various notes
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 sdcc/doc/*
17502 \end_inset
17503 </cell>
17504 </row>
17505 <row topline="true">
17506 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17507 \begin_inset Text
17508
17509 \layout Standard
17510
17511 Notes on debugging with sdcdb
17512 \begin_inset LatexCommand \index{sdcdb (debugger)}
17513
17514 \end_inset
17515
17516
17517 \end_inset
17518 </cell>
17519 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17520 \begin_inset Text
17521
17522 \layout Standard
17523
17524 sdcc/debugger/README
17525 \end_inset
17526 </cell>
17527 </row>
17528 <row topline="true">
17529 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17530 \begin_inset Text
17531
17532 \layout Standard
17533
17534 Software simulator for microcontrollers
17535 \end_inset
17536 </cell>
17537 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17538 \begin_inset Text
17539
17540 \layout Standard
17541
17542
17543 \family roman
17544 \series medium
17545 \shape up
17546 \size normal
17547 \emph off
17548 \bar no
17549 \noun off
17550 \color none
17551 sdcc/sim/ucsim/doc
17552 \family default
17553 \series default
17554 \shape default
17555 \size default
17556 \emph default
17557 \bar default
17558 \noun default
17559 \color default
17560 /index.html
17561 \end_inset
17562 </cell>
17563 </row>
17564 <row topline="true">
17565 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17566 \begin_inset Text
17567
17568 \layout Standard
17569
17570 Temporary notes on the pic16
17571 \begin_inset LatexCommand \index{PIC16}
17572
17573 \end_inset
17574
17575  port
17576 \end_inset
17577 </cell>
17578 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17579 \begin_inset Text
17580
17581 \layout Standard
17582
17583 sdcc/src/pic16/NOTES
17584 \end_inset
17585 </cell>
17586 </row>
17587 <row topline="true" bottomline="true">
17588 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17589 \begin_inset Text
17590
17591 \layout Standard
17592
17593 SDCC internal documentation (debugging file format)
17594 \end_inset
17595 </cell>
17596 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17597 \begin_inset Text
17598
17599 \layout Standard
17600
17601 sdcc/doc/
17602 \family roman
17603 \series medium
17604 \shape up
17605 \size normal
17606 \emph off
17607 \bar no
17608 \noun off
17609 \color none
17610 cdbfileformat.pd
17611 \family default
17612 \series default
17613 \shape default
17614 \size default
17615 \emph default
17616 \bar default
17617 \noun default
17618 \color default
17619 f
17620 \end_inset
17621 </cell>
17622 </row>
17623 </lyxtabular>
17624
17625 \end_inset
17626
17627
17628 \newline
17629
17630 \layout Section
17631
17632 Related open source tools
17633 \begin_inset LatexCommand \index{Related tools}
17634
17635 \end_inset
17636
17637
17638 \layout Standard
17639 \align center
17640
17641 \begin_inset  Tabular
17642 <lyxtabular version="3" rows="11" columns="3">
17643 <features>
17644 <column alignment="center" valignment="top" leftline="true" width="0pt">
17645 <column alignment="block" valignment="top" leftline="true" width="30line%">
17646 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
17647 <row topline="true" bottomline="true">
17648 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17649 \begin_inset Text
17650
17651 \layout Standard
17652
17653 Name
17654 \end_inset
17655 </cell>
17656 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17657 \begin_inset Text
17658
17659 \layout Standard
17660
17661 Purpose
17662 \end_inset
17663 </cell>
17664 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17665 \begin_inset Text
17666
17667 \layout Standard
17668
17669 Where to get
17670 \end_inset
17671 </cell>
17672 </row>
17673 <row topline="true">
17674 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17675 \begin_inset Text
17676
17677 \layout Standard
17678
17679 gpsim
17680 \begin_inset LatexCommand \index{gpsim (pic simulator)}
17681
17682 \end_inset
17683
17684
17685 \end_inset
17686 </cell>
17687 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17688 \begin_inset Text
17689
17690 \layout Standard
17691
17692 PIC simulator
17693 \end_inset
17694 </cell>
17695 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17696 \begin_inset Text
17697
17698 \layout Standard
17699
17700
17701 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
17702
17703 \end_inset
17704
17705
17706 \end_inset
17707 </cell>
17708 </row>
17709 <row topline="true">
17710 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17711 \begin_inset Text
17712
17713 \layout Standard
17714
17715 gputils
17716 \begin_inset LatexCommand \index{gputils (pic tools)}
17717
17718 \end_inset
17719
17720
17721 \end_inset
17722 </cell>
17723 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17724 \begin_inset Text
17725
17726 \layout Standard
17727
17728 GNU PIC utilities
17729 \end_inset
17730 </cell>
17731 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17732 \begin_inset Text
17733
17734 \layout Standard
17735
17736
17737 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
17738
17739 \end_inset
17740
17741
17742 \end_inset
17743 </cell>
17744 </row>
17745 <row topline="true">
17746 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17747 \begin_inset Text
17748
17749 \layout Standard
17750
17751 flP5
17752 \end_inset
17753 </cell>
17754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17755 \begin_inset Text
17756
17757 \layout Standard
17758
17759 PIC programmer
17760 \end_inset
17761 </cell>
17762 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17763 \begin_inset Text
17764
17765 \layout Standard
17766
17767
17768 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
17769
17770 \end_inset
17771
17772
17773 \end_inset
17774 </cell>
17775 </row>
17776 <row topline="true">
17777 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17778 \begin_inset Text
17779
17780 \layout Standard
17781
17782 indent
17783 \begin_inset LatexCommand \index{indent (source formatting tool)}
17784
17785 \end_inset
17786
17787
17788 \end_inset
17789 </cell>
17790 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17791 \begin_inset Text
17792
17793 \layout Standard
17794
17795 Formats C source - Master of the white spaces
17796 \end_inset
17797 </cell>
17798 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17799 \begin_inset Text
17800
17801 \layout Standard
17802
17803
17804 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
17805
17806 \end_inset
17807
17808
17809 \end_inset
17810 </cell>
17811 </row>
17812 <row topline="true">
17813 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17814 \begin_inset Text
17815
17816 \layout Standard
17817
17818 srecord
17819 \begin_inset LatexCommand \index{srecord (tool)}
17820
17821 \end_inset
17822
17823
17824 \end_inset
17825 </cell>
17826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17827 \begin_inset Text
17828
17829 \layout Standard
17830
17831 Object file conversion, checksumming, ...
17832 \end_inset
17833 </cell>
17834 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17835 \begin_inset Text
17836
17837 \layout Standard
17838
17839
17840 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
17841
17842 \end_inset
17843
17844
17845 \end_inset
17846 </cell>
17847 </row>
17848 <row topline="true">
17849 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17850 \begin_inset Text
17851
17852 \layout Standard
17853
17854 objdump
17855 \begin_inset LatexCommand \index{objdump (tool)}
17856
17857 \end_inset
17858
17859
17860 \end_inset
17861 </cell>
17862 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17863 \begin_inset Text
17864
17865 \layout Standard
17866
17867 Object file conversion, ...
17868 \end_inset
17869 </cell>
17870 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17871 \begin_inset Text
17872
17873 \layout Standard
17874
17875 Part of binutils (should be there anyway)
17876 \end_inset
17877 </cell>
17878 </row>
17879 <row topline="true">
17880 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17881 \begin_inset Text
17882
17883 \layout Standard
17884
17885 doxygen
17886 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
17887
17888 \end_inset
17889
17890
17891 \end_inset
17892 </cell>
17893 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17894 \begin_inset Text
17895
17896 \layout Standard
17897
17898 Source code documentation system
17899 \end_inset
17900 </cell>
17901 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17902 \begin_inset Text
17903
17904 \layout Standard
17905
17906
17907 \begin_inset LatexCommand \url{http://www.doxygen.org}
17908
17909 \end_inset
17910
17911
17912 \end_inset
17913 </cell>
17914 </row>
17915 <row topline="true">
17916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17917 \begin_inset Text
17918
17919 \layout Standard
17920
17921 kdevelop
17922 \end_inset
17923 </cell>
17924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17925 \begin_inset Text
17926
17927 \layout Standard
17928
17929 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
17930 \end_inset
17931 </cell>
17932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17933 \begin_inset Text
17934
17935 \layout Standard
17936
17937
17938 \begin_inset LatexCommand \url{http://www.kdevelop.org}
17939
17940 \end_inset
17941
17942
17943 \end_inset
17944 </cell>
17945 </row>
17946 <row topline="true">
17947 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17948 \begin_inset Text
17949
17950 \layout Standard
17951
17952 splint
17953 \begin_inset LatexCommand \index{splint (syntax checking tool)}
17954
17955 \end_inset
17956
17957
17958 \end_inset
17959 </cell>
17960 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17961 \begin_inset Text
17962
17963 \layout Standard
17964
17965 Statically checks c sources
17966 \end_inset
17967 </cell>
17968 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17969 \begin_inset Text
17970
17971 \layout Standard
17972
17973
17974 \begin_inset LatexCommand \url{http://www.splint.org}
17975
17976 \end_inset
17977
17978
17979 \end_inset
17980 </cell>
17981 </row>
17982 <row topline="true" bottomline="true">
17983 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17984 \begin_inset Text
17985
17986 \layout Standard
17987
17988 ddd
17989 \begin_inset LatexCommand \index{ddd (debugger)}
17990
17991 \end_inset
17992
17993
17994 \end_inset
17995 </cell>
17996 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17997 \begin_inset Text
17998
17999 \layout Standard
18000
18001 Debugger, serves nicely as GUI to sdcdb
18002 \begin_inset LatexCommand \index{sdcdb (debugger)}
18003
18004 \end_inset
18005
18006  (Unix only)
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
18015 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
18016
18017 \end_inset
18018
18019
18020 \end_inset
18021 </cell>
18022 </row>
18023 </lyxtabular>
18024
18025 \end_inset
18026
18027
18028 \newline
18029
18030 \layout Section
18031
18032 Related documentation / recommended reading
18033 \layout Standard
18034 \align center
18035
18036 \begin_inset  Tabular
18037 <lyxtabular version="3" rows="6" columns="3">
18038 <features>
18039 <column alignment="center" valignment="top" leftline="true" width="0pt">
18040 <column alignment="block" valignment="top" leftline="true" width="30line%">
18041 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18042 <row topline="true" bottomline="true">
18043 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18044 \begin_inset Text
18045
18046 \layout Standard
18047
18048 Name
18049 \end_inset
18050 </cell>
18051 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18052 \begin_inset Text
18053
18054 \layout Standard
18055
18056 Subject / Title
18057 \end_inset
18058 </cell>
18059 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18060 \begin_inset Text
18061
18062 \layout Standard
18063
18064 Where to get
18065 \end_inset
18066 </cell>
18067 </row>
18068 <row topline="true">
18069 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18070 \begin_inset Text
18071
18072 \layout Standard
18073
18074
18075 \family roman
18076 \series medium
18077 \shape up
18078 \size normal
18079 \emph off
18080 \bar no
18081 \noun off
18082 \color none
18083 c-refcard.pdf
18084 \end_inset
18085 </cell>
18086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18087 \begin_inset Text
18088
18089 \layout Standard
18090
18091 C Reference Card
18092 \begin_inset LatexCommand \index{C Reference card}
18093
18094 \end_inset
18095
18096 , 2 pages
18097 \end_inset
18098 </cell>
18099 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18100 \begin_inset Text
18101
18102 \layout Standard
18103
18104
18105 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
18106
18107 \end_inset
18108
18109
18110 \end_inset
18111 </cell>
18112 </row>
18113 <row topline="true">
18114 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18115 \begin_inset Text
18116
18117 \layout Standard
18118
18119 c-faq
18120 \end_inset
18121 </cell>
18122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18123 \begin_inset Text
18124
18125 \layout Standard
18126
18127 C-FAQ-list
18128 \end_inset
18129 </cell>
18130 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18131 \begin_inset Text
18132
18133 \layout Standard
18134
18135
18136 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
18137
18138 \end_inset
18139
18140
18141 \end_inset
18142 </cell>
18143 </row>
18144 <row topline="true">
18145 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18146 \begin_inset Text
18147
18148 \layout Standard
18149
18150 \end_inset
18151 </cell>
18152 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18153 \begin_inset Text
18154
18155 \layout Standard
18156
18157 Latest datasheet of the target CPU
18158 \end_inset
18159 </cell>
18160 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18161 \begin_inset Text
18162
18163 \layout Standard
18164
18165 vendor
18166 \end_inset
18167 </cell>
18168 </row>
18169 <row topline="true">
18170 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18171 \begin_inset Text
18172
18173 \layout Standard
18174
18175 \end_inset
18176 </cell>
18177 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18178 \begin_inset Text
18179
18180 \layout Standard
18181
18182 Revision history of datasheet
18183 \end_inset
18184 </cell>
18185 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18186 \begin_inset Text
18187
18188 \layout Standard
18189
18190 vendor
18191 \end_inset
18192 </cell>
18193 </row>
18194 <row topline="true" bottomline="true">
18195 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18196 \begin_inset Text
18197
18198 \layout Standard
18199
18200 S.
18201  S.
18202  Muchnick
18203 \end_inset
18204 </cell>
18205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18206 \begin_inset Text
18207
18208 \layout Standard
18209
18210 Advanced Compiler Design and Implementation
18211 \end_inset
18212 </cell>
18213 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18214 \begin_inset Text
18215
18216 \layout Standard
18217
18218 bookstore (very dedicated, probably read other books first)
18219 \end_inset
18220 </cell>
18221 </row>
18222 </lyxtabular>
18223
18224 \end_inset
18225
18226
18227 \newline
18228
18229 \layout Section
18230
18231 Some Questions
18232 \layout Standard
18233
18234 Some questions answered, some pointers given - it might be time to in turn
18235  ask
18236 \emph on
18237 you
18238 \emph default
18239  some questions:
18240 \layout Itemize
18241
18242 can you solve your project with the selected microcontroller? Would you
18243  find out early or rather late that your target is too small/slow/whatever?
18244  Can you switch to a slightly better device if it doesn't fit?
18245 \layout Itemize
18246
18247 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
18248  and/or another programming language be more adequate? Would an operating
18249  system on the target device help?
18250 \layout Itemize
18251
18252 if you solved the problem, will the marketing department be happy?
18253 \layout Itemize
18254
18255 if the marketing department is happy, will customers be happy?
18256 \layout Itemize
18257
18258 if you're the project manager, marketing department and maybe even the customer
18259  in one person, have you tried to see the project from the outside?
18260 \layout Itemize
18261
18262 is the project done if you think it is done? Or is just that other interface/pro
18263 tocol/feature/configuration/option missing? How about website, manual(s),
18264  internationali(z|s)ation, packaging, labels, 2nd source for components,
18265  electromagnetic compatability/interference, documentation for production,
18266  production test software, update mechanism, patent issues?
18267 \layout Itemize
18268
18269 is your project adequately positioned in that magic triangle: fame, fortune,
18270  fun?
18271 \layout Standard
18272
18273 Maybe not all answers to these questions are known and some answers may
18274  even be
18275 \emph on
18276 no
18277 \emph default
18278 , nevertheless knowing these questions may help you to avoid burnout
18279 \begin_inset Foot
18280 collapsed false
18281
18282 \layout Standard
18283
18284 burnout is bad for electronic devices, programmers and motorcycle tyres
18285 \end_inset
18286
18287 .
18288  Chances are you didn't want to hear some of them...
18289 \layout Chapter
18290
18291 Support
18292 \begin_inset LatexCommand \index{Support}
18293
18294 \end_inset
18295
18296
18297 \layout Standard
18298
18299 SDCC has grown to be a large project.
18300  The compiler alone (without the preprocessor, assembler and linker) is
18301  well over 100,000 lines of code (blank stripped).
18302  The open source nature of this project is a key to its continued growth
18303  and support.
18304  You gain the benefit and support of many active software developers and
18305  end users.
18306  Is SDCC perfect? No, that's why we need your help.
18307  The developers take pride in fixing reported bugs.
18308  You can help by reporting the bugs and helping other SDCC users.
18309  There are lots of ways to contribute, and we encourage you to take part
18310  in making SDCC a great software package.
18311
18312 \layout Standard
18313
18314 The SDCC project is hosted on the SDCC sourceforge site at
18315 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
18316
18317 \end_inset
18318
18319 .
18320  You'll find the complete set of mailing lists
18321 \begin_inset LatexCommand \index{Mailing list}
18322
18323 \end_inset
18324
18325 , forums, bug reporting system, patch submission
18326 \begin_inset LatexCommand \index{Patch submission}
18327
18328 \end_inset
18329
18330  system, download
18331 \begin_inset LatexCommand \index{download}
18332
18333 \end_inset
18334
18335  area and cvs code repository
18336 \begin_inset LatexCommand \index{cvs code repository}
18337
18338 \end_inset
18339
18340  there.
18341 \layout Section
18342
18343 Reporting Bugs
18344 \begin_inset LatexCommand \index{Bug reporting}
18345
18346 \end_inset
18347
18348
18349 \begin_inset LatexCommand \index{Reporting bugs}
18350
18351 \end_inset
18352
18353
18354 \layout Standard
18355
18356 The recommended way of reporting bugs is using the infrastructure of the
18357  sourceforge site.
18358  You can follow the status of bug reports there and have an overview about
18359  the known bugs.
18360 \layout Standard
18361
18362 Bug reports are automatically forwarded to the developer mailing list and
18363  will be fixed ASAP.
18364  When reporting a bug, it is very useful to include a small test program
18365  (the smaller the better) which reproduces the problem.
18366  If you can isolate the problem by looking at the generated assembly code,
18367  this can be very helpful.
18368  Compiling your program with the -
18369 \begin_inset ERT
18370 status Collapsed
18371
18372 \layout Standard
18373
18374 \backslash
18375 /
18376 \end_inset
18377
18378 -dumpall
18379 \begin_inset LatexCommand \index{-\/-dumpall}
18380
18381 \end_inset
18382
18383  option can sometimes be useful in locating optimization problems.
18384  When reporting a bug please maker sure you:
18385 \layout Enumerate
18386
18387 Attach the code you are compiling with SDCC.
18388
18389 \layout Enumerate
18390
18391 Specify the exact command you use to run SDCC, or attach your Makefile.
18392
18393 \layout Enumerate
18394
18395 Specify the SDCC version (type "
18396 \family sans
18397 \series bold
18398 sdcc -v
18399 \family default
18400 \series default
18401 "), your platform, and operating system.
18402
18403 \layout Enumerate
18404
18405 Provide an exact copy of any error message or incorrect output.
18406
18407 \layout Enumerate
18408
18409 Put something meaningful in the subject of your message.
18410 \layout Standard
18411
18412 Please attempt to include these 5 important parts, as applicable, in all
18413  requests for support or when reporting any problems or bugs with SDCC.
18414  Though this will make your message lengthy, it will greatly improve your
18415  chance that SDCC users and developers will be able to help you.
18416  Some SDCC developers are frustrated by bug reports without code provided
18417  that they can use to reproduce and ultimately fix the problem, so please
18418  be sure to provide sample code if you are reporting a bug!
18419 \layout Standard
18420
18421 Please have a short check that you are using a recent version of SDCC and
18422  the bug is not yet known.
18423  This is the link for reporting bugs:
18424 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
18425
18426 \end_inset
18427
18428 .
18429 \layout Section
18430
18431 Requesting Features
18432 \begin_inset LatexCommand \label{sub:Requesting-Features}
18433
18434 \end_inset
18435
18436
18437 \begin_inset LatexCommand \index{Feature request}
18438
18439 \end_inset
18440
18441
18442 \begin_inset LatexCommand \index{Requesting features}
18443
18444 \end_inset
18445
18446
18447 \layout Standard
18448
18449 Like bug reports feature requests are forwarded to the developer mailing
18450  list.
18451  This is the link for requesting features:
18452 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
18453
18454 \end_inset
18455
18456 .
18457 \layout Section
18458
18459 Submitting patches
18460 \layout Standard
18461
18462 Like bug reports contributed patches are forwarded to the developer mailing
18463  list.
18464  This is the link for submitting patches
18465 \begin_inset LatexCommand \index{Patch submission}
18466
18467 \end_inset
18468
18469 :
18470 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
18471
18472 \end_inset
18473
18474 .
18475 \layout Standard
18476
18477 You need to specify some parameters to the
18478 \family typewriter
18479 diff
18480 \family default
18481  command for the patches to be useful.
18482  If you modified more than one file a patch created f.e.
18483  with
18484 \family sans
18485 \series bold
18486
18487 \begin_inset Quotes sld
18488 \end_inset
18489
18490 diff -Naur unmodified_directory modified_directory >my_changes.patch
18491 \begin_inset Quotes srd
18492 \end_inset
18493
18494
18495 \family default
18496 \series default
18497  will be fine, otherwise
18498 \family sans
18499 \series bold
18500
18501 \begin_inset Quotes sld
18502 \end_inset
18503
18504 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
18505 \begin_inset Quotes srd
18506 \end_inset
18507
18508
18509 \series default
18510
18511 \family default
18512 will do.
18513 \layout Section
18514
18515 Getting Help
18516 \layout Standard
18517
18518 These links should take you directly to the
18519 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
18520
18521 \end_inset
18522
18523
18524 \begin_inset Foot
18525 collapsed false
18526
18527 \layout Standard
18528
18529 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
18530  automated messages (mid 2003)
18531 \end_inset
18532
18533  and the
18534 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
18535
18536 \end_inset
18537
18538 , lists and forums are archived and searchable so if you are lucky someone
18539  already had a similar problem.
18540 \layout Section
18541
18542 ChangeLog
18543 \layout Standard
18544
18545 You can follow the status of the cvs version
18546 \begin_inset LatexCommand \index{version}
18547
18548 \end_inset
18549
18550  of SDCC by watching the Changelog
18551 \begin_inset LatexCommand \index{Changelog}
18552
18553 \end_inset
18554
18555  in the cvs-repository
18556 \newline
18557
18558 \size footnotesize
18559
18560 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
18561
18562 \end_inset
18563
18564 .
18565 \layout Section
18566
18567 Release policy
18568 \begin_inset LatexCommand \index{Release policy}
18569
18570 \end_inset
18571
18572
18573 \layout Standard
18574
18575 Historically there often were long delays between official releases and
18576  the sourceforge download area tends to get not updated at all.
18577  Excuses in the past might have referred to problems with live range analysis,
18578  but as this was fixed a while ago, the current problem is that another
18579  excuse has to be found.
18580  Kidding aside, we have to get better there! On the other hand there are
18581  daily snapshots available at
18582 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
18583
18584 \end_inset
18585
18586 , and you can always build the very last version (hopefully with many bugs
18587  fixed, and features added) from the source code available at
18588 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
18589
18590 \end_inset
18591
18592 .
18593 \layout Section
18594
18595 Examples
18596 \begin_inset LatexCommand \index{Examples}
18597
18598 \end_inset
18599
18600
18601 \layout Standard
18602
18603 You'll find some small examples in the directory
18604 \emph on
18605 sdcc/device/examples/.
18606
18607 \emph default
18608 More examples and libraries are available at
18609 \emph on
18610  The SDCC Open Knowledge Resource
18611 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
18612
18613 \end_inset
18614
18615
18616 \emph default
18617 web site or at
18618 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
18619
18620 \end_inset
18621
18622 .
18623 \layout Comment
18624
18625 I did insert a reference to Paul's web site here although it seems rather
18626  dedicated to a specific 8032 board (I think it's okay because it f.e.
18627  shows LCD/Harddisc interface and has a free 8051 monitor.
18628  Independent 8032 board vendors face hard competition of heavily subsidized
18629  development boards anyway).
18630 \layout Comment
18631
18632 Maybe we should include some links to real world applications.
18633  Preferably pointer to pointers (one for each architecture) so this stays
18634  manageable here?
18635 \layout Section
18636
18637 Quality control
18638 \begin_inset LatexCommand \index{Quality control}
18639
18640 \end_inset
18641
18642
18643 \layout Standard
18644
18645 The compiler is passed through nightly compile and build checks.
18646  The so called
18647 \shape italic
18648 regression tests
18649 \shape default
18650
18651 \begin_inset LatexCommand \index{Regression test}
18652
18653 \end_inset
18654
18655  check that SDCC itself compiles flawlessly on several platforms and checks
18656  the quality of the code generated by SDCC by running the code through simulator
18657 s.
18658  There is a separate document
18659 \shape italic
18660 test_suite.pdf
18661 \begin_inset LatexCommand \index{Test suite}
18662
18663 \end_inset
18664
18665
18666 \shape default
18667  about this.
18668 \layout Standard
18669
18670 You'll find the test code in the directory
18671 \shape italic
18672 sdcc/support/regression
18673 \shape default
18674 .
18675  You can run these tests manually by running
18676 \family sans
18677 make
18678 \family default
18679  in this directory (or f.e.
18680
18681 \family sans
18682 \series bold
18683
18684 \begin_inset Quotes sld
18685 \end_inset
18686
18687 make test-mcs51
18688 \begin_inset Quotes srd
18689 \end_inset
18690
18691
18692 \family default
18693 \series default
18694  if you don't want to run the complete tests).
18695  The test code might also be interesting if you want to look for examples
18696 \begin_inset LatexCommand \index{Examples}
18697
18698 \end_inset
18699
18700  checking corner cases of SDCC or if you plan to submit patches
18701 \begin_inset LatexCommand \index{Patch submission}
18702
18703 \end_inset
18704
18705 .
18706 \layout Standard
18707
18708 The pic port uses a different set of regression tests, you'll find them
18709  in the directory
18710 \shape italic
18711 sdcc/src/regression
18712 \shape default
18713 .
18714 \layout Chapter
18715 \pagebreak_top
18716 SDCC Technical Data
18717 \layout Section
18718
18719 Optimizations
18720 \begin_inset LatexCommand \index{Optimizations}
18721
18722 \end_inset
18723
18724
18725 \layout Standard
18726
18727 SDCC performs a host of standard optimizations in addition to some MCU specific
18728  optimizations.
18729
18730 \layout Subsection
18731
18732 Sub-expression Elimination
18733 \begin_inset LatexCommand \index{Subexpression elimination}
18734
18735 \end_inset
18736
18737
18738 \layout Standard
18739
18740 The compiler does local and
18741 \emph on
18742 g
18743 \emph default
18744 lobal
18745 \emph on
18746 c
18747 \emph default
18748 ommon
18749 \emph on
18750 s
18751 \emph default
18752 ubexpression
18753 \emph on
18754 e
18755 \emph default
18756 limination, e.g.:
18757 \layout Verse
18758
18759
18760 \family typewriter
18761 i = x + y + 1;
18762 \newline
18763 j = x + y;
18764 \layout Standard
18765
18766 will be translated to
18767 \layout Verse
18768
18769
18770 \family typewriter
18771 iTemp = x + y;
18772 \newline
18773 i = iTemp + 1;
18774 \newline
18775 j = iTemp;
18776 \layout Standard
18777
18778 Some subexpressions are not as obvious as the above example, e.g.:
18779 \layout Verse
18780
18781
18782 \family typewriter
18783 a->b[i].c = 10;
18784 \newline
18785 a->b[i].d = 11;
18786 \layout Standard
18787
18788 In this case the address arithmetic a->b[i] will be computed only once;
18789  the equivalent code in C would be.
18790 \layout Verse
18791
18792
18793 \family typewriter
18794 iTemp = a->b[i];
18795 \newline
18796 iTemp.c = 10;
18797 \newline
18798 iTemp.d = 11;
18799 \layout Standard
18800
18801 The compiler will try to keep these temporary variables in registers.
18802 \layout Subsection
18803
18804 Dead-Code Elimination
18805 \begin_inset LatexCommand \index{Dead-code elimination}
18806
18807 \end_inset
18808
18809
18810 \layout Verse
18811
18812
18813 \family typewriter
18814 int global;
18815 \newline
18816
18817 \newline
18818 void f () {
18819 \newline
18820 \SpecialChar ~
18821 \SpecialChar ~
18822 int i;
18823 \newline
18824 \SpecialChar ~
18825 \SpecialChar ~
18826 i = 1; \SpecialChar ~
18827 \SpecialChar ~
18828 \SpecialChar ~
18829 \SpecialChar ~
18830 \SpecialChar ~
18831 /* dead store */
18832 \newline
18833 \SpecialChar ~
18834 \SpecialChar ~
18835 global = 1;\SpecialChar ~
18836 /* dead store */
18837 \newline
18838 \SpecialChar ~
18839 \SpecialChar ~
18840 global = 2;
18841 \newline
18842 \SpecialChar ~
18843 \SpecialChar ~
18844 return;
18845 \newline
18846 \SpecialChar ~
18847 \SpecialChar ~
18848 global = 3;\SpecialChar ~
18849 /* unreachable */
18850 \newline
18851 }
18852 \layout Standard
18853
18854 will be changed to
18855 \layout Verse
18856
18857
18858 \family typewriter
18859 int global;
18860 \newline
18861
18862 \newline
18863 void f () {
18864 \newline
18865 \SpecialChar ~
18866 \SpecialChar ~
18867 global = 2;
18868 \newline
18869 \SpecialChar ~
18870 \SpecialChar ~
18871 return;
18872 \newline
18873 }
18874 \layout Subsection
18875
18876 Copy-Propagation
18877 \begin_inset LatexCommand \index{Copy propagation}
18878
18879 \end_inset
18880
18881
18882 \layout Verse
18883
18884
18885 \family typewriter
18886 int f() {
18887 \newline
18888 \SpecialChar ~
18889 \SpecialChar ~
18890 int i, j;
18891 \newline
18892 \SpecialChar ~
18893 \SpecialChar ~
18894 i = 10;
18895 \newline
18896 \SpecialChar ~
18897 \SpecialChar ~
18898 j = i;
18899 \newline
18900 \SpecialChar ~
18901 \SpecialChar ~
18902 return j;
18903 \newline
18904 }
18905 \layout Standard
18906
18907 will be changed to
18908 \layout Verse
18909
18910
18911 \family typewriter
18912 int f() {
18913 \newline
18914 \SpecialChar ~
18915 \SpecialChar ~
18916 int i, j;
18917 \newline
18918 \SpecialChar ~
18919 \SpecialChar ~
18920 i = 10;
18921 \newline
18922 \SpecialChar ~
18923 \SpecialChar ~
18924 j = 10;
18925 \newline
18926 \SpecialChar ~
18927 \SpecialChar ~
18928 return 10;
18929 \newline
18930 }
18931 \layout Standard
18932
18933 Note: the dead stores created by this copy propagation will be eliminated
18934  by dead-code elimination.
18935 \layout Subsection
18936
18937 Loop Optimizations
18938 \begin_inset LatexCommand \index{Loop optimization}
18939
18940 \end_inset
18941
18942
18943 \layout Standard
18944
18945 Two types of loop optimizations are done by SDCC loop invariant lifting
18946  and strength reduction of loop induction variables.
18947  In addition to the strength reduction the optimizer marks the induction
18948  variables and the register allocator tries to keep the induction variables
18949  in registers for the duration of the loop.
18950  Because of this preference of the register allocator
18951 \begin_inset LatexCommand \index{Register allocation}
18952
18953 \end_inset
18954
18955 , loop induction optimization causes an increase in register pressure, which
18956  may cause unwanted spilling of other temporary variables into the stack
18957 \begin_inset LatexCommand \index{stack}
18958
18959 \end_inset
18960
18961  / data space.
18962  The compiler will generate a warning message when it is forced to allocate
18963  extra space either on the stack or data space.
18964  If this extra space allocation is undesirable then induction optimization
18965  can be eliminated either for the entire source file (with -
18966 \begin_inset ERT
18967 status Collapsed
18968
18969 \layout Standard
18970
18971 \backslash
18972 /
18973 \end_inset
18974
18975 -noinduction option) or for a given function only using #pragma\SpecialChar ~
18976 noinduction
18977 \begin_inset LatexCommand \index{\#pragma noinduction}
18978
18979 \end_inset
18980
18981 .
18982 \newline
18983
18984 \newline
18985 Loop Invariant:
18986 \layout Verse
18987
18988
18989 \family typewriter
18990 for (i = 0 ; i < 100 ; i ++)
18991 \newline
18992 \SpecialChar ~
18993 \SpecialChar ~
18994 \SpecialChar ~
18995 \SpecialChar ~
18996 f += k + l;
18997 \layout Standard
18998
18999 changed to
19000 \layout Verse
19001
19002
19003 \family typewriter
19004 itemp = k + l;
19005 \newline
19006 for (i = 0; i < 100; i++)
19007 \newline
19008 \SpecialChar ~
19009 \SpecialChar ~
19010 \SpecialChar ~
19011 \SpecialChar ~
19012 f += itemp;
19013 \layout Standard
19014
19015 As mentioned previously some loop invariants are not as apparent, all static
19016  address computations are also moved out of the loop.
19017 \newline
19018
19019 \newline
19020 Strength Reduction
19021 \begin_inset LatexCommand \index{Strength reduction}
19022
19023 \end_inset
19024
19025 , this optimization substitutes an expression by a cheaper expression:
19026 \layout Verse
19027
19028
19029 \family typewriter
19030 for (i=0;i < 100; i++)
19031 \newline
19032 \SpecialChar ~
19033 \SpecialChar ~
19034 \SpecialChar ~
19035 \SpecialChar ~
19036 ar[i*5] = i*3;
19037 \layout Standard
19038
19039 changed to
19040 \layout Verse
19041
19042
19043 \family typewriter
19044 itemp1 = 0;
19045 \newline
19046 itemp2 = 0;
19047 \newline
19048 for (i=0;i< 100;i++) {
19049 \newline
19050 \SpecialChar ~
19051 \SpecialChar ~
19052 \SpecialChar ~
19053 \SpecialChar ~
19054 ar[itemp1] = itemp2;
19055 \newline
19056 \SpecialChar ~
19057 \SpecialChar ~
19058 \SpecialChar ~
19059 \SpecialChar ~
19060 itemp1 += 5;
19061 \newline
19062 \SpecialChar ~
19063 \SpecialChar ~
19064 \SpecialChar ~
19065 \SpecialChar ~
19066 itemp2 += 3;
19067 \newline
19068 }
19069 \layout Standard
19070
19071 The more expensive multiplication
19072 \begin_inset LatexCommand \index{Multiplication}
19073
19074 \end_inset
19075
19076  is changed to a less expensive addition.
19077 \layout Subsection
19078
19079 Loop Reversing
19080 \begin_inset LatexCommand \index{Loop reversing}
19081
19082 \end_inset
19083
19084
19085 \layout Standard
19086
19087 This optimization is done to reduce the overhead of checking loop boundaries
19088  for every iteration.
19089  Some simple loops can be reversed and implemented using a
19090 \begin_inset Quotes eld
19091 \end_inset
19092
19093 decrement and jump if not zero
19094 \begin_inset Quotes erd
19095 \end_inset
19096
19097  instruction.
19098  SDCC checks for the following criterion to determine if a loop is reversible
19099  (note: more sophisticated compilers use data-dependency analysis to make
19100  this determination, SDCC uses a more simple minded analysis).
19101 \layout Itemize
19102
19103 The 'for' loop is of the form
19104 \newline
19105
19106 \newline
19107
19108 \family typewriter
19109 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
19110  += 1])
19111 \newline
19112 \SpecialChar ~
19113 \SpecialChar ~
19114 \SpecialChar ~
19115 \SpecialChar ~
19116 <for body>
19117 \layout Itemize
19118
19119 The <for body> does not contain
19120 \begin_inset Quotes eld
19121 \end_inset
19122
19123 continue
19124 \begin_inset Quotes erd
19125 \end_inset
19126
19127  or 'break
19128 \begin_inset Quotes erd
19129 \end_inset
19130
19131 .
19132 \layout Itemize
19133
19134 All goto's are contained within the loop.
19135 \layout Itemize
19136
19137 No function calls within the loop.
19138 \layout Itemize
19139
19140 The loop control variable <sym> is not assigned any value within the loop
19141 \layout Itemize
19142
19143 The loop control variable does NOT participate in any arithmetic operation
19144  within the loop.
19145 \layout Itemize
19146
19147 There are NO switch statements in the loop.
19148 \layout Subsection
19149
19150 Algebraic Simplifications
19151 \layout Standard
19152
19153 SDCC does numerous algebraic simplifications, the following is a small sub-set
19154  of these optimizations.
19155 \layout Verse
19156
19157
19158 \family typewriter
19159 i = j + 0;\SpecialChar ~
19160 \SpecialChar ~
19161 \SpecialChar ~
19162 \SpecialChar ~
19163  /* changed to: */\SpecialChar ~
19164 \SpecialChar ~
19165 \SpecialChar ~
19166 \SpecialChar ~
19167  i = j;
19168 \newline
19169 i /= 2;\SpecialChar ~
19170 \SpecialChar ~
19171 \SpecialChar ~
19172 \SpecialChar ~
19173 \SpecialChar ~
19174 \SpecialChar ~
19175 \SpecialChar ~
19176  /* changed to: */\SpecialChar ~
19177 \SpecialChar ~
19178 \SpecialChar ~
19179 \SpecialChar ~
19180  i >>= 1;
19181 \newline
19182 i = j - j;\SpecialChar ~
19183 \SpecialChar ~
19184 \SpecialChar ~
19185 \SpecialChar ~
19186  /* changed to: */\SpecialChar ~
19187 \SpecialChar ~
19188 \SpecialChar ~
19189 \SpecialChar ~
19190  i = 0;
19191 \newline
19192 i = j / 1;\SpecialChar ~
19193 \SpecialChar ~
19194 \SpecialChar ~
19195 \SpecialChar ~
19196  /* changed to: */\SpecialChar ~
19197 \SpecialChar ~
19198 \SpecialChar ~
19199 \SpecialChar ~
19200  i = j;
19201 \layout Standard
19202
19203 Note the subexpressions
19204 \begin_inset LatexCommand \index{Subexpression}
19205
19206 \end_inset
19207
19208  given above are generally introduced by macro expansions or as a result
19209  of copy/constant propagation.
19210 \layout Subsection
19211
19212 'switch' Statements
19213 \begin_inset LatexCommand \label{sub:'switch'-Statements}
19214
19215 \end_inset
19216
19217
19218 \begin_inset LatexCommand \index{switch statement}
19219
19220 \end_inset
19221
19222
19223 \layout Standard
19224
19225 SDCC changes switch statements to jump tables
19226 \begin_inset LatexCommand \index{jump tables}
19227
19228 \end_inset
19229
19230  when the following conditions are true.
19231
19232 \layout Itemize
19233
19234 The case labels are in numerical sequence, the labels need not be in order,
19235  and the starting number need not be one or zero.
19236 \begin_deeper
19237 \layout Verse
19238
19239
19240 \family typewriter
19241 switch(i) {\SpecialChar ~
19242 \SpecialChar ~
19243 \SpecialChar ~
19244 \SpecialChar ~
19245 \SpecialChar ~
19246 \SpecialChar ~
19247 \SpecialChar ~
19248 \SpecialChar ~
19249 \SpecialChar ~
19250 \SpecialChar ~
19251 \SpecialChar ~
19252 \SpecialChar ~
19253 \SpecialChar ~
19254 \SpecialChar ~
19255 \SpecialChar ~
19256 \SpecialChar ~
19257 \SpecialChar ~
19258 \SpecialChar ~
19259 \SpecialChar ~
19260 \SpecialChar ~
19261 \SpecialChar ~
19262 \SpecialChar ~
19263 \SpecialChar ~
19264 \SpecialChar ~
19265 \SpecialChar ~
19266 \SpecialChar ~
19267 switch (i) {
19268 \newline
19269 \SpecialChar ~
19270 \SpecialChar ~
19271 \SpecialChar ~
19272 case 4: ...\SpecialChar ~
19273 \SpecialChar ~
19274 \SpecialChar ~
19275 \SpecialChar ~
19276 \SpecialChar ~
19277 \SpecialChar ~
19278 \SpecialChar ~
19279 \SpecialChar ~
19280 \SpecialChar ~
19281 \SpecialChar ~
19282 \SpecialChar ~
19283 \SpecialChar ~
19284 \SpecialChar ~
19285 \SpecialChar ~
19286 \SpecialChar ~
19287 \SpecialChar ~
19288 \SpecialChar ~
19289 \SpecialChar ~
19290 \SpecialChar ~
19291 \SpecialChar ~
19292 \SpecialChar ~
19293 \SpecialChar ~
19294 \SpecialChar ~
19295 \SpecialChar ~
19296 \SpecialChar ~
19297 \SpecialChar ~
19298 case 0: ...
19299
19300 \newline
19301 \SpecialChar ~
19302 \SpecialChar ~
19303 \SpecialChar ~
19304 case 5: ...\SpecialChar ~
19305 \SpecialChar ~
19306 \SpecialChar ~
19307 \SpecialChar ~
19308 \SpecialChar ~
19309 \SpecialChar ~
19310 \SpecialChar ~
19311 \SpecialChar ~
19312 \SpecialChar ~
19313 \SpecialChar ~
19314 \SpecialChar ~
19315 \SpecialChar ~
19316 \SpecialChar ~
19317 \SpecialChar ~
19318 \SpecialChar ~
19319 \SpecialChar ~
19320 \SpecialChar ~
19321 \SpecialChar ~
19322 \SpecialChar ~
19323 \SpecialChar ~
19324 \SpecialChar ~
19325 \SpecialChar ~
19326 \SpecialChar ~
19327 \SpecialChar ~
19328 \SpecialChar ~
19329 \SpecialChar ~
19330 case 1: ...
19331
19332 \newline
19333 \SpecialChar ~
19334 \SpecialChar ~
19335 \SpecialChar ~
19336 case 3: ...\SpecialChar ~
19337 \SpecialChar ~
19338 \SpecialChar ~
19339 \SpecialChar ~
19340 \SpecialChar ~
19341 \SpecialChar ~
19342 \SpecialChar ~
19343 \SpecialChar ~
19344 \SpecialChar ~
19345 \SpecialChar ~
19346 \SpecialChar ~
19347 \SpecialChar ~
19348 \SpecialChar ~
19349 \SpecialChar ~
19350 \SpecialChar ~
19351 \SpecialChar ~
19352 \SpecialChar ~
19353 \SpecialChar ~
19354 \SpecialChar ~
19355 \SpecialChar ~
19356 \SpecialChar ~
19357 \SpecialChar ~
19358 \SpecialChar ~
19359 \SpecialChar ~
19360 \SpecialChar ~
19361 \SpecialChar ~
19362 case 2: ...
19363
19364 \newline
19365 \SpecialChar ~
19366 \SpecialChar ~
19367 \SpecialChar ~
19368 case 6: ...\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 \SpecialChar ~
19391 \SpecialChar ~
19392 \SpecialChar ~
19393 \SpecialChar ~
19394 case 3: ...
19395
19396 \newline
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 \SpecialChar ~
19429 \SpecialChar ~
19430 \SpecialChar ~
19431 \SpecialChar ~
19432 \SpecialChar ~
19433 }
19434 \layout Standard
19435
19436 Both the above switch statements will be implemented using a jump-table.
19437  The example to the right side is slightly more efficient as the check for
19438  the lower boundary of the jump-table is not needed.
19439 \end_deeper
19440 \layout Itemize
19441
19442 The number of case labels is at least three, since it takes two conditional
19443  statements to handle the boundary conditions.
19444 \layout Itemize
19445
19446 The number of case labels is less than 84, since each label takes 3 bytes
19447  and a jump-table can be utmost 256 bytes long.
19448 \layout Standard
19449
19450 Switch statements which have gaps in the numeric sequence or those that
19451  have more that 84 case labels can be split into more than one switch statement
19452  for efficient code generation, e.g.:
19453 \layout Verse
19454
19455
19456 \family typewriter
19457 switch (i) {
19458 \newline
19459 \SpecialChar ~
19460 \SpecialChar ~
19461 case 1: ...
19462
19463 \newline
19464 \SpecialChar ~
19465 \SpecialChar ~
19466 case 2: ...
19467
19468 \newline
19469 \SpecialChar ~
19470 \SpecialChar ~
19471 case 3: ...
19472
19473 \newline
19474 \SpecialChar ~
19475 \SpecialChar ~
19476 case 4: ...
19477
19478 \newline
19479 \SpecialChar ~
19480 \SpecialChar ~
19481 case 9: ...
19482
19483 \newline
19484 \SpecialChar ~
19485 \SpecialChar ~
19486 case 10: ...
19487
19488 \newline
19489 \SpecialChar ~
19490 \SpecialChar ~
19491 case 11: ...
19492
19493 \newline
19494 \SpecialChar ~
19495 \SpecialChar ~
19496 case 12: ...
19497
19498 \newline
19499 }
19500 \layout Standard
19501
19502 If the above switch statement is broken down into two switch statements
19503 \layout Verse
19504
19505
19506 \family typewriter
19507 switch (i) {
19508 \newline
19509 \SpecialChar ~
19510 \SpecialChar ~
19511 case 1: ...
19512
19513 \newline
19514 \SpecialChar ~
19515 \SpecialChar ~
19516 case 2: ...
19517
19518 \newline
19519 \SpecialChar ~
19520 \SpecialChar ~
19521 case 3: ...
19522
19523 \newline
19524 \SpecialChar ~
19525 \SpecialChar ~
19526 case 4: ...
19527
19528 \newline
19529 }
19530 \layout Standard
19531
19532 and
19533 \layout Verse
19534
19535
19536 \family typewriter
19537 switch (i) {
19538 \newline
19539 \SpecialChar ~
19540 \SpecialChar ~
19541 case 9:\SpecialChar ~
19542 \SpecialChar ~
19543 ...
19544
19545 \newline
19546 \SpecialChar ~
19547 \SpecialChar ~
19548 case 10:\SpecialChar ~
19549 ...
19550
19551 \newline
19552 \SpecialChar ~
19553 \SpecialChar ~
19554 case 11:\SpecialChar ~
19555 ...
19556
19557 \newline
19558 \SpecialChar ~
19559 \SpecialChar ~
19560 case 12:\SpecialChar ~
19561 ...
19562
19563 \newline
19564 }
19565 \layout Standard
19566
19567 then both the switch statements will be implemented using jump-tables whereas
19568  the unmodified switch statement will not be.
19569  You might also consider inserting dummy cases 0 and 5 to 8 in this example.
19570
19571 \newline
19572 The pragma nojtbound
19573 \begin_inset LatexCommand \index{\#pragma nojtbound}
19574
19575 \end_inset
19576
19577  can be used to turn off checking the
19578 \emph on
19579 j
19580 \emph default
19581 ump
19582 \emph on
19583 t
19584 \emph default
19585 able
19586 \emph on
19587 bound
19588 \emph default
19589 aries.
19590  It has no effect if a default label is supplied.
19591  Use of this pragma is dangerous: if the switch argument is not matched
19592  by a case statement the processor will happily jump into Nirvana.
19593 \layout Subsection
19594
19595 Bit-shifting Operations
19596 \begin_inset LatexCommand \index{Bit shifting}
19597
19598 \end_inset
19599
19600 .
19601 \layout Standard
19602
19603 Bit shifting is one of the most frequently used operation in embedded programmin
19604 g.
19605  SDCC tries to implement bit-shift operations in the most efficient way
19606  possible, e.g.:
19607 \layout Verse
19608
19609
19610 \family typewriter
19611 unsigned char i;
19612 \newline
19613 ...
19614
19615 \newline
19616 i >>= 4;
19617 \newline
19618 ...
19619 \layout Standard
19620
19621 generates the following code:
19622 \layout Verse
19623
19624
19625 \family typewriter
19626 mov\SpecialChar ~
19627  a,_i
19628 \newline
19629 swap a
19630 \newline
19631 anl\SpecialChar ~
19632  a,#0x0f
19633 \newline
19634 mov\SpecialChar ~
19635  _i,a
19636 \layout Standard
19637
19638 In general SDCC will never setup a loop if the shift count is known.
19639  Another example:
19640 \layout Verse
19641
19642
19643 \family typewriter
19644 unsigned int i;
19645 \newline
19646 ...
19647
19648 \newline
19649 i >>= 9;
19650 \newline
19651 ...
19652 \layout Standard
19653
19654 will generate:
19655 \layout Verse
19656
19657
19658 \family typewriter
19659 mov\SpecialChar ~
19660 \SpecialChar ~
19661 a,(_i + 1)
19662 \newline
19663 mov\SpecialChar ~
19664 \SpecialChar ~
19665 (_i + 1),#0x00
19666 \newline
19667 clr\SpecialChar ~
19668 \SpecialChar ~
19669 c
19670 \newline
19671 rrc\SpecialChar ~
19672 \SpecialChar ~
19673 a
19674 \newline
19675 mov\SpecialChar ~
19676 \SpecialChar ~
19677 _i,a
19678 \layout Subsection
19679
19680 Bit-rotation
19681 \begin_inset LatexCommand \index{Bit rotation}
19682
19683 \end_inset
19684
19685
19686 \layout Standard
19687
19688 A special case of the bit-shift operation is bit rotation
19689 \begin_inset LatexCommand \index{rotating bits}
19690
19691 \end_inset
19692
19693 , SDCC recognizes the following expression to be a left bit-rotation:
19694 \layout Verse
19695
19696
19697 \family typewriter
19698 \series bold
19699 unsigned
19700 \series default
19701 \SpecialChar ~
19702 \SpecialChar ~
19703 char i;\SpecialChar ~
19704 \SpecialChar ~
19705 \SpecialChar ~
19706 \SpecialChar ~
19707 \SpecialChar ~
19708 \SpecialChar ~
19709 \SpecialChar ~
19710 \SpecialChar ~
19711 \SpecialChar ~
19712 \SpecialChar ~
19713 \SpecialChar ~
19714 /* unsigned is needed for rotation */
19715 \newline
19716 ...
19717
19718 \newline
19719 i = ((i << 1) | (i >> 7));
19720 \family default
19721
19722 \newline
19723
19724 \family typewriter
19725 ...
19726 \layout Standard
19727
19728 will generate the following code:
19729 \layout Verse
19730
19731
19732 \family typewriter
19733 mov\SpecialChar ~
19734 \SpecialChar ~
19735 a,_i
19736 \newline
19737 rl\SpecialChar ~
19738 \SpecialChar ~
19739 \SpecialChar ~
19740 a
19741 \newline
19742 mov\SpecialChar ~
19743 \SpecialChar ~
19744 _i,a
19745 \layout Standard
19746
19747 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
19748 ns of this case will also be recognized as bit-rotation, i.e.:
19749 \layout Verse
19750
19751
19752 \family typewriter
19753 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
19754 \layout Subsection
19755
19756 Nibble and Byte Swapping
19757 \layout Standard
19758
19759 Other special cases of the bit-shift operations are nibble or byte swapping
19760 \begin_inset LatexCommand \index{swapping nibbles/bytes}
19761
19762 \end_inset
19763
19764 , SDCC recognizes the following expressions:
19765 \layout Verse
19766
19767
19768 \family typewriter
19769 \series bold
19770 unsigned
19771 \series default
19772 \SpecialChar ~
19773 \SpecialChar ~
19774 char i;
19775 \newline
19776
19777 \series bold
19778 unsigned
19779 \series default
19780 \SpecialChar ~
19781 \SpecialChar ~
19782 int j;
19783 \newline
19784 ...
19785
19786 \newline
19787 i = ((i << 4) | (i >> 4));
19788 \family default
19789
19790 \newline
19791
19792 \family typewriter
19793 j = ((j << 8) | (j >> 8));
19794 \layout Standard
19795
19796 and generates a swap instruction for the nibble swapping
19797 \begin_inset LatexCommand \index{Nibble swapping}
19798
19799 \end_inset
19800
19801  or move instructions for the byte swapping
19802 \begin_inset LatexCommand \index{Byte swapping}
19803
19804 \end_inset
19805
19806 .
19807  The
19808 \begin_inset Quotes sld
19809 \end_inset
19810
19811 j
19812 \begin_inset Quotes srd
19813 \end_inset
19814
19815  example can be used to convert from little to big-endian or vice versa.
19816  If you want to change the endianness of a
19817 \emph on
19818 signed
19819 \emph default
19820  integer you have to cast to
19821 \family typewriter
19822 (unsigned int)
19823 \family default
19824  first.
19825 \layout Standard
19826
19827 Note that SDCC stores numbers in little-endian
19828 \begin_inset Foot
19829 collapsed false
19830
19831 \layout Standard
19832
19833 Usually 8-bit processors don't care much about endianness.
19834  This is not the case for the standard 8051 which only has an instruction
19835  to increment its
19836 \emph on
19837 dptr
19838 \emph default
19839
19840 \begin_inset LatexCommand \index{DPTR}
19841
19842 \end_inset
19843
19844 -datapointer
19845 \emph on
19846
19847 \emph default
19848 so little-endian is the more efficient byte order.
19849 \end_inset
19850
19851
19852 \begin_inset LatexCommand \index{little-endian}
19853
19854 \end_inset
19855
19856
19857 \begin_inset LatexCommand \index{Endianness}
19858
19859 \end_inset
19860
19861  format (i.e.
19862  lowest order first).
19863 \layout Subsection
19864
19865 Highest Order Bit
19866 \begin_inset LatexCommand \index{Highest Order Bit}
19867
19868 \end_inset
19869
19870
19871 \layout Standard
19872
19873 It is frequently required to obtain the highest order bit of an integral
19874  type (long, int, short or char types).
19875  SDCC recognizes the following expression to yield the highest order bit
19876  and generates optimized code for it, e.g.:
19877 \layout Verse
19878
19879
19880 \family typewriter
19881 unsigned int gint;
19882 \newline
19883
19884 \newline
19885 foo () {
19886 \newline
19887 \SpecialChar ~
19888 \SpecialChar ~
19889 unsigned char hob;
19890 \newline
19891 \SpecialChar ~
19892 \SpecialChar ~
19893 ...
19894
19895 \newline
19896 \SpecialChar ~
19897 \SpecialChar ~
19898 hob = (gint >> 15) & 1;
19899 \newline
19900 \SpecialChar ~
19901 \SpecialChar ~
19902 ..
19903
19904 \newline
19905 }
19906 \layout Standard
19907
19908 will generate the following code:
19909 \layout Verse
19910
19911
19912 \family typewriter
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 \SpecialChar ~
19938  61 ;\SpecialChar ~
19939  hob.c 7
19940 \newline
19941 000A E5*01\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 \SpecialChar ~
19956  62\SpecialChar ~
19957 \SpecialChar ~
19958 \SpecialChar ~
19959 \SpecialChar ~
19960 \SpecialChar ~
19961 \SpecialChar ~
19962 \SpecialChar ~
19963 \SpecialChar ~
19964  mov\SpecialChar ~
19965 \SpecialChar ~
19966  a,(_gint + 1)
19967 \newline
19968 000C 23\SpecialChar ~
19969 \SpecialChar ~
19970 \SpecialChar ~
19971 \SpecialChar ~
19972 \SpecialChar ~
19973 \SpecialChar ~
19974 \SpecialChar ~
19975 \SpecialChar ~
19976 \SpecialChar ~
19977 \SpecialChar ~
19978 \SpecialChar ~
19979 \SpecialChar ~
19980 \SpecialChar ~
19981 \SpecialChar ~
19982 \SpecialChar ~
19983 \SpecialChar ~
19984 \SpecialChar ~
19985 \SpecialChar ~
19986  63\SpecialChar ~
19987 \SpecialChar ~
19988 \SpecialChar ~
19989 \SpecialChar ~
19990 \SpecialChar ~
19991 \SpecialChar ~
19992 \SpecialChar ~
19993 \SpecialChar ~
19994  rl\SpecialChar ~
19995 \SpecialChar ~
19996 \SpecialChar ~
19997  a
19998 \newline
19999 000D 54 01\SpecialChar ~
20000 \SpecialChar ~
20001 \SpecialChar ~
20002 \SpecialChar ~
20003 \SpecialChar ~
20004 \SpecialChar ~
20005 \SpecialChar ~
20006 \SpecialChar ~
20007 \SpecialChar ~
20008 \SpecialChar ~
20009 \SpecialChar ~
20010 \SpecialChar ~
20011 \SpecialChar ~
20012 \SpecialChar ~
20013 \SpecialChar ~
20014  64\SpecialChar ~
20015 \SpecialChar ~
20016 \SpecialChar ~
20017 \SpecialChar ~
20018 \SpecialChar ~
20019 \SpecialChar ~
20020 \SpecialChar ~
20021 \SpecialChar ~
20022  anl\SpecialChar ~
20023 \SpecialChar ~
20024  a,#0x01
20025 \newline
20026 000F F5*02\SpecialChar ~
20027 \SpecialChar ~
20028 \SpecialChar ~
20029 \SpecialChar ~
20030 \SpecialChar ~
20031 \SpecialChar ~
20032 \SpecialChar ~
20033 \SpecialChar ~
20034 \SpecialChar ~
20035 \SpecialChar ~
20036 \SpecialChar ~
20037 \SpecialChar ~
20038 \SpecialChar ~
20039 \SpecialChar ~
20040 \SpecialChar ~
20041  65\SpecialChar ~
20042 \SpecialChar ~
20043 \SpecialChar ~
20044 \SpecialChar ~
20045 \SpecialChar ~
20046 \SpecialChar ~
20047 \SpecialChar ~
20048 \SpecialChar ~
20049  mov\SpecialChar ~
20050 \SpecialChar ~
20051  _foo_hob_1_1,a
20052 \layout Standard
20053
20054 Variations of this case however will
20055 \emph on
20056 not
20057 \emph default
20058  be recognized.
20059  It is a standard C expression, so I heartily recommend this be the only
20060  way to get the highest order bit, (it is portable).
20061  Of course it will be recognized even if it is embedded in other expressions,
20062  e.g.:
20063 \layout Verse
20064
20065
20066 \family typewriter
20067 xyz = gint + ((gint >> 15) & 1);
20068 \layout Standard
20069
20070 will still be recognized.
20071 \layout Subsection
20072
20073 Peephole Optimizer
20074 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
20075
20076 \end_inset
20077
20078
20079 \begin_inset LatexCommand \index{Peephole optimizer}
20080
20081 \end_inset
20082
20083
20084 \layout Standard
20085
20086 The compiler uses a rule based, pattern matching and re-writing mechanism
20087  for peep-hole optimization.
20088  It is inspired by
20089 \emph on
20090 copt
20091 \emph default
20092  a peep-hole optimizer by Christopher W.
20093  Fraser (cwfraser@microsoft.com).
20094  A default set of rules are compiled into the compiler, additional rules
20095  may be added with the
20096 \emph on
20097 -
20098 \begin_inset ERT
20099 status Collapsed
20100
20101 \layout Standard
20102
20103 \backslash
20104 /
20105 \end_inset
20106
20107 -peep-file
20108 \begin_inset LatexCommand \index{-\/-peep-file}
20109
20110 \end_inset
20111
20112  <filename>
20113 \emph default
20114  option.
20115  The rule language is best illustrated with examples.
20116 \layout Verse
20117
20118
20119 \family typewriter
20120 replace {
20121 \newline
20122 \SpecialChar ~
20123 \SpecialChar ~
20124 mov %1,a
20125 \newline
20126 \SpecialChar ~
20127 \SpecialChar ~
20128 mov a,%1
20129 \newline
20130 } by {
20131 \newline
20132 \SpecialChar ~
20133 \SpecialChar ~
20134 mov %1,a
20135 \newline
20136 }
20137 \layout Standard
20138
20139 The above rule will change the following assembly
20140 \begin_inset LatexCommand \index{Assembler routines}
20141
20142 \end_inset
20143
20144  sequence:
20145 \layout Verse
20146
20147
20148 \family typewriter
20149 mov r1,a
20150 \newline
20151 mov a,r1
20152 \layout Standard
20153
20154 to
20155 \layout Verse
20156
20157
20158 \family typewriter
20159 mov r1,a
20160 \layout Standard
20161
20162 Note: All occurrences of a
20163 \emph on
20164 %n
20165 \emph default
20166  (pattern variable) must denote the same string.
20167  With the above rule, the assembly sequence:
20168 \layout Verse
20169
20170
20171 \family typewriter
20172 mov r1,a
20173 \newline
20174 mov a,r2
20175 \layout Standard
20176
20177 will remain unmodified.
20178 \newline
20179
20180 \newline
20181 Other special case optimizations may be added by the user (via
20182 \emph on
20183 -
20184 \begin_inset ERT
20185 status Collapsed
20186
20187 \layout Standard
20188
20189 \backslash
20190 /
20191 \end_inset
20192
20193 -peep-file option
20194 \emph default
20195 ).
20196  E.g.
20197  some variants of the 8051 MCU allow only
20198 \family typewriter
20199 ajmp
20200 \family default
20201  and
20202 \family typewriter
20203 acall
20204 \family default
20205 .
20206  The following two rules will change all
20207 \family typewriter
20208 ljmp
20209 \family default
20210  and
20211 \family typewriter
20212 lcall
20213 \family default
20214  to
20215 \family typewriter
20216 ajmp
20217 \family default
20218  and
20219 \family typewriter
20220 acall
20221 \layout Verse
20222
20223
20224 \family typewriter
20225 replace { lcall %1 } by { acall %1 }
20226 \newline
20227 replace { ljmp %1 } by { ajmp %1 }
20228 \layout Standard
20229
20230 The
20231 \emph on
20232 inline-assembler code
20233 \emph default
20234  is also passed through the peep hole optimizer, thus the peephole optimizer
20235  can also be used as an assembly level macro expander.
20236  The rules themselves are MCU dependent whereas the rule language infra-structur
20237 e is MCU independent.
20238  Peephole optimization rules for other MCU can be easily programmed using
20239  the rule language.
20240 \newline
20241
20242 \newline
20243 The syntax for a rule is as follows:
20244 \layout Verse
20245
20246
20247 \family typewriter
20248 rule := replace [ restart ] '{' <assembly sequence> '
20249 \backslash
20250 n'
20251 \newline
20252 \SpecialChar ~
20253  \SpecialChar ~
20254  \SpecialChar ~
20255  \SpecialChar ~
20256  \SpecialChar ~
20257  \SpecialChar ~
20258  \SpecialChar ~
20259  \SpecialChar ~
20260  \SpecialChar ~
20261  \SpecialChar ~
20262  \SpecialChar ~
20263  \SpecialChar ~
20264  \SpecialChar ~
20265  \SpecialChar ~
20266  '}' by '{' '
20267 \backslash
20268 n'
20269 \newline
20270 \SpecialChar ~
20271  \SpecialChar ~
20272  \SpecialChar ~
20273  \SpecialChar ~
20274  \SpecialChar ~
20275  \SpecialChar ~
20276  \SpecialChar ~
20277  \SpecialChar ~
20278  \SpecialChar ~
20279  \SpecialChar ~
20280  \SpecialChar ~
20281  \SpecialChar ~
20282  \SpecialChar ~
20283  \SpecialChar ~
20284  \SpecialChar ~
20285  \SpecialChar ~
20286  <assembly sequence> '
20287 \backslash
20288 n'
20289 \newline
20290 \SpecialChar ~
20291  \SpecialChar ~
20292  \SpecialChar ~
20293  \SpecialChar ~
20294  \SpecialChar ~
20295  \SpecialChar ~
20296  \SpecialChar ~
20297  \SpecialChar ~
20298  \SpecialChar ~
20299  \SpecialChar ~
20300  \SpecialChar ~
20301  \SpecialChar ~
20302  \SpecialChar ~
20303  \SpecialChar ~
20304  '}' [if <functionName> ] '
20305 \backslash
20306 n'
20307 \layout Standard
20308
20309 <assembly sequence> := assembly instruction (each instruction including
20310  labels must be on a separate line).
20311 \newline
20312
20313 \newline
20314 The optimizer will apply to the rules one by one from the top in the sequence
20315  of their appearance, it will terminate when all rules are exhausted.
20316  If the 'restart' option is specified, then the optimizer will start matching
20317  the rules again from the top, this option for a rule is expensive (performance)
20318 , it is intended to be used in situations where a transformation will trigger
20319  the same rule again.
20320  An example of this (not a good one, it has side effects) is the following
20321  rule:
20322 \layout Verse
20323
20324
20325 \family typewriter
20326 replace restart {
20327 \newline
20328 \SpecialChar ~
20329 \SpecialChar ~
20330 pop %1
20331 \newline
20332 \SpecialChar ~
20333 \SpecialChar ~
20334 push %1 } by {
20335 \newline
20336 \SpecialChar ~
20337 \SpecialChar ~
20338 ; nop
20339 \newline
20340 }
20341 \layout Standard
20342
20343 Note that the replace pattern cannot be a blank, but can be a comment line.
20344  Without the 'restart' option only the innermost 'pop' 'push' pair would
20345  be eliminated, i.e.:
20346 \layout Verse
20347
20348
20349 \family typewriter
20350 pop ar1
20351 \newline
20352 pop ar2
20353 \newline
20354 push ar2
20355 \newline
20356 push ar1
20357 \layout Standard
20358
20359 would result in:
20360 \layout Verse
20361
20362
20363 \family typewriter
20364 pop ar1
20365 \newline
20366 ; nop
20367 \newline
20368 push ar1
20369 \layout Standard
20370
20371
20372 \emph on
20373 with
20374 \emph default
20375  the restart option the rule will be applied again to the resulting code
20376  and then all the pop-push pairs will be eliminated to yield:
20377 \layout Verse
20378
20379
20380 \family typewriter
20381 ; nop
20382 \newline
20383 ; nop
20384 \layout Standard
20385
20386 A conditional function can be attached to a rule.
20387  Attaching rules are somewhat more involved, let me illustrate this with
20388  an example.
20389 \layout Verse
20390
20391
20392 \family typewriter
20393 replace {
20394 \newline
20395 \SpecialChar ~
20396  \SpecialChar ~
20397  \SpecialChar ~
20398 ljmp %5
20399 \newline
20400 %2:
20401 \newline
20402 } by {
20403 \newline
20404 \SpecialChar ~
20405  \SpecialChar ~
20406  \SpecialChar ~
20407 sjmp %5
20408 \newline
20409 %2:
20410 \newline
20411 } if labelInRange
20412 \layout Standard
20413
20414 The optimizer does a look-up of a function name table defined in function
20415
20416 \emph on
20417 callFuncByName
20418 \emph default
20419  in the source file SDCCpeeph.c, with the name
20420 \emph on
20421 labelInRange
20422 \emph default
20423 .
20424  If it finds a corresponding entry the function is called.
20425  Note there can be no parameters specified for these functions, in this
20426  case the use of
20427 \emph on
20428 %5
20429 \emph default
20430  is crucial, since the function
20431 \emph on
20432 labelInRange
20433 \emph default
20434  expects to find the label in that particular variable (the hash table containin
20435 g the variable bindings is passed as a parameter).
20436  If you want to code more such functions, take a close look at the function
20437  labelInRange and the calling mechanism in source file SDCCpeeph.c.
20438  Currently implemented are
20439 \emph on
20440 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
20441  24bitMode, portIsDS390, 24bitModeAndPortDS390
20442 \emph default
20443 and
20444 \emph on
20445  notVolatile
20446 \emph default
20447 .
20448 \layout Standard
20449
20450 I know this whole thing is a little kludgey, but maybe some day we will
20451  have some better means.
20452  If you are looking at this file, you will see the default rules that are
20453  compiled into the compiler, you can add your own rules in the default set
20454  there if you get tired of specifying the -
20455 \begin_inset ERT
20456 status Collapsed
20457
20458 \layout Standard
20459
20460 \backslash
20461 /
20462 \end_inset
20463
20464 -peep-file option.
20465 \layout Section
20466
20467 ANSI-Compliance
20468 \begin_inset LatexCommand \index{ANSI-compliance}
20469
20470 \end_inset
20471
20472
20473 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
20474
20475 \end_inset
20476
20477
20478 \layout Standard
20479
20480 Deviations from the compliance:
20481 \layout Itemize
20482
20483 functions are not always reentrant
20484 \begin_inset LatexCommand \index{reentrant}
20485
20486 \end_inset
20487
20488 .
20489 \layout Itemize
20490
20491 structures cannot be assigned values directly, cannot be passed as function
20492  parameters or assigned to each other and cannot be a return value from
20493  a function, e.g.:
20494 \begin_deeper
20495 \layout Verse
20496
20497
20498 \family typewriter
20499 struct s { ...
20500  };
20501 \newline
20502 struct s s1, s2;
20503 \newline
20504 foo()
20505 \newline
20506 {
20507 \newline
20508 \SpecialChar ~
20509 \SpecialChar ~
20510 \SpecialChar ~
20511 \SpecialChar ~
20512 ...
20513
20514 \newline
20515 \SpecialChar ~
20516 \SpecialChar ~
20517 \SpecialChar ~
20518 \SpecialChar ~
20519 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
20520 \newline
20521 \SpecialChar ~
20522 \SpecialChar ~
20523 \SpecialChar ~
20524 \SpecialChar ~
20525 ...
20526
20527 \newline
20528 }
20529 \newline
20530 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
20531  */
20532 \newline
20533 {
20534 \newline
20535 \SpecialChar ~
20536 \SpecialChar ~
20537 \SpecialChar ~
20538 \SpecialChar ~
20539 struct s rets;
20540 \newline
20541 \SpecialChar ~
20542 \SpecialChar ~
20543 \SpecialChar ~
20544 \SpecialChar ~
20545 ...
20546
20547 \newline
20548 \SpecialChar ~
20549 \SpecialChar ~
20550 \SpecialChar ~
20551 \SpecialChar ~
20552 return rets;/* is invalid in SDCC although allowed in ANSI */
20553 \newline
20554 }
20555 \end_deeper
20556 \layout Itemize
20557
20558 'long long
20559 \begin_inset LatexCommand \index{long long (not supported)}
20560
20561 \end_inset
20562
20563 ' (64 bit integers
20564 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
20565
20566 \end_inset
20567
20568 ) not supported.
20569 \layout Itemize
20570
20571 'double
20572 \begin_inset LatexCommand \index{double (not supported)}
20573
20574 \end_inset
20575
20576 ' precision floating point
20577 \begin_inset LatexCommand \index{Floating point support}
20578
20579 \end_inset
20580
20581 not supported.
20582 \layout Itemize
20583
20584 No support for setjmp
20585 \begin_inset LatexCommand \index{setjmp (not supported)}
20586
20587 \end_inset
20588
20589  and longjmp
20590 \begin_inset LatexCommand \index{longjmp (not supported)}
20591
20592 \end_inset
20593
20594  (for now).
20595 \layout Itemize
20596
20597 Old K&R style
20598 \begin_inset LatexCommand \index{K\&R style}
20599
20600 \end_inset
20601
20602  function declarations are NOT allowed.
20603 \begin_deeper
20604 \layout Verse
20605
20606
20607 \family typewriter
20608 foo(i,j) /* this old style of function declarations */
20609 \newline
20610 int i,j; /* are valid in ANSI but not valid in SDCC */
20611 \newline
20612 {
20613 \newline
20614 \SpecialChar ~
20615 \SpecialChar ~
20616 \SpecialChar ~
20617 \SpecialChar ~
20618 ...
20619
20620 \newline
20621 }
20622 \end_deeper
20623 \layout Section
20624
20625 Cyclomatic Complexity
20626 \begin_inset LatexCommand \index{Cyclomatic complexity}
20627
20628 \end_inset
20629
20630
20631 \layout Standard
20632
20633 Cyclomatic complexity of a function is defined as the number of independent
20634  paths the program can take during execution of the function.
20635  This is an important number since it defines the number test cases you
20636  have to generate to validate the function.
20637  The accepted industry standard for complexity number is 10, if the cyclomatic
20638  complexity reported by SDCC exceeds 10 you should think about simplification
20639  of the function logic.
20640  Note that the complexity level is not related to the number of lines of
20641  code in a function.
20642  Large functions can have low complexity, and small functions can have large
20643  complexity levels.
20644
20645 \newline
20646
20647 \newline
20648 SDCC uses the following formula to compute the complexity:
20649 \newline
20650
20651 \layout Standard
20652
20653 complexity = (number of edges in control flow graph) - (number of nodes
20654  in control flow graph) + 2;
20655 \newline
20656
20657 \newline
20658 Having said that the industry standard is 10, you should be aware that in
20659  some cases it be may unavoidable to have a complexity level of less than
20660  10.
20661  For example if you have switch statement with more than 10 case labels,
20662  each case label adds one to the complexity level.
20663  The complexity level is by no means an absolute measure of the algorithmic
20664  complexity of the function, it does however provide a good starting point
20665  for which functions you might look at for further optimization.
20666 \layout Section
20667
20668 Retargetting for other Processors
20669 \layout Standard
20670
20671 The issues for retargetting the compiler are far too numerous to be covered
20672  by this document.
20673  What follows is a brief description of each of the seven phases of the
20674  compiler and its MCU dependency.
20675 \layout Itemize
20676
20677 Parsing the source and building the annotated parse tree.
20678  This phase is largely MCU independent (except for the language extensions).
20679  Syntax & semantic checks are also done in this phase, along with some initial
20680  optimizations like back patching labels and the pattern matching optimizations
20681  like bit-rotation etc.
20682 \layout Itemize
20683
20684 The second phase involves generating an intermediate code which can be easy
20685  manipulated during the later phases.
20686  This phase is entirely MCU independent.
20687  The intermediate code generation assumes the target machine has unlimited
20688  number of registers, and designates them with the name iTemp.
20689  The compiler can be made to dump a human readable form of the code generated
20690  by using the -
20691 \begin_inset ERT
20692 status Collapsed
20693
20694 \layout Standard
20695
20696 \backslash
20697 /
20698 \end_inset
20699
20700 -dumpraw option.
20701 \layout Itemize
20702
20703 This phase does the bulk of the standard optimizations and is also MCU independe
20704 nt.
20705  This phase can be broken down into several sub-phases:
20706 \newline
20707
20708 \newline
20709 Break down intermediate code (iCode) into basic blocks.
20710 \newline
20711 Do control flow & data flow analysis on the basic blocks.
20712 \newline
20713 Do local common subexpression elimination, then global subexpression elimination
20714 \newline
20715 Dead code elimination
20716 \newline
20717 Loop optimizations
20718 \newline
20719 If loop optimizations caused any changes then do 'global subexpression eliminati
20720 on' and 'dead code elimination' again.
20721 \layout Itemize
20722
20723 This phase determines the live-ranges; by live range I mean those iTemp
20724  variables defined by the compiler that still survive after all the optimization
20725 s.
20726  Live range analysis
20727 \begin_inset LatexCommand \index{Live range analysis}
20728
20729 \end_inset
20730
20731  is essential for register allocation, since these computation determines
20732  which of these iTemps will be assigned to registers, and for how long.
20733 \layout Itemize
20734
20735 Phase five is register allocation.
20736  There are two parts to this process.
20737 \newline
20738
20739 \newline
20740 The first part I call 'register packing' (for lack of a better term).
20741  In this case several MCU specific expression folding is done to reduce
20742  register pressure.
20743 \newline
20744
20745 \newline
20746 The second part is more MCU independent and deals with allocating registers
20747  to the remaining live ranges.
20748  A lot of MCU specific code does creep into this phase because of the limited
20749  number of index registers available in the 8051.
20750 \layout Itemize
20751
20752 The Code generation phase is (unhappily), entirely MCU dependent and very
20753  little (if any at all) of this code can be reused for other MCU.
20754  However the scheme for allocating a homogenized assembler operand for each
20755  iCode operand may be reused.
20756 \layout Itemize
20757
20758 As mentioned in the optimization section the peep-hole optimizer is rule
20759  based system, which can reprogrammed for other MCUs.
20760 \layout Chapter
20761
20762 Compiler internals
20763 \begin_inset LatexCommand \index{Compiler internals}
20764
20765 \end_inset
20766
20767
20768 \layout Section
20769
20770 The anatomy of the compiler
20771 \begin_inset LatexCommand \label{sub:The-anatomy-of}
20772
20773 \end_inset
20774
20775
20776 \layout Standard
20777
20778
20779 \shape italic
20780 This is an excerpt from an article published in Circuit Cellar Magazine
20781  in august 2000.
20782  It's a little outdated (the compiler is much more efficient now and user/develo
20783 per friendly), but pretty well exposes the guts of it all.
20784 \shape default
20785
20786 \newline
20787
20788 \newline
20789 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
20790  It is fairly easy to retarget for other 8-bit MCU.
20791  Here we take a look at some of the internals of the compiler.
20792
20793 \layout Paragraph*
20794
20795 Parsing
20796 \begin_inset LatexCommand \index{Parsing}
20797
20798 \end_inset
20799
20800
20801 \layout Standard
20802
20803 Parsing the input source file and creating an AST (Annotated Syntax Tree
20804 \begin_inset LatexCommand \index{Annotated syntax tree}
20805
20806 \end_inset
20807
20808 ).
20809  This phase also involves propagating types (annotating each node of the
20810  parse tree with type information) and semantic analysis.
20811  There are some MCU specific parsing rules.
20812  For example the storage classes, the extended storage classes are MCU specific
20813  while there may be a xdata storage class for 8051 there is no such storage
20814  class for z80 or Atmel AVR.
20815  SDCC allows MCU specific storage class extensions, i.e.
20816  xdata will be treated as a storage class specifier when parsing 8051 C
20817  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
20818  C code.
20819 \layout Paragraph*
20820
20821 Generating iCode
20822 \begin_inset LatexCommand \index{iCode}
20823
20824 \end_inset
20825
20826
20827 \layout Standard
20828
20829 Intermediate code generation.
20830  In this phase the AST is broken down into three-operand form (iCode).
20831  These three operand forms are represented as doubly linked lists.
20832  ICode is the term given to the intermediate form generated by the compiler.
20833  ICode example section shows some examples of iCode generated for some simple
20834  C source functions.
20835 \layout Paragraph*
20836
20837 Optimizations
20838 \begin_inset LatexCommand \index{Optimizations}
20839
20840 \end_inset
20841
20842 .
20843 \layout Standard
20844
20845 Bulk of the target independent optimizations is performed in this phase.
20846  The optimizations include constant propagation, common sub-expression eliminati
20847 on, loop invariant code movement, strength reduction of loop induction variables
20848  and dead-code elimination.
20849 \layout Paragraph*
20850
20851 Live range analysis
20852 \begin_inset LatexCommand \index{Live range analysis}
20853
20854 \end_inset
20855
20856
20857 \layout Standard
20858
20859 During intermediate code generation phase, the compiler assumes the target
20860  machine has infinite number of registers and generates a lot of temporary
20861  variables.
20862  The live range computation determines the lifetime of each of these compiler-ge
20863 nerated temporaries.
20864  A picture speaks a thousand words.
20865  ICode example sections show the live range annotations for each of the
20866  operand.
20867  It is important to note here, each iCode is assigned a number in the order
20868  of its execution in the function.
20869  The live ranges are computed in terms of these numbers.
20870  The from number is the number of the iCode which first defines the operand
20871  and the to number signifies the iCode which uses this operand last.
20872 \layout Paragraph*
20873
20874 Register Allocation
20875 \begin_inset LatexCommand \index{Register allocation}
20876
20877 \end_inset
20878
20879
20880 \layout Standard
20881
20882 The register allocation determines the type and number of registers needed
20883  by each operand.
20884  In most MCUs only a few registers can be used for indirect addressing.
20885  In case of 8051 for example the registers R0 & R1 can be used to indirectly
20886  address the internal ram and DPTR to indirectly address the external ram.
20887  The compiler will try to allocate the appropriate register to pointer variables
20888  if it can.
20889  ICode example section shows the operands annotated with the registers assigned
20890  to them.
20891  The compiler will try to keep operands in registers as much as possible;
20892  there are several schemes the compiler uses to do achieve this.
20893  When the compiler runs out of registers the compiler will check to see
20894  if there are any live operands which is not used or defined in the current
20895  basic block being processed, if there are any found then it will push that
20896  operand and use the registers in this block, the operand will then be popped
20897  at the end of the basic block.
20898
20899 \layout Standard
20900
20901 There are other MCU specific considerations in this phase.
20902  Some MCUs have an accumulator; very short-lived operands could be assigned
20903  to the accumulator instead of a general-purpose register.
20904 \layout Paragraph*
20905
20906 Code generation
20907 \layout Standard
20908
20909 Figure II gives a table of iCode operations supported by the compiler.
20910  The code generation involves translating these operations into corresponding
20911  assembly code for the processor.
20912  This sounds overly simple but that is the essence of code generation.
20913  Some of the iCode operations are generated on a MCU specific manner for
20914  example, the z80 port does not use registers to pass parameters so the
20915  SEND and RECV iCode operations will not be generated, and it also does
20916  not support JUMPTABLES.
20917
20918 \newline
20919
20920 \series bold
20921 \shape italic
20922 \color red
20923 <Where is Figure II ?>
20924 \layout Paragraph*
20925
20926 ICode Example
20927 \begin_inset LatexCommand \index{iCode}
20928
20929 \end_inset
20930
20931
20932 \layout Standard
20933
20934 This section shows some details of iCode.
20935  The example C code does not do anything useful; it is used as an example
20936  to illustrate the intermediate code generated by the compiler.
20937 \layout Verse
20938
20939
20940 \family typewriter
20941 1.\SpecialChar ~
20942 xdata int * p;
20943 \newline
20944 2.\SpecialChar ~
20945 int gint;
20946 \newline
20947 3.\SpecialChar ~
20948 /* This function does nothing useful.
20949  It is used
20950 \newline
20951 4.\SpecialChar ~
20952 \SpecialChar ~
20953 \SpecialChar ~
20954 \SpecialChar ~
20955 for the purpose of explaining iCode */
20956 \newline
20957 5.\SpecialChar ~
20958 short function (data int *x)
20959 \newline
20960 6.\SpecialChar ~
20961 {
20962 \newline
20963 7.\SpecialChar ~
20964 \SpecialChar ~
20965 \SpecialChar ~
20966 short i=10; \SpecialChar ~
20967 \SpecialChar ~
20968 /* dead initialization eliminated */
20969 \newline
20970 8.\SpecialChar ~
20971 \SpecialChar ~
20972 \SpecialChar ~
20973 short sum=10; /* dead initialization eliminated */
20974 \newline
20975 9.\SpecialChar ~
20976 \SpecialChar ~
20977 \SpecialChar ~
20978 short mul;
20979 \newline
20980 10.\SpecialChar ~
20981 \SpecialChar ~
20982 int j ;
20983 \newline
20984 11.\SpecialChar ~
20985 \SpecialChar ~
20986 while (*x) *x++ = *p++;
20987 \newline
20988 12.\SpecialChar ~
20989 \SpecialChar ~
20990 \SpecialChar ~
20991 \SpecialChar ~
20992 sum = 0 ;
20993 \newline
20994 13.\SpecialChar ~
20995 \SpecialChar ~
20996 mul = 0;
20997 \newline
20998 14.\SpecialChar ~
20999 \SpecialChar ~
21000 /* compiler detects i,j to be induction variables */
21001 \newline
21002 15.\SpecialChar ~
21003 \SpecialChar ~
21004 for (i = 0, j = 10 ; i < 10 ; i++, j
21005 \family default
21006 -
21007 \begin_inset ERT
21008 status Collapsed
21009
21010 \layout Standard
21011
21012 \backslash
21013 /
21014 \end_inset
21015
21016 -
21017 \family typewriter
21018 ) {
21019 \newline
21020 16.\SpecialChar ~
21021 \SpecialChar ~
21022 \SpecialChar ~
21023 \SpecialChar ~
21024 sum += i;
21025 \newline
21026 17.\SpecialChar ~
21027 \SpecialChar ~
21028 \SpecialChar ~
21029 \SpecialChar ~
21030 mul += i * 3; \SpecialChar ~
21031 \SpecialChar ~
21032 /* this multiplication remains */
21033 \newline
21034 18.\SpecialChar ~
21035 \SpecialChar ~
21036 \SpecialChar ~
21037 \SpecialChar ~
21038 gint += j * 3;\SpecialChar ~
21039 \SpecialChar ~
21040 /* this multiplication changed to addition */
21041 \newline
21042 19.\SpecialChar ~
21043 \SpecialChar ~
21044 }
21045 \newline
21046 20.\SpecialChar ~
21047 \SpecialChar ~
21048 return sum+mul;
21049 \newline
21050 21.\SpecialChar ~
21051 }
21052 \layout Standard
21053
21054 In addition to the operands each iCode contains information about the filename
21055  and line it corresponds to in the source file.
21056  The first field in the listing should be interpreted as follows:
21057 \newline
21058
21059 \shape italic
21060 \size footnotesize
21061 Filename(linenumber: iCode Execution sequence number : ICode hash table
21062  key : loop depth of the iCode).
21063 \shape default
21064 \size default
21065
21066 \newline
21067 Then follows the human readable form of the ICode operation.
21068  Each operand of this triplet form can be of three basic types a) compiler
21069  generated temporary b) user defined variable c) a constant value.
21070  Note that local variables and parameters are replaced by compiler generated
21071  temporaries.
21072  Live ranges
21073 \begin_inset LatexCommand \index{Live range analysis}
21074
21075 \end_inset
21076
21077  are computed only for temporaries (i.e.
21078  live ranges are not computed for global variables).
21079  Registers
21080 \begin_inset LatexCommand \index{Register allocation}
21081
21082 \end_inset
21083
21084  are allocated for temporaries only.
21085  Operands are formatted in the following manner:
21086 \newline
21087
21088 \shape italic
21089 \size footnotesize
21090 Operand Name [lr live-from : live-to ] { type information } [ registers
21091  allocated ].
21092 \shape default
21093 \size default
21094
21095 \newline
21096 As mentioned earlier the live ranges are computed in terms of the execution
21097  sequence number of the iCodes, for example
21098 \newline
21099 the iTemp0 is live from (i.e.
21100  first defined in iCode with execution sequence number 3, and is last used
21101  in the iCode with sequence number 5).
21102  For induction variables such as iTemp21 the live range computation extends
21103  the lifetime from the start to the end of the loop.
21104 \newline
21105 The register allocator used the live range information to allocate registers,
21106  the same registers may be used for different temporaries if their live
21107  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
21108  iTemp17 since their live ranges do not overlap.
21109  In addition the allocator also takes into consideration the type and usage
21110  of a temporary, for example itemp6 is a pointer to near space and is used
21111  as to fetch data from (i.e.
21112  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
21113  Some short lived temporaries are allocated to special registers which have
21114  meaning to the code generator e.g.
21115  iTemp13 is allocated to a pseudo register CC which tells the back end that
21116  the temporary is used only for a conditional jump the code generation makes
21117  use of this information to optimize a compare and jump ICode.
21118 \newline
21119 There are several loop optimizations
21120 \begin_inset LatexCommand \index{Loop optimization}
21121
21122 \end_inset
21123
21124  performed by the compiler.
21125  It can detect induction variables iTemp21(i) and iTemp23(j).
21126  Also note the compiler does selective strength reduction
21127 \begin_inset LatexCommand \index{Strength reduction}
21128
21129 \end_inset
21130
21131 , i.e.
21132  the multiplication of an induction variable in line 18 (gint = j * 3) is
21133  changed to addition, a new temporary iTemp17 is allocated and assigned
21134  a initial value, a constant 3 is then added for each iteration of the loop.
21135  The compiler does not change the multiplication
21136 \begin_inset LatexCommand \index{Multiplication}
21137
21138 \end_inset
21139
21140  in line 17 however since the processor does support an 8 * 8 bit multiplication.
21141 \newline
21142 Note the dead code elimination
21143 \begin_inset LatexCommand \index{Dead-code elimination}
21144
21145 \end_inset
21146
21147  optimization eliminated the dead assignments in line 7 & 8 to I and sum
21148  respectively.
21149 \newline
21150
21151 \layout Standard
21152
21153
21154 \size footnotesize
21155 Sample.c (5:1:0:0) _entry($9) :
21156 \layout Standard
21157
21158
21159 \size footnotesize
21160 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
21161 \layout Standard
21162
21163
21164 \size footnotesize
21165 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
21166 \layout Standard
21167
21168
21169 \size footnotesize
21170 Sample.c(11:4:53:0) preHeaderLbl0($11) :
21171 \layout Standard
21172
21173
21174 \size footnotesize
21175 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
21176  * int}[r2]
21177 \layout Standard
21178
21179
21180 \size footnotesize
21181 Sample.c(11:6:5:1) _whilecontinue_0($1) :
21182 \layout Standard
21183
21184
21185 \size footnotesize
21186 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
21187  int}[r0]]
21188 \layout Standard
21189
21190
21191 \size footnotesize
21192 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
21193 \layout Standard
21194
21195
21196 \size footnotesize
21197 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
21198  * int}
21199 \layout Standard
21200
21201
21202 \size footnotesize
21203 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
21204  {short}
21205 \layout Standard
21206
21207
21208 \size footnotesize
21209 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
21210  * int}[DPTR]]
21211 \layout Standard
21212
21213
21214 \size footnotesize
21215 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
21216 }[r2 r3]
21217 \layout Standard
21218
21219
21220 \size footnotesize
21221 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
21222  * int}[r0] + 0x2 {short}
21223 \layout Standard
21224
21225
21226 \size footnotesize
21227 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
21228 \layout Standard
21229
21230
21231 \size footnotesize
21232 Sample.c(11:17:21:0)_whilebreak_0($3) :
21233 \layout Standard
21234
21235
21236 \size footnotesize
21237 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
21238 \layout Standard
21239
21240
21241 \size footnotesize
21242 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
21243 \layout Standard
21244
21245
21246 \size footnotesize
21247 Sample.c(15:20:54:0)preHeaderLbl1($13) :
21248 \layout Standard
21249
21250
21251 \size footnotesize
21252 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
21253 \layout Standard
21254
21255
21256 \size footnotesize
21257 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
21258 \layout Standard
21259
21260
21261 \size footnotesize
21262 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
21263 \layout Standard
21264
21265
21266 \size footnotesize
21267 Sample.c(15:24:26:1)_forcond_0($4) :
21268 \layout Standard
21269
21270
21271 \size footnotesize
21272 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
21273  < 0xa {short}
21274 \layout Standard
21275
21276
21277 \size footnotesize
21278 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
21279 \layout Standard
21280
21281
21282 \size footnotesize
21283 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
21284  + ITemp21 [lr21:38]{short}[r4]
21285 \layout Standard
21286
21287
21288 \size footnotesize
21289 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
21290  * 0x3 {short}
21291 \layout Standard
21292
21293
21294 \size footnotesize
21295 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
21296  + iTemp15 [lr29:30]{short}[r1]
21297 \layout Standard
21298
21299
21300 \size footnotesize
21301 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
21302  r0]- 0x3 {short}
21303 \layout Standard
21304
21305
21306 \size footnotesize
21307 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
21308 int}[r7 r0]
21309 \layout Standard
21310
21311
21312 \size footnotesize
21313 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
21314  + 0x1 {short}
21315 \layout Standard
21316
21317
21318 \size footnotesize
21319 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
21320  r6]- 0x1 {short}
21321 \layout Standard
21322
21323
21324 \size footnotesize
21325 Sample.c(19:38:47:1) goto _forcond_0($4)
21326 \layout Standard
21327
21328
21329 \size footnotesize
21330 Sample.c(19:39:48:0)_forbreak_0($7) :
21331 \layout Standard
21332
21333
21334 \size footnotesize
21335 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
21336  + ITemp11 [lr19:40]{short}[r3]
21337 \layout Standard
21338
21339
21340 \size footnotesize
21341 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
21342 \layout Standard
21343
21344
21345 \size footnotesize
21346 Sample.c(20:42:51:0)_return($8) :
21347 \layout Standard
21348
21349
21350 \size footnotesize
21351 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
21352 \size default
21353
21354 \newline
21355
21356 \newline
21357 Finally the code generated for this function:
21358 \newline
21359
21360 \layout Standard
21361
21362
21363 \size footnotesize
21364 .area DSEG (DATA)
21365 \layout Standard
21366
21367
21368 \size footnotesize
21369 _p::
21370 \layout Standard
21371
21372
21373 \size footnotesize
21374 \SpecialChar ~
21375 \SpecialChar ~
21376 .ds 2
21377 \layout Standard
21378
21379
21380 \size footnotesize
21381 _gint::
21382 \layout Standard
21383
21384
21385 \size footnotesize
21386 \SpecialChar ~
21387 \SpecialChar ~
21388 .ds 2
21389 \layout Standard
21390
21391
21392 \size footnotesize
21393 ; sample.c 5
21394 \layout Standard
21395
21396
21397 \size footnotesize
21398 ; ----------------------------------------------
21399 \layout Standard
21400
21401
21402 \size footnotesize
21403 ; function function
21404 \layout Standard
21405
21406
21407 \size footnotesize
21408 ; ----------------------------------------------
21409 \layout Standard
21410
21411
21412 \size footnotesize
21413 _function:
21414 \layout Standard
21415
21416
21417 \size footnotesize
21418 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
21419 \layout Standard
21420
21421
21422 \size footnotesize
21423 \SpecialChar ~
21424 \SpecialChar ~
21425 mov r2,dpl
21426 \layout Standard
21427
21428
21429 \size footnotesize
21430 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
21431 \layout Standard
21432
21433
21434 \size footnotesize
21435 \SpecialChar ~
21436 \SpecialChar ~
21437 mov ar0,r2
21438 \layout Standard
21439
21440
21441 \size footnotesize
21442 ;_whilecontinue_0($1) :
21443 \layout Standard
21444
21445
21446 \size footnotesize
21447 00101$:
21448 \layout Standard
21449
21450
21451 \size footnotesize
21452 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
21453 \layout Standard
21454
21455
21456 \size footnotesize
21457 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
21458 \layout Standard
21459
21460
21461 \size footnotesize
21462 \SpecialChar ~
21463 \SpecialChar ~
21464 mov ar2,@r0
21465 \layout Standard
21466
21467
21468 \size footnotesize
21469 \SpecialChar ~
21470 \SpecialChar ~
21471 inc r0
21472 \layout Standard
21473
21474
21475 \size footnotesize
21476 \SpecialChar ~
21477 \SpecialChar ~
21478 mov ar3,@r0
21479 \layout Standard
21480
21481
21482 \size footnotesize
21483 \SpecialChar ~
21484 \SpecialChar ~
21485 dec r0
21486 \layout Standard
21487
21488
21489 \size footnotesize
21490 \SpecialChar ~
21491 \SpecialChar ~
21492 mov a,r2
21493 \layout Standard
21494
21495
21496 \size footnotesize
21497 \SpecialChar ~
21498 \SpecialChar ~
21499 orl a,r3
21500 \layout Standard
21501
21502
21503 \size footnotesize
21504 \SpecialChar ~
21505 \SpecialChar ~
21506 jz 00103$
21507 \layout Standard
21508
21509
21510 \size footnotesize
21511 00114$:
21512 \layout Standard
21513
21514
21515 \size footnotesize
21516 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
21517 \layout Standard
21518
21519
21520 \size footnotesize
21521 \SpecialChar ~
21522 \SpecialChar ~
21523 mov dpl,_p
21524 \layout Standard
21525
21526
21527 \size footnotesize
21528 \SpecialChar ~
21529 \SpecialChar ~
21530 mov dph,(_p + 1)
21531 \layout Standard
21532
21533
21534 \size footnotesize
21535 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
21536 \layout Standard
21537
21538
21539 \size footnotesize
21540 \SpecialChar ~
21541 \SpecialChar ~
21542 mov a,#0x02
21543 \layout Standard
21544
21545
21546 \size footnotesize
21547 \SpecialChar ~
21548 \SpecialChar ~
21549 add a,_p
21550 \layout Standard
21551
21552
21553 \size footnotesize
21554 \SpecialChar ~
21555 \SpecialChar ~
21556 mov _p,a
21557 \layout Standard
21558
21559
21560 \size footnotesize
21561 \SpecialChar ~
21562 \SpecialChar ~
21563 clr a
21564 \layout Standard
21565
21566
21567 \size footnotesize
21568 \SpecialChar ~
21569 \SpecialChar ~
21570 addc a,(_p + 1)
21571 \layout Standard
21572
21573
21574 \size footnotesize
21575 \SpecialChar ~
21576 \SpecialChar ~
21577 mov (_p + 1),a
21578 \layout Standard
21579
21580
21581 \size footnotesize
21582 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
21583 \layout Standard
21584
21585
21586 \size footnotesize
21587 \SpecialChar ~
21588 \SpecialChar ~
21589 movx a,@dptr
21590 \layout Standard
21591
21592
21593 \size footnotesize
21594 \SpecialChar ~
21595 \SpecialChar ~
21596 mov r2,a
21597 \layout Standard
21598
21599
21600 \size footnotesize
21601 \SpecialChar ~
21602 \SpecialChar ~
21603 inc dptr
21604 \layout Standard
21605
21606
21607 \size footnotesize
21608 \SpecialChar ~
21609 \SpecialChar ~
21610 movx a,@dptr
21611 \layout Standard
21612
21613
21614 \size footnotesize
21615 \SpecialChar ~
21616 \SpecialChar ~
21617 mov r3,a
21618 \layout Standard
21619
21620
21621 \size footnotesize
21622 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
21623 \layout Standard
21624
21625
21626 \size footnotesize
21627 \SpecialChar ~
21628 \SpecialChar ~
21629 mov @r0,ar2
21630 \layout Standard
21631
21632
21633 \size footnotesize
21634 \SpecialChar ~
21635 \SpecialChar ~
21636 inc r0
21637 \layout Standard
21638
21639
21640 \size footnotesize
21641 \SpecialChar ~
21642 \SpecialChar ~
21643 mov @r0,ar3
21644 \layout Standard
21645
21646
21647 \size footnotesize
21648 ; iTemp6 [lr5:16]{_near * int}[r0] =
21649 \layout Standard
21650
21651
21652 \size footnotesize
21653 ; iTemp6 [lr5:16]{_near * int}[r0] +
21654 \layout Standard
21655
21656
21657 \size footnotesize
21658 ; 0x2 {short}
21659 \layout Standard
21660
21661
21662 \size footnotesize
21663 \SpecialChar ~
21664 \SpecialChar ~
21665 inc r0
21666 \layout Standard
21667
21668
21669 \size footnotesize
21670 ; goto _whilecontinue_0($1)
21671 \layout Standard
21672
21673
21674 \size footnotesize
21675 \SpecialChar ~
21676 \SpecialChar ~
21677 sjmp 00101$
21678 \layout Standard
21679
21680
21681 \size footnotesize
21682 ; _whilebreak_0($3) :
21683 \layout Standard
21684
21685
21686 \size footnotesize
21687 00103$:
21688 \layout Standard
21689
21690
21691 \size footnotesize
21692 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
21693 \layout Standard
21694
21695
21696 \size footnotesize
21697 \SpecialChar ~
21698 \SpecialChar ~
21699 mov r2,#0x00
21700 \layout Standard
21701
21702
21703 \size footnotesize
21704 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
21705 \layout Standard
21706
21707
21708 \size footnotesize
21709 \SpecialChar ~
21710 \SpecialChar ~
21711 mov r3,#0x00
21712 \layout Standard
21713
21714
21715 \size footnotesize
21716 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
21717 \layout Standard
21718
21719
21720 \size footnotesize
21721 \SpecialChar ~
21722 \SpecialChar ~
21723 mov r4,#0x00
21724 \layout Standard
21725
21726
21727 \size footnotesize
21728 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
21729 \layout Standard
21730
21731
21732 \size footnotesize
21733 \SpecialChar ~
21734 \SpecialChar ~
21735 mov r5,#0x0A
21736 \layout Standard
21737
21738
21739 \size footnotesize
21740 \SpecialChar ~
21741 \SpecialChar ~
21742 mov r6,#0x00
21743 \layout Standard
21744
21745
21746 \size footnotesize
21747 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
21748 \layout Standard
21749
21750
21751 \size footnotesize
21752 \SpecialChar ~
21753 \SpecialChar ~
21754 mov r7,#0x1E
21755 \layout Standard
21756
21757
21758 \size footnotesize
21759 \SpecialChar ~
21760 \SpecialChar ~
21761 mov r0,#0x00
21762 \layout Standard
21763
21764
21765 \size footnotesize
21766 ; _forcond_0($4) :
21767 \layout Standard
21768
21769
21770 \size footnotesize
21771 00104$:
21772 \layout Standard
21773
21774
21775 \size footnotesize
21776 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
21777 \layout Standard
21778
21779
21780 \size footnotesize
21781 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
21782 \layout Standard
21783
21784
21785 \size footnotesize
21786 \SpecialChar ~
21787 \SpecialChar ~
21788 clr c
21789 \layout Standard
21790
21791
21792 \size footnotesize
21793 \SpecialChar ~
21794 \SpecialChar ~
21795 mov a,r4
21796 \layout Standard
21797
21798
21799 \size footnotesize
21800 \SpecialChar ~
21801 \SpecialChar ~
21802 xrl a,#0x80
21803 \layout Standard
21804
21805
21806 \size footnotesize
21807 \SpecialChar ~
21808 \SpecialChar ~
21809 subb a,#0x8a
21810 \layout Standard
21811
21812
21813 \size footnotesize
21814 \SpecialChar ~
21815 \SpecialChar ~
21816 jnc 00107$
21817 \layout Standard
21818
21819
21820 \size footnotesize
21821 00115$:
21822 \layout Standard
21823
21824
21825 \size footnotesize
21826 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
21827 \layout Standard
21828
21829
21830 \size footnotesize
21831 ; iTemp21 [lr21:38]{short}[r4]
21832 \layout Standard
21833
21834
21835 \size footnotesize
21836 \SpecialChar ~
21837 \SpecialChar ~
21838 mov a,r4
21839 \layout Standard
21840
21841
21842 \size footnotesize
21843 \SpecialChar ~
21844 \SpecialChar ~
21845 add a,r2
21846 \layout Standard
21847
21848
21849 \size footnotesize
21850 \SpecialChar ~
21851 \SpecialChar ~
21852 mov r2,a
21853 \layout Standard
21854
21855
21856 \size footnotesize
21857 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
21858 \layout Standard
21859
21860
21861 \size footnotesize
21862 \SpecialChar ~
21863 \SpecialChar ~
21864 mov b,#0x03
21865 \layout Standard
21866
21867
21868 \size footnotesize
21869 \SpecialChar ~
21870 \SpecialChar ~
21871 mov a,r4
21872 \layout Standard
21873
21874
21875 \size footnotesize
21876 \SpecialChar ~
21877 \SpecialChar ~
21878 mul ab
21879 \layout Standard
21880
21881
21882 \size footnotesize
21883 \SpecialChar ~
21884 \SpecialChar ~
21885 mov r1,a
21886 \layout Standard
21887
21888
21889 \size footnotesize
21890 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
21891 \layout Standard
21892
21893
21894 \size footnotesize
21895 ; iTemp15 [lr29:30]{short}[r1]
21896 \layout Standard
21897
21898
21899 \size footnotesize
21900 \SpecialChar ~
21901 \SpecialChar ~
21902 add a,r3
21903 \layout Standard
21904
21905
21906 \size footnotesize
21907 \SpecialChar ~
21908 \SpecialChar ~
21909 mov r3,a
21910 \layout Standard
21911
21912
21913 \size footnotesize
21914 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
21915 \layout Standard
21916
21917
21918 \size footnotesize
21919 \SpecialChar ~
21920 \SpecialChar ~
21921 mov a,r7
21922 \layout Standard
21923
21924
21925 \size footnotesize
21926 \SpecialChar ~
21927 \SpecialChar ~
21928 add a,#0xfd
21929 \layout Standard
21930
21931
21932 \size footnotesize
21933 \SpecialChar ~
21934 \SpecialChar ~
21935 mov r7,a
21936 \layout Standard
21937
21938
21939 \size footnotesize
21940 \SpecialChar ~
21941 \SpecialChar ~
21942 mov a,r0
21943 \layout Standard
21944
21945
21946 \size footnotesize
21947 \SpecialChar ~
21948 \SpecialChar ~
21949 addc a,#0xff
21950 \layout Standard
21951
21952
21953 \size footnotesize
21954 \SpecialChar ~
21955 \SpecialChar ~
21956 mov r0,a
21957 \layout Standard
21958
21959
21960 \size footnotesize
21961 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
21962 \layout Standard
21963
21964
21965 \size footnotesize
21966 \SpecialChar ~
21967 \SpecialChar ~
21968 mov a,r7
21969 \layout Standard
21970
21971
21972 \size footnotesize
21973 \SpecialChar ~
21974 \SpecialChar ~
21975 add a,_gint
21976 \layout Standard
21977
21978
21979 \size footnotesize
21980 \SpecialChar ~
21981 \SpecialChar ~
21982 mov _gint,a
21983 \layout Standard
21984
21985
21986 \size footnotesize
21987 \SpecialChar ~
21988 \SpecialChar ~
21989 mov a,r0
21990 \layout Standard
21991
21992
21993 \size footnotesize
21994 \SpecialChar ~
21995 \SpecialChar ~
21996 addc a,(_gint + 1)
21997 \layout Standard
21998
21999
22000 \size footnotesize
22001 \SpecialChar ~
22002 \SpecialChar ~
22003 mov (_gint + 1),a
22004 \layout Standard
22005
22006
22007 \size footnotesize
22008 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
22009 \layout Standard
22010
22011
22012 \size footnotesize
22013 \SpecialChar ~
22014 \SpecialChar ~
22015 inc r4
22016 \layout Standard
22017
22018
22019 \size footnotesize
22020 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
22021 \layout Standard
22022
22023
22024 \size footnotesize
22025 \SpecialChar ~
22026 \SpecialChar ~
22027 dec r5
22028 \layout Standard
22029
22030
22031 \size footnotesize
22032 \SpecialChar ~
22033 \SpecialChar ~
22034 cjne r5,#0xff,00104$
22035 \layout Standard
22036
22037
22038 \size footnotesize
22039 \SpecialChar ~
22040 \SpecialChar ~
22041 dec r6
22042 \layout Standard
22043
22044
22045 \size footnotesize
22046 ; goto _forcond_0($4)
22047 \layout Standard
22048
22049
22050 \size footnotesize
22051 \SpecialChar ~
22052 \SpecialChar ~
22053 sjmp 00104$
22054 \layout Standard
22055
22056
22057 \size footnotesize
22058 ; _forbreak_0($7) :
22059 \layout Standard
22060
22061
22062 \size footnotesize
22063 00107$:
22064 \layout Standard
22065
22066
22067 \size footnotesize
22068 ; ret iTemp24 [lr40:41]{short}
22069 \layout Standard
22070
22071
22072 \size footnotesize
22073 \SpecialChar ~
22074 \SpecialChar ~
22075 mov a,r3
22076 \layout Standard
22077
22078
22079 \size footnotesize
22080 \SpecialChar ~
22081 \SpecialChar ~
22082 add a,r2
22083 \layout Standard
22084
22085
22086 \size footnotesize
22087 \SpecialChar ~
22088 \SpecialChar ~
22089 mov dpl,a
22090 \layout Standard
22091
22092
22093 \size footnotesize
22094 ; _return($8) :
22095 \layout Standard
22096
22097
22098 \size footnotesize
22099 00108$:
22100 \layout Standard
22101
22102
22103 \size footnotesize
22104 \SpecialChar ~
22105 \SpecialChar ~
22106 ret
22107 \newline
22108
22109 \layout Section
22110
22111 A few words about basic block successors, predecessors and dominators
22112 \layout Standard
22113
22114 Successors are basic blocks
22115 \begin_inset LatexCommand \index{Basic blocks}
22116
22117 \end_inset
22118
22119  that might execute after this basic block.
22120 \newline
22121 Predecessors are basic blocks that might execute before reaching this basic
22122  block.
22123 \newline
22124 Dominators are basic blocks that WILL execute before reaching this basic
22125  block.
22126 \newline
22127
22128 \layout Standard
22129
22130 [basic block 1]
22131 \layout Standard
22132
22133 if (something)
22134 \layout Standard
22135
22136 \SpecialChar ~
22137 \SpecialChar ~
22138 \SpecialChar ~
22139 \SpecialChar ~
22140 [basic block 2]
22141 \layout Standard
22142
22143 else
22144 \layout Standard
22145
22146 \SpecialChar ~
22147 \SpecialChar ~
22148 \SpecialChar ~
22149 \SpecialChar ~
22150 [basic block 3]
22151 \layout Standard
22152
22153 [basic block 4]
22154 \newline
22155
22156 \layout Standard
22157
22158 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
22159 \layout Standard
22160
22161 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
22162 \layout Standard
22163
22164 c) domVect of [BB4] = BB1 ...
22165  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
22166  was executed.
22167 \layout Chapter
22168
22169 Acknowledgments
22170 \layout Standard
22171
22172
22173 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
22174
22175 \end_inset
22176
22177
22178 \newline
22179
22180 \newline
22181
22182 \emph on
22183 Thanks to all the other volunteer developers who have helped with coding,
22184  testing, web-page creation, distribution sets, etc.
22185  You know who you are :-)
22186 \emph default
22187
22188 \newline
22189
22190 \layout Standard
22191
22192 This document was initially written by Sandeep Dutta
22193 \layout Standard
22194
22195 All product names mentioned herein may be trademarks
22196 \begin_inset LatexCommand \index{Trademarks}
22197
22198 \end_inset
22199
22200  of their respective companies.
22201
22202 \layout Section*
22203
22204 Alphabetical index
22205 \layout Standard
22206
22207 To avoid confusion, the installation and building options for SDCC itself
22208  (chapter 2) are not part of the index.
22209 \layout Standard
22210
22211
22212 \begin_inset LatexCommand \printindex{}
22213
22214 \end_inset
22215
22216
22217 \the_end