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.4
  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 an open source, retargettable, optimizing ANSI-C compiler by
 132
 133 \series bold
 134 Sandeep Dutta
 135 \series default
 136  designed for 8 bit Microprocessors.
 137  The current version targets Intel MCS51 based Microprocessors (8031, 8032,
 138  8051, 8052
 139 \begin_inset LatexCommand \index{8031, 8032, 8051, 8052, mcs51 CPU}
 140
 141 \end_inset
 142
 143 , etc.), Dallas DS80C390 variants, Motorola HC08 and Zilog Z80 based MCUs.
 144  It can be retargetted for other microprocessors, support for Microchip
 145  PIC, Atmel AVR is under development.
 146  The entire source code for the compiler is distributed under GPL.
 147  SDCC uses ASXXXX
 148 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
 149
 150 \end_inset
 151
 152  & ASLINK
 153 \begin_inset LatexCommand \index{aslink}
 154
 155 \end_inset
 156
 157 , an open source retargettable assembler & linker.
 158  SDCC has extensive language extensions suitable for utilizing various microcont
 159 rollers and underlying hardware effectively.
 160
 161 \newline
 162
 163 \newline
 164 In addition to the MCU specific optimizations SDCC also does a host of standard
 165  optimizations like:
 166 \layout Itemize
 167
 168 global sub expression elimination,
 169 \layout Itemize
 170
 171 loop optimizations (loop invariant, strength reduction of induction variables
 172  and loop reversing),
 173 \layout Itemize
 174
 175 constant folding & propagation,
 176 \layout Itemize
 177
 178 copy propagation,
 179 \layout Itemize
 180
 181 dead code elimination
 182 \layout Itemize
 183
 184 jump tables for
 185 \emph on
 186 switch
 187 \emph default
 188  statements.
 189 \layout Standard
 190
 191 For the back-end SDCC uses a global register allocation scheme which should
 192  be well suited for other 8 bit MCUs.
 193
 194 \newline
 195
 196 \newline
 197 The peep hole optimizer uses a rule based substitution mechanism which is
 198  MCU independent.
 199
 200 \newline
 201
 202 \newline
 203 Supported data-types are:
 204 \layout Itemize
 205
 206 char (8 bits, 1 byte),
 207 \layout Itemize
 208
 209 short and int (16 bits, 2 bytes),
 210 \layout Itemize
 211
 212 long (32 bit, 4 bytes)
 213 \layout Itemize
 214
 215 float (4 byte IEEE).
 216
 217 \layout Standard
 218
 219 The compiler also allows
 220 \emph on
 221 inline assembler code
 222 \emph default
 223  to be embedded anywhere in a function.
 224  In addition, routines developed in assembly can also be called.
 225 \newline
 226
 227 \newline
 228 SDCC also provides an option (-
 229 \begin_inset ERT
 230 status Collapsed
 231
 232 \layout Standard
 233
 234 \backslash
 235 /
 236 \end_inset
 237
 238 -cyclomatic) to report the relative complexity of a function.
 239  These functions can then be further optimized, or hand coded in assembly
 240  if needed.
 241
 242 \newline
 243
 244 \newline
 245 SDCC also comes with a companion source level debugger SDCDB, the debugger
 246  currently uses ucSim a freeware simulator for 8051 and other micro-controllers.
 247
 248 \newline
 249
 250 \newline
 251 The latest version can be downloaded from
 252 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
 253
 254 \end_inset
 255
 256 .
 257
 258 \series bold
 259
 260 \series default
 261 \emph on
 262 Please note: the compiler will probably always be some steps ahead of this
 263  documentation
 264 \series bold
 265 \emph default
 266
 267 \begin_inset LatexCommand \index{Status of documentation}
 268
 269 \end_inset
 270
 271
 272 \begin_inset Foot
 273 collapsed false
 274
 275 \layout Standard
 276
 277 Obviously this has pros and cons
 278 \end_inset
 279
 280 .
 281 \layout Section
 282
 283 Open Source
 284 \layout Standard
 285
 286 All packages used in this compiler system are
 287 \emph on
 288 open source
 289 \emph default
 290  and
 291 \emph on
 292 freeware
 293 \emph default
 294 ; source code for all the sub-packages (pre-processor, assemblers, linkers
 295  etc) is distributed with the package.
 296  This documentation is maintained using a freeware word processor (LyX).
 297 \newline
 298 This program is free software; you can redistribute it and/or modify it
 299  under the terms of the GNU General Public License
 300 \begin_inset LatexCommand \index{GNU General Public License, GPL}
 301
 302 \end_inset
 303
 304  as published by the Free Software Foundation; either version 2, or (at
 305  your option) any later version.
 306  This program is distributed in the hope that it will be useful, but WITHOUT
 307  ANY WARRANTY; without even the implied warranty
 308 \begin_inset LatexCommand \index{warranty}
 309
 310 \end_inset
 311
 312  of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 313  See the GNU General Public License for more details.
 314  You should have received a copy of the GNU General Public License along
 315  with this program; if not, write to the Free Software Foundation, 59 Temple
 316  Place - Suite 330, Boston, MA 02111-1307, USA.
 317  In other words, you are welcome to use, share and improve this program.
 318  You are forbidden to forbid anyone else to use, share and improve what
 319  you give them.
 320  Help stamp out software-hoarding!
 321 \layout Section
 322
 323 Typographic conventions
 324 \begin_inset LatexCommand \index{Typographic conventions}
 325
 326 \end_inset
 327
 328
 329 \layout Standard
 330
 331 Throughout this manual, we will use the following convention.
 332  Commands you have to type in are printed in
 333 \family sans
 334 \series bold
 335 "sans serif"
 336 \series default
 337 .
 338
 339 \family default
 340  Code samples are printed in
 341 \family typewriter
 342 typewriter font.
 343
 344 \family default
 345  Interesting items and new terms are printed in
 346 \emph on
 347 italic.
 348 \layout Section
 349
 350 Compatibility with previous versions
 351 \layout Standard
 352
 353 This version has numerous bug fixes compared with the previous version.
 354  But we also introduced some incompatibilities with older versions.
 355  Not just for the fun of it, but to make the compiler more stable, efficient
 356  and ANSI compliant
 357 \begin_inset LatexCommand \index{ANSI-compliance}
 358
 359 \end_inset
 360
 361  (see section
 362 \begin_inset LatexCommand \ref{sub:ANSI-Compliance}
 363
 364 \end_inset
 365
 366  for ANSI-Compliance).
 367
 368 \newline
 369
 370 \layout Itemize
 371
 372 short is now equivalent to int (16 bits), it used to be equivalent to char
 373  (8 bits) which is not ANSI compliant
 374 \layout Itemize
 375
 376 the default directory for gcc-builds where include, library and documentation
 377  files are stored is now in /usr/local/share
 378 \layout Itemize
 379
 380 char type parameters to vararg functions are casted to int unless explicitly
 381  casted, e.g.:
 382 \newline
 383
 384 \family typewriter
 385 \SpecialChar ~
 386 \SpecialChar ~
 387 char a=3;
 388 \newline
 389 \SpecialChar ~
 390 \SpecialChar ~
 391 printf ("%d %c
 392 \backslash
 393 n", a, (char)a);
 394 \family default
 395
 396 \newline
 397  will push a as an int and as a char resp.
 398 \layout Itemize
 399
 400 option -
 401 \begin_inset ERT
 402 status Collapsed
 403
 404 \layout Standard
 405
 406 \backslash
 407 /
 408 \end_inset
 409
 410 -regextend has been removed
 411 \layout Itemize
 412
 413 option -
 414 \begin_inset ERT
 415 status Collapsed
 416
 417 \layout Standard
 418
 419 \backslash
 420 /
 421 \end_inset
 422
 423 -noregparms has been removed
 424 \layout Itemize
 425
 426 option -
 427 \begin_inset ERT
 428 status Collapsed
 429
 430 \layout Standard
 431
 432 \backslash
 433 /
 434 \end_inset
 435
 436 -stack-after-data has been removed
 437 \layout Standard
 438
 439
 440 \emph on
 441 <pending: more incompatibilities?>
 442 \layout Section
 443
 444 System Requirements
 445 \layout Standard
 446
 447 What do you need before you start installation of SDCC? A computer, and
 448  a desire to compute.
 449  The preferred method of installation is to compile SDCC from source using
 450  GNU gcc and make.
 451  For Windows some pre-compiled binary distributions are available for your
 452  convenience.
 453  You should have some experience with command line tools and compiler use.
 454 \layout Section
 455
 456 Other Resources
 457 \layout Standard
 458
 459 The SDCC home page at
 460 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/}
 461
 462 \end_inset
 463
 464  is a great place to find distribution sets.
 465  You can also find links to the user mailing lists that offer help or discuss
 466  SDCC with other SDCC users.
 467  Web links to other SDCC related sites can also be found here.
 468  This document can be found in the DOC directory of the source package as
 469  a text or HTML file.
 470  A pdf version of this document is available at
 471 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
 472
 473 \end_inset
 474
 475 .
 476  Some of the other tools (simulator and assembler) included with SDCC contain
 477  their own documentation and can be found in the source distribution.
 478  If you want the latest unreleased software, the complete source package
 479  is available directly by anonymous CVS on cvs.sdcc.sourceforge.net.
 480 \layout Section
 481
 482 Wishes for the future
 483 \layout Standard
 484
 485 There are (and always will be) some things that could be done.
 486  Here are some I can think of:
 487 \newline
 488
 489 \layout Standard
 490
 491
 492 \family typewriter
 493 char KernelFunction3(char p) at 0x340;
 494 \newline
 495
 496 \layout Standard
 497
 498
 499 \family typewriter
 500 code banking
 501 \begin_inset LatexCommand \index{code banking (not supported)}
 502
 503 \end_inset
 504
 505  support for mcs51
 506 \newline
 507
 508 \newline
 509
 510 \family default
 511 If you can think of some more, please see the section
 512 \begin_inset LatexCommand \ref{sub:Requesting-Features}
 513
 514 \end_inset
 515
 516  about filing feature requests
 517 \begin_inset LatexCommand \index{Requesting features}
 518
 519 \end_inset
 520
 521
 522 \begin_inset LatexCommand \index{Feature request}
 523
 524 \end_inset
 525
 526 .
 527 \newline
 528
 529 \layout Chapter
 530
 531 Installing SDCC
 532 \begin_inset LatexCommand \index{Installation}
 533
 534 \end_inset
 535
 536
 537 \layout Standard
 538
 539 For most users it is sufficient to skip to either section
 540 \begin_inset LatexCommand \ref{sub:Building-SDCC-on-Linux}
 541
 542 \end_inset
 543
 544  or section
 545 \begin_inset LatexCommand \ref{sub:Windows-Install}
 546
 547 \end_inset
 548
 549 .
 550  More detailled instructions follow below.
 551 \layout Section
 552
 553 Configure Options
 554 \begin_inset LatexCommand \index{Options SDCC configuration}
 555
 556 \end_inset
 557
 558
 559 \layout Standard
 560
 561 The install paths, search paths and other options are defined when running
 562  'configure'.
 563  The defaults can be overridden by:
 564 \layout List
 565 \labelwidthstring 00.00.0000
 566
 567 -
 568 \begin_inset ERT
 569 status Collapsed
 570
 571 \layout Standard
 572
 573 \backslash
 574 /
 575 \end_inset
 576
 577 -prefix see table below
 578 \layout List
 579 \labelwidthstring 00.00.0000
 580
 581 -
 582 \begin_inset ERT
 583 status Collapsed
 584
 585 \layout Standard
 586
 587 \backslash
 588 /
 589 \end_inset
 590
 591 -exec_prefix see table below
 592 \layout List
 593 \labelwidthstring 00.00.0000
 594
 595 -
 596 \begin_inset ERT
 597 status Collapsed
 598
 599 \layout Standard
 600
 601 \backslash
 602 /
 603 \end_inset
 604
 605 -bindir see table below
 606 \layout List
 607 \labelwidthstring 00.00.0000
 608
 609 -
 610 \begin_inset ERT
 611 status Collapsed
 612
 613 \layout Standard
 614
 615 \backslash
 616 /
 617 \end_inset
 618
 619 -datadir see table below
 620 \layout List
 621 \labelwidthstring 00.00.0000
 622
 623 docdir environment variable, see table below
 624 \layout List
 625 \labelwidthstring 00.00.0000
 626
 627 include_dir_suffix environment variable, see table below
 628 \layout List
 629 \labelwidthstring 00.00.0000
 630
 631 lib_dir_suffix environment variable, see table below
 632 \layout List
 633 \labelwidthstring 00.00.0000
 634
 635 sdccconf_h_dir_separator environment variable, either / or
 636 \backslash
 637
 638 \backslash
 639  makes sense here.
 640  This character will only be used in sdccconf.h; don't forget it's a C-header,
 641  therefore a double-backslash is needed there.
 642 \layout List
 643 \labelwidthstring 00.00.0000
 644
 645 -
 646 \begin_inset ERT
 647 status Collapsed
 648
 649 \layout Standard
 650
 651 \backslash
 652 /
 653 \end_inset
 654
 655 -disable-mcs51-port Excludes the Intel mcs51 port
 656 \layout List
 657 \labelwidthstring 00.00.0000
 658
 659 -
 660 \begin_inset ERT
 661 status Collapsed
 662
 663 \layout Standard
 664
 665 \backslash
 666 /
 667 \end_inset
 668
 669 -disable-gbz80-port Excludes the Gameboy gbz80 port
 670 \layout List
 671 \labelwidthstring 00.00.0000
 672
 673 -
 674 \begin_inset ERT
 675 status Collapsed
 676
 677 \layout Standard
 678
 679 \backslash
 680 /
 681 \end_inset
 682
 683 -disable-z80-port Excludes the z80 port
 684 \layout List
 685 \labelwidthstring 00.00.0000
 686
 687 -
 688 \begin_inset ERT
 689 status Collapsed
 690
 691 \layout Standard
 692
 693 \backslash
 694 /
 695 \end_inset
 696
 697 -disable-avr-port Excludes the AVR port
 698 \layout List
 699 \labelwidthstring 00.00.0000
 700
 701 -
 702 \begin_inset ERT
 703 status Collapsed
 704
 705 \layout Standard
 706
 707 \backslash
 708 /
 709 \end_inset
 710
 711 -disable-ds390-port Excludes the DS390 port
 712 \layout List
 713 \labelwidthstring 00.00.0000
 714
 715 -
 716 \begin_inset ERT
 717 status Collapsed
 718
 719 \layout Standard
 720
 721 \backslash
 722 /
 723 \end_inset
 724
 725 -disable-hc08-port Excludes the HC08 port
 726 \layout List
 727 \labelwidthstring 00.00.0000
 728
 729 -
 730 \begin_inset ERT
 731 status Collapsed
 732
 733 \layout Standard
 734
 735 \backslash
 736 /
 737 \end_inset
 738
 739 -disable-pic-port Excludes the PIC port
 740 \layout List
 741 \labelwidthstring 00.00.0000
 742
 743 -
 744 \begin_inset ERT
 745 status Collapsed
 746
 747 \layout Standard
 748
 749 \backslash
 750 /
 751 \end_inset
 752
 753 -disable-xa51-port Excludes the XA51 port
 754 \layout List
 755 \labelwidthstring 00.00.0000
 756
 757 -
 758 \begin_inset ERT
 759 status Collapsed
 760
 761 \layout Standard
 762
 763 \backslash
 764 /
 765 \end_inset
 766
 767 -disable-ucsim Disables configuring and building of ucsim
 768 \layout List
 769 \labelwidthstring 00.00.0000
 770
 771 -
 772 \begin_inset ERT
 773 status Collapsed
 774
 775 \layout Standard
 776
 777 \backslash
 778 /
 779 \end_inset
 780
 781 -disable-device-lib-build Disables automatically building device libraries
 782 \layout List
 783 \labelwidthstring 00.00.0000
 784
 785 -
 786 \begin_inset ERT
 787 status Collapsed
 788
 789 \layout Standard
 790
 791 \backslash
 792 /
 793 \end_inset
 794
 795 -disable-packihx Disables building packihx
 796 \layout List
 797 \labelwidthstring 00.00.0000
 798
 799 -
 800 \begin_inset ERT
 801 status Collapsed
 802
 803 \layout Standard
 804
 805 \backslash
 806 /
 807 \end_inset
 808
 809 -enable-libgc Use the Bohem memory allocator.
 810  Lower runtime footprint.
 811 \layout Standard
 812
 813 Furthermore the environment variables CC, CFLAGS, ...
 814  the tools and their arguments can be influenced.
 815  Please see `configure -
 816 \begin_inset ERT
 817 status Collapsed
 818
 819 \layout Standard
 820
 821 \backslash
 822 /
 823 \end_inset
 824
 825 -help` and the man/info pages of `configure` for details.
 826 \newline
 827
 828 \newline
 829 The names of the standard libraries STD_LIB, STD_INT_LIB, STD_LONG_LIB,
 830  STD_FP_LIB, STD_DS390_LIB, STD_XA51_LIB and the environment variables SDCC_DIR_
 831 NAME, SDCC_INCLUDE_NAME, SDCC_LIB_NAME are defined by `configure` too.
 832  At the moment it's not possible to change the default settings (it was
 833  simply never required).
 834 \newline
 835
 836 \newline
 837 These configure options are compiled into the binaries, and can only be
 838  changed by rerunning 'configure' and recompiling SDCC.
 839  The configure options are written in
 840 \emph on
 841 italics
 842 \emph default
 843  to distinguish them from run time environment variables (see section search
 844  paths).
 845 \newline
 846
 847 \newline
 848 The settings for
 849 \begin_inset Quotes sld
 850 \end_inset
 851
 852 Win32 builds
 853 \begin_inset Quotes srd
 854 \end_inset
 855
 856  are used by the SDCC team to build the official Win32 binaries.
 857  The SDCC team uses Mingw32 to build the official Windows binaries, because
 858  it's
 859 \layout Enumerate
 860
 861 open source,
 862 \layout Enumerate
 863
 864 a gcc compiler and last but not least
 865 \layout Enumerate
 866
 867 the binaries can be built by cross compiling on Sourceforge's compile farm.
 868 \layout Standard
 869
 870 See the examples, how to pass the Win32 settings to 'configure'.
 871  The other Win32 builds using Borland, VC or whatever don't use 'configure',
 872  but a header file sdcc_vc_in.h is the same as sdccconf.h built by 'configure'
 873  for Win32.
 874 \newline
 875
 876 \newline
 877 These defaults are:
 878 \newline
 879
 880 \layout Standard
 881 \align center
 882
 883 \begin_inset  Tabular
 884 <lyxtabular version="3" rows="8" columns="3">
 885 <features>
 886 <column alignment="block" valignment="top" leftline="true" width="0in">
 887 <column alignment="block" valignment="top" leftline="true" width="0in">
 888 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
 889 <row topline="true" bottomline="true">
 890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 891 \begin_inset Text
 892
 893 \layout Standard
 894
 895 Variable
 896 \end_inset
 897 </cell>
 898 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 899 \begin_inset Text
 900
 901 \layout Standard
 902
 903 default
 904 \end_inset
 905 </cell>
 906 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 907 \begin_inset Text
 908
 909 \layout Standard
 910
 911 Win32 builds
 912 \end_inset
 913 </cell>
 914 </row>
 915 <row topline="true">
 916 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 917 \begin_inset Text
 918
 919 \layout Standard
 920
 921
 922 \emph on
 923 PREFIX
 924 \end_inset
 925 </cell>
 926 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 927 \begin_inset Text
 928
 929 \layout Standard
 930
 931 /usr/local
 932 \end_inset
 933 </cell>
 934 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 935 \begin_inset Text
 936
 937 \layout Standard
 938
 939
 940 \backslash
 941 sdcc
 942 \end_inset
 943 </cell>
 944 </row>
 945 <row topline="true">
 946 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 947 \begin_inset Text
 948
 949 \layout Standard
 950
 951
 952 \emph on
 953 EXEC_PREFIX
 954 \end_inset
 955 </cell>
 956 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 957 \begin_inset Text
 958
 959 \layout Standard
 960
 961
 962 \emph on
 963 $PREFIX
 964 \end_inset
 965 </cell>
 966 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
 967 \begin_inset Text
 968
 969 \layout Standard
 970
 971
 972 \emph on
 973 $PREFIX
 974 \end_inset
 975 </cell>
 976 </row>
 977 <row topline="true">
 978 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 979 \begin_inset Text
 980
 981 \layout Standard
 982
 983
 984 \emph on
 985 BINDIR
 986 \end_inset
 987 </cell>
 988 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
 989 \begin_inset Text
 990
 991 \layout Standard
 992
 993
 994 \emph on
 995 $EXECPREFIX
 996 \emph default
 997 /bin
 998 \end_inset
 999 </cell>
1000 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1001 \begin_inset Text
1002
1003 \layout Standard
1004
1005
1006 \emph on
1007 $EXECPREFIX
1008 \emph default
1009
1010 \backslash
1011 bin
1012 \end_inset
1013 </cell>
1014 </row>
1015 <row topline="true">
1016 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1017 \begin_inset Text
1018
1019 \layout Standard
1020
1021
1022 \emph on
1023 DATADIR
1024 \end_inset
1025 </cell>
1026 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1027 \begin_inset Text
1028
1029 \layout Standard
1030
1031
1032 \emph on
1033 $PREFIX
1034 \emph default
1035 /share
1036 \end_inset
1037 </cell>
1038 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1039 \begin_inset Text
1040
1041 \layout Standard
1042
1043
1044 \emph on
1045 $PREFIX
1046 \end_inset
1047 </cell>
1048 </row>
1049 <row topline="true">
1050 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1051 \begin_inset Text
1052
1053 \layout Standard
1054
1055
1056 \emph on
1057 DOCDIR
1058 \end_inset
1059 </cell>
1060 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1061 \begin_inset Text
1062
1063 \layout Standard
1064
1065
1066 \emph on
1067 $DATADIR
1068 \emph default
1069 /sdcc/doc
1070 \end_inset
1071 </cell>
1072 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1073 \begin_inset Text
1074
1075 \layout Standard
1076
1077
1078 \emph on
1079 $DATADIR
1080 \emph default
1081
1082 \backslash
1083 doc
1084 \end_inset
1085 </cell>
1086 </row>
1087 <row topline="true">
1088 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1089 \begin_inset Text
1090
1091 \layout Standard
1092
1093
1094 \emph on
1095 INCLUDE_DIR_SUFFIX
1096 \end_inset
1097 </cell>
1098 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1099 \begin_inset Text
1100
1101 \layout Standard
1102
1103 sdcc/include
1104 \end_inset
1105 </cell>
1106 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1107 \begin_inset Text
1108
1109 \layout Standard
1110
1111 include
1112 \end_inset
1113 </cell>
1114 </row>
1115 <row topline="true" bottomline="true">
1116 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1117 \begin_inset Text
1118
1119 \layout Standard
1120
1121
1122 \emph on
1123 LIB_DIR_SUFFIX
1124 \end_inset
1125 </cell>
1126 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1127 \begin_inset Text
1128
1129 \layout Standard
1130
1131 sdcc/lib
1132 \end_inset
1133 </cell>
1134 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1135 \begin_inset Text
1136
1137 \layout Standard
1138
1139 lib
1140 \end_inset
1141 </cell>
1142 </row>
1143 </lyxtabular>
1144
1145 \end_inset
1146
1147
1148 \newline
1149
1150 \layout Standard
1151 \noindent
1152 'configure' also computes relative paths.
1153  This is needed for full relocatability of a binary package and to complete
1154  search paths (see section search paths below):
1155 \newline
1156
1157 \layout Standard
1158 \align center
1159
1160 \begin_inset  Tabular
1161 <lyxtabular version="3" rows="4" columns="3">
1162 <features>
1163 <column alignment="block" valignment="top" leftline="true" width="0in">
1164 <column alignment="block" valignment="top" leftline="true" width="0in">
1165 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
1166 <row topline="true" bottomline="true">
1167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1168 \begin_inset Text
1169
1170 \layout Standard
1171
1172 Variable (computed)
1173 \end_inset
1174 </cell>
1175 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1176 \begin_inset Text
1177
1178 \layout Standard
1179
1180 default
1181 \end_inset
1182 </cell>
1183 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1184 \begin_inset Text
1185
1186 \layout Standard
1187
1188 Win32 builds
1189 \end_inset
1190 </cell>
1191 </row>
1192 <row topline="true" bottomline="true">
1193 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1194 \begin_inset Text
1195
1196 \layout Standard
1197
1198
1199 \emph on
1200 BIN2DATA_DIR
1201 \end_inset
1202 </cell>
1203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1204 \begin_inset Text
1205
1206 \layout Standard
1207
1208 ../share
1209 \end_inset
1210 </cell>
1211 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1212 \begin_inset Text
1213
1214 \layout Standard
1215
1216 ..
1217 \end_inset
1218 </cell>
1219 </row>
1220 <row bottomline="true">
1221 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1222 \begin_inset Text
1223
1224 \layout Standard
1225
1226
1227 \emph on
1228 PREFIX2BIN_DIR
1229 \end_inset
1230 </cell>
1231 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1232 \begin_inset Text
1233
1234 \layout Standard
1235
1236 bin
1237 \end_inset
1238 </cell>
1239 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1240 \begin_inset Text
1241
1242 \layout Standard
1243
1244 bin
1245 \end_inset
1246 </cell>
1247 </row>
1248 <row bottomline="true">
1249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1250 \begin_inset Text
1251
1252 \layout Standard
1253
1254
1255 \emph on
1256 PREFIX2DATA_DIR
1257 \end_inset
1258 </cell>
1259 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1260 \begin_inset Text
1261
1262 \layout Standard
1263
1264 share/sdcc
1265 \end_inset
1266 </cell>
1267 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1268 \begin_inset Text
1269
1270 \layout Standard
1271
1272 \end_inset
1273 </cell>
1274 </row>
1275 </lyxtabular>
1276
1277 \end_inset
1278
1279
1280 \newline
1281
1282 \layout Standard
1283 \noindent
1284 Examples:
1285 \layout LyX-Code
1286
1287 ./configure
1288 \newline
1289 ./configure -
1290 \begin_inset ERT
1291 status Collapsed
1292
1293 \layout Standard
1294
1295 \backslash
1296 /
1297 \end_inset
1298
1299 -prefix=
1300 \begin_inset Quotes srd
1301 \end_inset
1302
1303 /usr/bin
1304 \begin_inset Quotes srd
1305 \end_inset
1306
1307  -
1308 \begin_inset ERT
1309 status Collapsed
1310
1311 \layout Standard
1312
1313 \backslash
1314 /
1315 \end_inset
1316
1317 -datadir=
1318 \begin_inset Quotes srd
1319 \end_inset
1320
1321 /usr/share
1322 \begin_inset Quotes srd
1323 \end_inset
1324
1325
1326 \newline
1327 ./configure -
1328 \begin_inset ERT
1329 status Collapsed
1330
1331 \layout Standard
1332
1333 \backslash
1334 /
1335 \end_inset
1336
1337 -disable-avr-port -
1338 \begin_inset ERT
1339 status Collapsed
1340
1341 \layout Standard
1342
1343 \backslash
1344 /
1345 \end_inset
1346
1347 -disable-xa51-port
1348 \layout Standard
1349
1350 To cross compile on linux for Mingw32 (see also 'sdcc/support/scripts/sdcc_mingw
1351 32'):
1352 \layout LyX-Code
1353
1354 ./configure
1355 \backslash
1356
1357 \newline
1358 CC=
1359 \begin_inset Quotes srd
1360 \end_inset
1361
1362 i586-mingw32msvc-gcc
1363 \begin_inset Quotes srd
1364 \end_inset
1365
1366  CXX=
1367 \begin_inset Quotes srd
1368 \end_inset
1369
1370 i586-mingw32msvc-g++
1371 \begin_inset Quotes srd
1372 \end_inset
1373
1374
1375 \backslash
1376
1377 \newline
1378 RANLIB=
1379 \begin_inset Quotes srd
1380 \end_inset
1381
1382 i586-mingw32msvc-ranlib
1383 \begin_inset Quotes srd
1384 \end_inset
1385
1386
1387 \backslash
1388
1389 \newline
1390 STRIP=
1391 \begin_inset Quotes srd
1392 \end_inset
1393
1394 i586-mingw32msvc-strip
1395 \begin_inset Quotes srd
1396 \end_inset
1397
1398
1399 \backslash
1400
1401 \newline
1402 -
1403 \begin_inset ERT
1404 status Collapsed
1405
1406 \layout Standard
1407
1408 \backslash
1409 /
1410 \end_inset
1411
1412 -prefix=
1413 \begin_inset Quotes srd
1414 \end_inset
1415
1416 /sdcc
1417 \begin_inset Quotes srd
1418 \end_inset
1419
1420
1421 \backslash
1422
1423 \newline
1424 -
1425 \begin_inset ERT
1426 status Collapsed
1427
1428 \layout Standard
1429
1430 \backslash
1431 /
1432 \end_inset
1433
1434 -datadir=
1435 \begin_inset Quotes srd
1436 \end_inset
1437
1438 /sdcc
1439 \begin_inset Quotes srd
1440 \end_inset
1441
1442
1443 \backslash
1444
1445 \newline
1446 docdir=
1447 \begin_inset Quotes srd
1448 \end_inset
1449
1450 /sdcc/doc
1451 \begin_inset Quotes srd
1452 \end_inset
1453
1454
1455 \backslash
1456
1457 \newline
1458 include_dir_suffix=
1459 \begin_inset Quotes srd
1460 \end_inset
1461
1462 include
1463 \begin_inset Quotes srd
1464 \end_inset
1465
1466
1467 \backslash
1468
1469 \newline
1470 lib_dir_suffix=
1471 \begin_inset Quotes srd
1472 \end_inset
1473
1474 lib
1475 \begin_inset Quotes srd
1476 \end_inset
1477
1478
1479 \backslash
1480
1481 \newline
1482 sdccconf_h_dir_separator=
1483 \begin_inset Quotes srd
1484 \end_inset
1485
1486
1487 \backslash
1488
1489 \backslash
1490
1491 \backslash
1492
1493 \backslash
1494
1495 \begin_inset Quotes srd
1496 \end_inset
1497
1498
1499 \backslash
1500
1501 \newline
1502 -
1503 \begin_inset ERT
1504 status Collapsed
1505
1506 \layout Standard
1507
1508 \backslash
1509 /
1510 \end_inset
1511
1512 -disable-device-lib-build
1513 \backslash
1514
1515 \newline
1516 -
1517 \begin_inset ERT
1518 status Collapsed
1519
1520 \layout Standard
1521
1522 \backslash
1523 /
1524 \end_inset
1525
1526 -disable-ucsim
1527 \backslash
1528
1529 \newline
1530 -
1531 \begin_inset ERT
1532 status Collapsed
1533
1534 \layout Standard
1535
1536 \backslash
1537 /
1538 \end_inset
1539
1540 -host=i586-mingw32msvc -
1541 \begin_inset ERT
1542 status Collapsed
1543
1544 \layout Standard
1545
1546 \backslash
1547 /
1548 \end_inset
1549
1550 -build=unknown-unknown-linux-gnu
1551 \layout Standard
1552
1553 To
1554 \begin_inset Quotes sld
1555 \end_inset
1556
1557 cross
1558 \begin_inset Quotes srd
1559 \end_inset
1560
1561 compile on Cygwin for Mingw32 (see also sdcc/support/scripts/sdcc_cygwin_mingw32
1562 ):
1563 \layout LyX-Code
1564
1565 ./configure -C
1566 \backslash
1567
1568 \newline
1569 CFLAGS=
1570 \begin_inset Quotes srd
1571 \end_inset
1572
1573 -mno-cygwin -O2
1574 \begin_inset Quotes srd
1575 \end_inset
1576
1577
1578 \backslash
1579
1580 \newline
1581 LDFLAGS=
1582 \begin_inset Quotes srd
1583 \end_inset
1584
1585 -mno-cygwin
1586 \begin_inset Quotes srd
1587 \end_inset
1588
1589
1590 \backslash
1591
1592 \newline
1593 -
1594 \begin_inset ERT
1595 status Collapsed
1596
1597 \layout Standard
1598
1599 \backslash
1600 /
1601 \end_inset
1602
1603 -prefix=
1604 \begin_inset Quotes srd
1605 \end_inset
1606
1607 /sdcc
1608 \begin_inset Quotes srd
1609 \end_inset
1610
1611
1612 \backslash
1613
1614 \newline
1615 -
1616 \begin_inset ERT
1617 status Collapsed
1618
1619 \layout Standard
1620
1621 \backslash
1622 /
1623 \end_inset
1624
1625 -datadir=
1626 \begin_inset Quotes srd
1627 \end_inset
1628
1629 /sdcc
1630 \begin_inset Quotes srd
1631 \end_inset
1632
1633
1634 \backslash
1635
1636 \newline
1637 docdir=
1638 \begin_inset Quotes srd
1639 \end_inset
1640
1641 /sdcc/doc
1642 \begin_inset Quotes srd
1643 \end_inset
1644
1645
1646 \backslash
1647
1648 \newline
1649 include_dir_suffix=
1650 \begin_inset Quotes srd
1651 \end_inset
1652
1653 include
1654 \begin_inset Quotes srd
1655 \end_inset
1656
1657
1658 \backslash
1659
1660 \newline
1661 lib_dir_suffix=
1662 \begin_inset Quotes srd
1663 \end_inset
1664
1665 lib
1666 \begin_inset Quotes srd
1667 \end_inset
1668
1669
1670 \backslash
1671
1672 \newline
1673 sdccconf_h_dir_separator=
1674 \begin_inset Quotes srd
1675 \end_inset
1676
1677
1678 \backslash
1679
1680 \backslash
1681
1682 \backslash
1683
1684 \backslash
1685
1686 \begin_inset Quotes srd
1687 \end_inset
1688
1689
1690 \backslash
1691
1692 \newline
1693 -
1694 \begin_inset ERT
1695 status Collapsed
1696
1697 \layout Standard
1698
1699 \backslash
1700 /
1701 \end_inset
1702
1703 -disable-ucsim
1704 \layout Standard
1705
1706 'configure' is quite slow on Cygwin (at least on windows before Win2000/XP).
1707  The option '-
1708 \begin_inset ERT
1709 status Collapsed
1710
1711 \layout Standard
1712
1713 \backslash
1714 /
1715 \end_inset
1716
1717 -C' turns on caching, which gives a little bit extra speed.
1718  However if options are changed, it can be necessary to delete the config.cache
1719  file.
1720 \layout Section
1721
1722 Install paths
1723 \begin_inset LatexCommand \label{sub:Install-paths}
1724
1725 \end_inset
1726
1727
1728 \begin_inset LatexCommand \index{Install paths}
1729
1730 \end_inset
1731
1732
1733 \layout Standard
1734 \added_space_top medskip \align center
1735
1736 \begin_inset  Tabular
1737 <lyxtabular version="3" rows="5" columns="4">
1738 <features>
1739 <column alignment="center" valignment="top" leftline="true" width="0">
1740 <column alignment="center" valignment="top" leftline="true" width="0">
1741 <column alignment="center" valignment="top" leftline="true" width="0">
1742 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
1743 <row topline="true" bottomline="true">
1744 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1745 \begin_inset Text
1746
1747 \layout Standard
1748
1749
1750 \series bold
1751 Description
1752 \end_inset
1753 </cell>
1754 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1755 \begin_inset Text
1756
1757 \layout Standard
1758
1759
1760 \series bold
1761 Path
1762 \end_inset
1763 </cell>
1764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1765 \begin_inset Text
1766
1767 \layout Standard
1768
1769
1770 \series bold
1771 Default
1772 \end_inset
1773 </cell>
1774 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1775 \begin_inset Text
1776
1777 \layout Standard
1778
1779
1780 \series bold
1781 Win32 builds
1782 \end_inset
1783 </cell>
1784 </row>
1785 <row topline="true">
1786 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1787 \begin_inset Text
1788
1789 \layout Standard
1790
1791 Binary files*
1792 \end_inset
1793 </cell>
1794 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1795 \begin_inset Text
1796
1797 \layout Standard
1798
1799
1800 \emph on
1801 $EXEC_PREFIX
1802 \end_inset
1803 </cell>
1804 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1805 \begin_inset Text
1806
1807 \layout Standard
1808
1809 /usr/local/bin
1810 \end_inset
1811 </cell>
1812 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1813 \begin_inset Text
1814
1815 \layout Standard
1816
1817
1818 \backslash
1819 sdcc
1820 \backslash
1821 bin
1822 \end_inset
1823 </cell>
1824 </row>
1825 <row topline="true">
1826 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1827 \begin_inset Text
1828
1829 \layout Standard
1830
1831 Include files
1832 \end_inset
1833 </cell>
1834 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1835 \begin_inset Text
1836
1837 \layout Standard
1838
1839
1840 \emph on
1841 $DATADIR/ $INCLUDE_DIR_SUFFIX
1842 \end_inset
1843 </cell>
1844 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1845 \begin_inset Text
1846
1847 \layout Standard
1848
1849 /usr/local/share/sdcc/include
1850 \end_inset
1851 </cell>
1852 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1853 \begin_inset Text
1854
1855 \layout Standard
1856
1857
1858 \backslash
1859 sdcc
1860 \backslash
1861 include
1862 \end_inset
1863 </cell>
1864 </row>
1865 <row topline="true">
1866 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1867 \begin_inset Text
1868
1869 \layout Standard
1870
1871 Library file**
1872 \end_inset
1873 </cell>
1874 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1875 \begin_inset Text
1876
1877 \layout Standard
1878
1879
1880 \emph on
1881 $DATADIR/$LIB_DIR_SUFFIX
1882 \end_inset
1883 </cell>
1884 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1885 \begin_inset Text
1886
1887 \layout Standard
1888
1889 /usr/local/share/sdcc/lib
1890 \end_inset
1891 </cell>
1892 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1893 \begin_inset Text
1894
1895 \layout Standard
1896
1897
1898 \backslash
1899 sdcc
1900 \backslash
1901 lib
1902 \end_inset
1903 </cell>
1904 </row>
1905 <row topline="true" bottomline="true">
1906 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1907 \begin_inset Text
1908
1909 \layout Standard
1910
1911 Documentation
1912 \end_inset
1913 </cell>
1914 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1915 \begin_inset Text
1916
1917 \layout Standard
1918
1919
1920 \emph on
1921 $DOCDIR
1922 \end_inset
1923 </cell>
1924 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
1925 \begin_inset Text
1926
1927 \layout Standard
1928
1929 /usr/local/share/sdcc/doc
1930 \end_inset
1931 </cell>
1932 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
1933 \begin_inset Text
1934
1935 \layout Standard
1936
1937
1938 \backslash
1939 sdcc
1940 \backslash
1941 doc
1942 \end_inset
1943 </cell>
1944 </row>
1945 </lyxtabular>
1946
1947 \end_inset
1948
1949
1950 \layout Verse
1951
1952
1953 \size footnotesize
1954 *compiler, preprocessor, assembler, and linker
1955 \newline
1956 **the
1957 \shape italic
1958 model
1959 \shape default
1960  is auto-appended by the compiler, e.g.
1961  small, large, z80, ds390 etc
1962 \layout Standard
1963 \noindent
1964 The install paths can still be changed during `make install` with e.g.:
1965 \layout LyX-Code
1966
1967 make install prefix=$(HOME)/local/sdcc
1968 \layout Standard
1969
1970 Of course this doesn't change the search paths compiled into the binaries.
1971 \newline
1972
1973 \newline
1974 Moreover the install path can be changed by defining DESTDIR
1975 \begin_inset LatexCommand \index{DESTDIR}
1976
1977 \end_inset
1978
1979 :
1980 \layout LyX-Code
1981
1982 make install DESTDIR=$(HOME)/sdcc.rpm/
1983 \layout Standard
1984
1985 Please note that DESTDIR must have a trailing slash!
1986 \layout Section
1987
1988 Search Paths
1989 \begin_inset LatexCommand \label{sub:Search-Paths}
1990
1991 \end_inset
1992
1993
1994 \begin_inset LatexCommand \index{Search path}
1995
1996 \end_inset
1997
1998
1999 \layout Standard
2000
2001 Some search paths or parts of them are determined by configure variables
2002  (in
2003 \emph on
2004 italics
2005 \emph default
2006 , see section above).
2007  Further search paths are determined by environment variables during runtime.
2008
2009 \newline
2010 The paths searched when running the compiler are as follows (the first catch
2011  wins):
2012 \newline
2013
2014 \newline
2015 1.
2016  Binary files (preprocessor, assembler and linker)
2017 \newline
2018
2019 \layout Standard
2020 \align center
2021
2022 \begin_inset  Tabular
2023 <lyxtabular version="3" rows="4" columns="3">
2024 <features>
2025 <column alignment="block" valignment="top" leftline="true" width="0in">
2026 <column alignment="block" valignment="top" leftline="true" width="0in">
2027 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2028 <row topline="true" bottomline="true">
2029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2030 \begin_inset Text
2031
2032 \layout Standard
2033
2034 Search path
2035 \end_inset
2036 </cell>
2037 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2038 \begin_inset Text
2039
2040 \layout Standard
2041
2042 default
2043 \end_inset
2044 </cell>
2045 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2046 \begin_inset Text
2047
2048 \layout Standard
2049
2050 Win32 builds
2051 \end_inset
2052 </cell>
2053 </row>
2054 <row topline="true">
2055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2056 \begin_inset Text
2057
2058 \layout Standard
2059
2060 $SDCC_HOME/
2061 \emph on
2062 $PPREFIX2BIN_DIR
2063 \end_inset
2064 </cell>
2065 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2066 \begin_inset Text
2067
2068 \layout Standard
2069
2070 $SDCC_HOME/bin
2071 \end_inset
2072 </cell>
2073 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2074 \begin_inset Text
2075
2076 \layout Standard
2077
2078 $SDCC_HOME
2079 \backslash
2080 bin
2081 \end_inset
2082 </cell>
2083 </row>
2084 <row topline="true">
2085 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2086 \begin_inset Text
2087
2088 \layout Standard
2089
2090 Path of argv[0] (if available)
2091 \end_inset
2092 </cell>
2093 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2094 \begin_inset Text
2095
2096 \layout Standard
2097
2098 Path of argv[0]
2099 \end_inset
2100 </cell>
2101 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2102 \begin_inset Text
2103
2104 \layout Standard
2105
2106 Path of argv[0]
2107 \end_inset
2108 </cell>
2109 </row>
2110 <row topline="true" bottomline="true">
2111 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2112 \begin_inset Text
2113
2114 \layout Standard
2115
2116 $PATH
2117 \end_inset
2118 </cell>
2119 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2120 \begin_inset Text
2121
2122 \layout Standard
2123
2124 $PATH
2125 \end_inset
2126 </cell>
2127 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2128 \begin_inset Text
2129
2130 \layout Standard
2131
2132 $PATH
2133 \end_inset
2134 </cell>
2135 </row>
2136 </lyxtabular>
2137
2138 \end_inset
2139
2140
2141 \newline
2142
2143 \layout Standard
2144 \noindent
2145 2.
2146  Include files
2147 \newline
2148
2149 \layout Standard
2150 \align center
2151
2152 \begin_inset  Tabular
2153 <lyxtabular version="3" rows="6" columns="3">
2154 <features>
2155 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2156 <column alignment="block" valignment="top" leftline="true" width="1.5in">
2157 <column alignment="block" valignment="top" leftline="true" rightline="true" width="0in">
2158 <row topline="true" bottomline="true">
2159 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2160 \begin_inset Text
2161
2162 \layout Standard
2163
2164 Search path
2165 \end_inset
2166 </cell>
2167 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2168 \begin_inset Text
2169
2170 \layout Standard
2171
2172 default
2173 \end_inset
2174 </cell>
2175 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2176 \begin_inset Text
2177
2178 \layout Standard
2179
2180 Win32 builds
2181 \end_inset
2182 </cell>
2183 </row>
2184 <row topline="true">
2185 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2186 \begin_inset Text
2187
2188 \layout Standard
2189
2190 -
2191 \begin_inset ERT
2192 status Collapsed
2193
2194 \layout Standard
2195
2196 \backslash
2197 /
2198 \end_inset
2199
2200 -I dir
2201 \end_inset
2202 </cell>
2203 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2204 \begin_inset Text
2205
2206 \layout Standard
2207
2208 -
2209 \begin_inset ERT
2210 status Collapsed
2211
2212 \layout Standard
2213
2214 \backslash
2215 /
2216 \end_inset
2217
2218 -I dir
2219 \end_inset
2220 </cell>
2221 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2222 \begin_inset Text
2223
2224 \layout Standard
2225
2226 -
2227 \begin_inset ERT
2228 status Collapsed
2229
2230 \layout Standard
2231
2232 \backslash
2233 /
2234 \end_inset
2235
2236 -I dir
2237 \end_inset
2238 </cell>
2239 </row>
2240 <row topline="true">
2241 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2242 \begin_inset Text
2243
2244 \layout Standard
2245
2246 $SDCC_INCLUDE
2247 \end_inset
2248 </cell>
2249 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2250 \begin_inset Text
2251
2252 \layout Standard
2253
2254 $SDCC_INCLUDE
2255 \end_inset
2256 </cell>
2257 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2258 \begin_inset Text
2259
2260 \layout Standard
2261
2262 $SDCC_INCLUDE
2263 \end_inset
2264 </cell>
2265 </row>
2266 <row topline="true">
2267 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2268 \begin_inset Text
2269
2270 \layout Standard
2271
2272 $SDCC_HOME/
2273 \newline
2274
2275 \emph on
2276 $PREFIX2DATA_DIR/
2277 \newline
2278 $INCLUDE_DIR_SUFFIX
2279 \end_inset
2280 </cell>
2281 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2282 \begin_inset Text
2283
2284 \layout Standard
2285
2286 $SDCC_ HOME/
2287 \newline
2288 share/sdcc/
2289 \newline
2290 include
2291 \end_inset
2292 </cell>
2293 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2294 \begin_inset Text
2295
2296 \layout Standard
2297
2298 $SDCC_HOME
2299 \backslash
2300 include
2301 \end_inset
2302 </cell>
2303 </row>
2304 <row topline="true">
2305 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2306 \begin_inset Text
2307
2308 \layout Standard
2309
2310 path(argv[0])/
2311 \newline
2312
2313 \emph on
2314 $BIN2DATADIR/
2315 \emph default
2316
2317 \newline
2318
2319 \emph on
2320 $INCLUDE_DIR_SUFFIX
2321 \end_inset
2322 </cell>
2323 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2324 \begin_inset Text
2325
2326 \layout Standard
2327
2328 path(argv[0])/
2329 \newline
2330 ../sdcc/include
2331 \newline
2332 \SpecialChar ~
2333 \SpecialChar ~
2334 \SpecialChar ~
2335 \SpecialChar ~
2336 \SpecialChar ~
2337 \SpecialChar ~
2338 \SpecialChar ~
2339 \SpecialChar ~
2340 \SpecialChar ~
2341 \SpecialChar ~
2342 \SpecialChar ~
2343 \SpecialChar ~
2344 \SpecialChar ~
2345 \SpecialChar ~
2346 \SpecialChar ~
2347 \SpecialChar ~
2348 \SpecialChar ~
2349 \SpecialChar ~
2350 \SpecialChar ~
2351 \SpecialChar ~
2352 \SpecialChar ~
2353 \SpecialChar ~
2354 \SpecialChar ~
2355 \SpecialChar ~
2356 \SpecialChar ~
2357 \SpecialChar ~
2358 \SpecialChar ~
2359 \SpecialChar ~
2360 \SpecialChar ~
2361 \SpecialChar ~
2362 \SpecialChar ~
2363 \SpecialChar ~
2364 \SpecialChar ~
2365 \SpecialChar ~
2366 \SpecialChar ~
2367 \SpecialChar ~
2368 \SpecialChar ~
2369 \SpecialChar ~
2370
2371 \end_inset
2372 </cell>
2373 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2374 \begin_inset Text
2375
2376 \layout Standard
2377
2378 path(argv[0])
2379 \backslash
2380 ..
2381 \backslash
2382 include
2383 \end_inset
2384 </cell>
2385 </row>
2386 <row topline="true" bottomline="true">
2387 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2388 \begin_inset Text
2389
2390 \layout Standard
2391
2392
2393 \emph on
2394 $DATADIR/
2395 \emph default
2396
2397 \newline
2398
2399 \emph on
2400 $INCLUDE_DIR_SUFFIX
2401 \end_inset
2402 </cell>
2403 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2404 \begin_inset Text
2405
2406 \layout Standard
2407
2408 /usr/local/share/sdcc/
2409 \newline
2410 include
2411 \end_inset
2412 </cell>
2413 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2414 \begin_inset Text
2415
2416 \layout Standard
2417
2418 (not on Win32)
2419 \end_inset
2420 </cell>
2421 </row>
2422 </lyxtabular>
2423
2424 \end_inset
2425
2426
2427 \newline
2428
2429 \layout Standard
2430 \noindent
2431 The option -
2432 \begin_inset ERT
2433 status Collapsed
2434
2435 \layout Standard
2436
2437 \backslash
2438 /
2439 \end_inset
2440
2441 -nostdinc disables the last two search paths.
2442 \newline
2443
2444 \newline
2445 3.
2446  Library files
2447 \newline
2448
2449 \layout Standard
2450
2451 With the exception of
2452 \begin_inset Quotes sld
2453 \end_inset
2454
2455 -
2456 \begin_inset ERT
2457 status Collapsed
2458
2459 \layout Standard
2460
2461 \backslash
2462 /
2463 \end_inset
2464
2465 -L dir
2466 \begin_inset Quotes srd
2467 \end_inset
2468
2469  the
2470 \shape italic
2471 model
2472 \shape default
2473  is auto-appended by the compiler (e.g.
2474  small, large, z80, ds390 etc.).
2475
2476 \newline
2477
2478 \layout Standard
2479 \align center
2480
2481 \begin_inset  Tabular
2482 <lyxtabular version="3" rows="6" columns="3">
2483 <features>
2484 <column alignment="block" valignment="top" leftline="true" width="1.7in">
2485 <column alignment="block" valignment="top" leftline="true" width="1.2in">
2486 <column alignment="block" valignment="top" leftline="true" rightline="true" width="1.2in">
2487 <row topline="true" bottomline="true">
2488 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2489 \begin_inset Text
2490
2491 \layout Standard
2492
2493 Search path
2494 \end_inset
2495 </cell>
2496 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2497 \begin_inset Text
2498
2499 \layout Standard
2500
2501 default
2502 \end_inset
2503 </cell>
2504 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2505 \begin_inset Text
2506
2507 \layout Standard
2508
2509 Win32 builds
2510 \end_inset
2511 </cell>
2512 </row>
2513 <row topline="true">
2514 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2515 \begin_inset Text
2516
2517 \layout Standard
2518
2519 -
2520 \begin_inset ERT
2521 status Collapsed
2522
2523 \layout Standard
2524
2525 \backslash
2526 /
2527 \end_inset
2528
2529 -L dir
2530 \end_inset
2531 </cell>
2532 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2533 \begin_inset Text
2534
2535 \layout Standard
2536
2537 -
2538 \begin_inset ERT
2539 status Collapsed
2540
2541 \layout Standard
2542
2543 \backslash
2544 /
2545 \end_inset
2546
2547 -L dir
2548 \end_inset
2549 </cell>
2550 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2551 \begin_inset Text
2552
2553 \layout Standard
2554
2555 -
2556 \begin_inset ERT
2557 status Collapsed
2558
2559 \layout Standard
2560
2561 \backslash
2562 /
2563 \end_inset
2564
2565 -L dir
2566 \end_inset
2567 </cell>
2568 </row>
2569 <row topline="true">
2570 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2571 \begin_inset Text
2572
2573 \layout Standard
2574
2575 $SDCC_LIB/
2576 \newline
2577
2578 \emph on
2579 <model>
2580 \end_inset
2581 </cell>
2582 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2583 \begin_inset Text
2584
2585 \layout Standard
2586
2587 $SDCC_LIB/
2588 \newline
2589
2590 \emph on
2591 <model>
2592 \end_inset
2593 </cell>
2594 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2595 \begin_inset Text
2596
2597 \layout Standard
2598
2599 $SDCC_LIB
2600 \backslash
2601
2602 \newline
2603
2604 \emph on
2605 <model>
2606 \end_inset
2607 </cell>
2608 </row>
2609 <row topline="true">
2610 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2611 \begin_inset Text
2612
2613 \layout Standard
2614
2615 $SDCC_HOME/
2616 \newline
2617
2618 \emph on
2619 $PREFIX2DATA_DIR/
2620 \newline
2621 $LIB_DIR_SUFFIX/<model>
2622 \end_inset
2623 </cell>
2624 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2625 \begin_inset Text
2626
2627 \layout Standard
2628
2629 $SDCC_HOME/
2630 \newline
2631 share/sdcc/
2632 \newline
2633 lib/
2634 \emph on
2635 <model>
2636 \end_inset
2637 </cell>
2638 <cell alignment="left" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2639 \begin_inset Text
2640
2641 \layout Standard
2642
2643 $SDCC_HOME
2644 \backslash
2645 lib
2646 \backslash
2647
2648 \emph on
2649
2650 \newline
2651 <model>
2652 \end_inset
2653 </cell>
2654 </row>
2655 <row topline="true">
2656 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2657 \begin_inset Text
2658
2659 \layout Standard
2660
2661 path(argv[0])/
2662 \newline
2663
2664 \emph on
2665 $BIN2DATADIR/
2666 \emph default
2667
2668 \newline
2669
2670 \emph on
2671 $LIB_DIR_SUFFIX/<model>
2672 \end_inset
2673 </cell>
2674 <cell alignment="left" valignment="top" topline="true" leftline="true" usebox="none">
2675 \begin_inset Text
2676
2677 \layout Standard
2678
2679 path(argv[0])/
2680 \newline
2681 ../sdcc/lib/
2682 \emph on
2683 <model>
2684 \newline
2685 \SpecialChar ~
2686 \SpecialChar ~
2687 \SpecialChar ~
2688 \SpecialChar ~
2689 \SpecialChar ~
2690 \SpecialChar ~
2691 \SpecialChar ~
2692 \SpecialChar ~
2693 \SpecialChar ~
2694 \SpecialChar ~
2695 \SpecialChar ~
2696 \SpecialChar ~
2697 \SpecialChar ~
2698 \SpecialChar ~
2699 \SpecialChar ~
2700 \SpecialChar ~
2701 \SpecialChar ~
2702 \SpecialChar ~
2703 \SpecialChar ~
2704 \SpecialChar ~
2705 \SpecialChar ~
2706 \SpecialChar ~
2707 \SpecialChar ~
2708 \SpecialChar ~
2709 \SpecialChar ~
2710 \SpecialChar ~
2711 \SpecialChar ~
2712 \SpecialChar ~
2713 \SpecialChar ~
2714 \SpecialChar ~
2715 \SpecialChar ~
2716 \SpecialChar ~
2717 \SpecialChar ~
2718 \SpecialChar ~
2719 \SpecialChar ~
2720 \SpecialChar ~
2721 \SpecialChar ~
2722 \SpecialChar ~
2723 \SpecialChar ~
2724
2725 \end_inset
2726 </cell>
2727 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2728 \begin_inset Text
2729
2730 \layout Standard
2731
2732 path(argv[0])
2733 \backslash
2734
2735 \newline
2736 ..
2737 \backslash
2738 lib
2739 \backslash
2740
2741 \emph on
2742 <model>
2743 \newline
2744 \SpecialChar ~
2745 \SpecialChar ~
2746 \SpecialChar ~
2747 \SpecialChar ~
2748 \SpecialChar ~
2749 \SpecialChar ~
2750 \SpecialChar ~
2751 \SpecialChar ~
2752 \SpecialChar ~
2753 \SpecialChar ~
2754 \SpecialChar ~
2755 \SpecialChar ~
2756 \SpecialChar ~
2757 \SpecialChar ~
2758 \SpecialChar ~
2759 \SpecialChar ~
2760 \SpecialChar ~
2761 \SpecialChar ~
2762 \SpecialChar ~
2763 \SpecialChar ~
2764 \SpecialChar ~
2765 \SpecialChar ~
2766 \SpecialChar ~
2767 \SpecialChar ~
2768 \SpecialChar ~
2769 \SpecialChar ~
2770 \SpecialChar ~
2771 \SpecialChar ~
2772 \SpecialChar ~
2773 \SpecialChar ~
2774 \SpecialChar ~
2775 \SpecialChar ~
2776 \SpecialChar ~
2777 \SpecialChar ~
2778 \SpecialChar ~
2779
2780 \end_inset
2781 </cell>
2782 </row>
2783 <row topline="true" bottomline="true">
2784 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2785 \begin_inset Text
2786
2787 \layout Standard
2788
2789
2790 \emph on
2791 $DATADIR/
2792 \newline
2793 $LIB_DIR_SUFFIX/<model>
2794 \end_inset
2795 </cell>
2796 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
2797 \begin_inset Text
2798
2799 \layout Standard
2800
2801 /usr/local/share/sdcc/
2802 \newline
2803 lib/
2804 \emph on
2805 <model>
2806 \end_inset
2807 </cell>
2808 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
2809 \begin_inset Text
2810
2811 \layout Standard
2812
2813 (not on Win32)
2814 \end_inset
2815 </cell>
2816 </row>
2817 </lyxtabular>
2818
2819 \end_inset
2820
2821
2822 \newline
2823
2824 \layout Comment
2825
2826 Don't delete any of the stray spaces in the table above without checking
2827  the HTML output (last line)!
2828 \layout Standard
2829
2830 \SpecialChar ~
2831
2832 \newline
2833 The option -
2834 \begin_inset ERT
2835 status Collapsed
2836
2837 \layout Standard
2838
2839 \backslash
2840 /
2841 \end_inset
2842
2843 -nostdlib disables the last two search paths.
2844 \layout Section
2845
2846 Building SDCC
2847 \begin_inset LatexCommand \index{Building SDCC}
2848
2849 \end_inset
2850
2851
2852 \layout Subsection
2853
2854 Building SDCC on Linux
2855 \begin_inset LatexCommand \label{sub:Building-SDCC-on-Linux}
2856
2857 \end_inset
2858
2859
2860 \layout Enumerate
2861
2862
2863 \series medium
2864 Download the source package
2865 \series default
2866  either from the SDCC CVS repository or from the nightly snapshots
2867 \series medium
2868 , it will be named something like sdcc
2869 \series default
2870 .src
2871 \series medium
2872 .t
2873 \series default
2874 ar.
2875 \series medium
2876 gz
2877 \series default
2878
2879 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
2880
2881 \end_inset
2882
2883 .
2884 \layout Enumerate
2885
2886
2887 \series medium
2888 Bring up a command line terminal, such as xterm.
2889 \layout Enumerate
2890
2891
2892 \series medium
2893 Unpack the file using a command like:
2894 \family sans
2895 \series bold
2896 "tar -xvzf sdcc.src.tar.gz
2897 \family default
2898 \series default
2899 "
2900 \series medium
2901 , this will create a sub-directory called sdcc with all of the sources.
2902 \layout Enumerate
2903
2904 Change directory into the main SDCC directory, for example type:
2905 \family sans
2906 \series bold
2907 "cd sdcc
2908 \series default
2909 ".
2910 \layout Enumerate
2911
2912
2913 \series medium
2914 Type
2915 \family sans
2916 \series bold
2917 "./configure
2918 \family default
2919 \series default
2920 ".
2921  This configures the package for compilation on your system.
2922 \layout Enumerate
2923
2924
2925 \series medium
2926 Type
2927 \family sans
2928 \series bold
2929 "make
2930 \family default
2931 \series default
2932 "
2933 \series medium
2934 .
2935
2936 \series default
2937  All of the source packages will compile, this can take a while.
2938 \layout Enumerate
2939
2940
2941 \series medium
2942 Type
2943 \family sans
2944 \series bold
2945 "make install"
2946 \family default
2947 \series default
2948  as root
2949 \series medium
2950 .
2951
2952 \series default
2953  This copies the binary executables, the include files, the libraries and
2954  the documentation to the install directories.
2955  Proceed with section
2956 \begin_inset LatexCommand \ref{sec:Testing-the-SDCC}
2957
2958 \end_inset
2959
2960 .
2961 \layout Subsection
2962
2963 Building SDCC on OSX 2.x
2964 \layout Standard
2965
2966 Follow the instruction for Linux.
2967 \newline
2968
2969 \newline
2970 On OSX 2.x it was reported, that the default gcc (version 3.1 20020420 (prerelease
2971 )) fails to compile SDCC.
2972  Fortunately there's also gcc 2.9.x installed, which works fine.
2973  This compiler can be selected by running 'configure' with:
2974 \layout LyX-Code
2975
2976 ./configure CC=gcc2 CXX=g++2
2977 \layout Subsection
2978
2979 Cross compiling SDCC on Linux for Windows
2980 \layout Standard
2981
2982 With the Mingw32 gcc cross compiler it's easy to compile SDCC for Win32.
2983  See section 'Configure Options'.
2984 \layout Subsection
2985
2986 Building SDCC on Windows
2987 \layout Standard
2988
2989 With the exception of Cygwin the SDCC binaries uCsim and sdcdb can't be
2990  built on Windows.
2991  They use Unix-sockets, which are not available on Win32.
2992 \layout Subsection
2993
2994 Building SDCC using Cygwin and Mingw32
2995 \layout Standard
2996
2997 For building and installing a Cygwin executable follow the instructions
2998  for Linux.
2999 \newline
3000
3001 \newline
3002 On Cygwin a
3003 \begin_inset Quotes sld
3004 \end_inset
3005
3006 native
3007 \begin_inset Quotes srd
3008 \end_inset
3009
3010  Win32-binary can be built, which will not need the Cygwin-DLL.
3011  For the necessary 'configure' options see section 'configure options' or
3012  the script 'sdcc/support/scripts/sdcc_cygwin_mingw32'.
3013 \newline
3014
3015 \newline
3016 In order to install Cygwin on Windows download setup.exe from
3017 \begin_inset LatexCommand \url[www.cygwin.com]{http://www.cygwin.com/}
3018
3019 \end_inset
3020
3021 .
3022  Run it, set the
3023 \begin_inset Quotes sld
3024 \end_inset
3025
3026 default text file type
3027 \begin_inset Quotes srd
3028 \end_inset
3029
3030  to
3031 \begin_inset Quotes sld
3032 \end_inset
3033
3034 unix
3035 \begin_inset Quotes srd
3036 \end_inset
3037
3038  and download/install at least the following packages.
3039  Some packages are selected by default, others will be automatically selected
3040  because of dependencies with the manually selected packages.
3041  Never deselect these packages!
3042 \layout Itemize
3043
3044 flex
3045 \layout Itemize
3046
3047 bison
3048 \layout Itemize
3049
3050 gcc ; version 3.x is fine, no need to use the old 2.9x
3051 \layout Itemize
3052
3053 binutils ; selected with gcc
3054 \layout Itemize
3055
3056 make
3057 \layout Itemize
3058
3059 rxvt ; a nice console, which makes life much easier under windoze (see below)
3060 \layout Itemize
3061
3062 man ; not really needed for building SDCC, but you'll miss it sooner or
3063  later
3064 \layout Itemize
3065
3066 less ; not really needed for building SDCC, but you'll miss it sooner or
3067  later
3068 \layout Itemize
3069
3070 cvs ; only if you use CVS access
3071 \layout Standard
3072
3073 If you want to develop something you'll need:
3074 \layout Itemize
3075
3076 python ; for the regression tests
3077 \layout Itemize
3078
3079 gdb ; the gnu debugger, together with the nice GUI
3080 \begin_inset Quotes sld
3081 \end_inset
3082
3083 insight
3084 \begin_inset Quotes srd
3085 \end_inset
3086
3087
3088 \layout Itemize
3089
3090 openssh ; to access the CF or commit changes
3091 \layout Itemize
3092
3093 autoconf and autoconf-devel ; if you want to fight with 'configure', don't
3094  use autoconf-stable!
3095 \layout Standard
3096
3097 rxvt is a nice console with history.
3098  Replace in your cygwin.bat the line
3099 \layout LyX-Code
3100
3101 bash -
3102 \begin_inset ERT
3103 status Collapsed
3104
3105 \layout Standard
3106
3107 \backslash
3108 /
3109 \end_inset
3110
3111 -login -i
3112 \layout Standard
3113
3114 with (one line):
3115 \layout LyX-Code
3116
3117 rxvt -sl 1000 -fn "Lucida Console-12" -sr -cr red
3118 \layout LyX-Code
3119
3120      -bg black -fg white -geometry 100x65 -e bash -
3121 \begin_inset ERT
3122 status Collapsed
3123
3124 \layout Standard
3125
3126 \backslash
3127 /
3128 \end_inset
3129
3130 -login
3131 \layout Standard
3132
3133 Text selected with the mouse is automatically copied to the clipboard, pasting
3134  works with shift-insert.
3135 \newline
3136
3137 \newline
3138 The other good tip is to make sure you have no //c/-style paths anywhere,
3139  use /cygdrive/c/ instead.
3140  Using // invokes a network lookup which is very slow.
3141  If you think
3142 \begin_inset Quotes sld
3143 \end_inset
3144
3145 cygdrive
3146 \begin_inset Quotes srd
3147 \end_inset
3148
3149  is too long, you can change it with e.g.
3150 \layout LyX-Code
3151
3152 mount -s -u -c /mnt
3153 \layout Standard
3154
3155 SDCC sources use the unix line ending LF.
3156  Life is much easier, if you store the source tree on a drive which is mounted
3157  in binary mode.
3158  And use an editor which can handle LF-only line endings.
3159  Make sure not to commit files with windows line endings.
3160  The tabulator spacing
3161 \begin_inset LatexCommand \index{tabulator spacing (8 columns)}
3162
3163 \end_inset
3164
3165  used in the project is 8.
3166  Although a tabulator spacing of 8 is a sensible choice for programmers
3167  (it's a power of 2 and allows to display 8/16 bit signed variables without
3168  loosing columns) the plan is to move towards using only spaces in the source.
3169 \layout Subsection
3170
3171 Building SDCC Using Microsoft Visual C++ 6.0/NET (MSVC)
3172 \layout Standard
3173
3174
3175 \series medium
3176 Download the source package
3177 \series default
3178  either from the SDCC CVS repository or from the
3179 \begin_inset LatexCommand \url[nightly snapshots]{http://sdcc.sourceforge.net/snap.php}
3180
3181 \end_inset
3182
3183
3184 \series medium
3185 , it will be named something like sdcc
3186 \series default
3187 .src
3188 \series medium
3189 .tgz.
3190
3191 \series default
3192  SDCC is distributed with all the projects, workspaces, and files you need
3193  to build it using Visual C++ 6.0/NET (except for sdcdb.exe which currently
3194  doesn't build under MSVC).
3195  The workspace name is 'sdcc.dsw'.
3196  Please note that as it is now, all the executables are created in a folder
3197  called sdcc
3198 \backslash
3199 bin_vc.
3200  Once built you need to copy the executables from sdcc
3201 \backslash
3202 bin_vc to sdcc
3203 \backslash
3204 bin before running SDCC.
3205
3206 \newline
3207
3208 \newline
3209 WARNING: Visual studio is very picky with line terminations; it expects
3210  the 0x0d, 0x0a DOS style line endings, not the 0x0a Unix style line endings.
3211  If you are getting a message such as "This makefile was not generated by
3212  Developer Studio etc.
3213  etc.
3214 \begin_inset Quotes srd
3215 \end_inset
3216
3217  when opening the sdcc.dsw workspace or any of the *.dsp projects, then you
3218  need to convert the Unix style line endings to DOS style line endings.
3219  To do so you can use the
3220 \begin_inset Quotes sld
3221 \end_inset
3222
3223 unix2dos
3224 \begin_inset Quotes srd
3225 \end_inset
3226
3227  utility freely available on the internet.
3228  Doug Hawkins reported in the sdcc-user list that this works:
3229 \newline
3230
3231 \newline
3232 C:
3233 \backslash
3234 Programming
3235 \backslash
3236 SDCC> unix2dos sdcc.dsw
3237 \newline
3238 C:
3239 \backslash
3240 Programming
3241 \backslash
3242 SDCC> for /R %I in (*.dsp) do @unix2dos "%I"
3243 \newline
3244
3245 \newline
3246 In order to build SDCC with MSVC you need win32 executables of bison.exe,
3247  flex.exe, and gawk.exe.
3248  One good place to get them is
3249 \begin_inset LatexCommand \url[here]{http://unxutils.sourceforge.net}
3250
3251 \end_inset
3252
3253
3254 \newline
3255
3256 \newline
3257 Download the file UnxUtils
3258 \begin_inset LatexCommand \index{UnxUtils}
3259
3260 \end_inset
3261
3262 .zip.
3263  Now you have to install the utilities and setup MSVC so it can locate the
3264  required programs.
3265  Here there are two alternatives (choose one!):
3266 \layout Enumerate
3267
3268 The easy way:
3269 \newline
3270
3271 \newline
3272 a) Extract UnxUtils.zip to your C:
3273 \backslash
3274  hard disk PRESERVING the original paths, otherwise bison won't work.
3275  (If you are using WinZip make certain that 'Use folder names' is selected)
3276 \newline
3277
3278 \newline
3279 b) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3280  in 'Show directories for:' select 'Executable files', and in the directories
3281  window add a new path: 'C:
3282 \backslash
3283 user
3284 \backslash
3285 local
3286 \backslash
3287 wbin', click ok.
3288 \newline
3289
3290 \newline
3291 (As a side effect, you get a bunch of Unix utilities that could be useful,
3292  such as diff and patch.)
3293 \layout Enumerate
3294
3295 A more compact way:
3296 \newline
3297
3298 \newline
3299 This one avoids extracting a bunch of files you may not use, but requires
3300  some extra work:
3301 \newline
3302
3303 \newline
3304 a) Create a directory were to put the tools needed, or use a directory already
3305  present.
3306  Say for example 'C:
3307 \backslash
3308 util'.
3309 \newline
3310
3311 \newline
3312 b) Extract 'bison.exe', 'bison.hairy', 'bison.simple', 'flex.exe', and gawk.exe
3313  to such directory WITHOUT preserving the original paths.
3314  (If you are using WinZip make certain that 'Use folder names' is not selected)
3315 \newline
3316
3317 \newline
3318 c) Rename bison.exe to '_bison.exe'.
3319 \newline
3320
3321 \newline
3322 d) Create a batch file 'bison.bat' in 'C:
3323 \backslash
3324 util
3325 \backslash
3326 ' and add these lines:
3327 \newline
3328 \SpecialChar ~
3329 \SpecialChar ~
3330 set BISON_SIMPLE=C:
3331 \backslash
3332 util
3333 \backslash
3334 bison.simple
3335 \newline
3336 \SpecialChar ~
3337 \SpecialChar ~
3338 set BISON_HAIRY=C:
3339 \backslash
3340 util
3341 \backslash
3342 bison.hairy
3343 \newline
3344 \SpecialChar ~
3345 \SpecialChar ~
3346 _bison %1 %2 %3 %4 %5 %6 %7 %8 %9
3347 \newline
3348
3349 \newline
3350 Steps 'c' and 'd' are needed because bison requires by default that the
3351  files 'bison.simple' and 'bison.hairy' reside in some weird Unix directory,
3352  '/usr/local/share/' I think.
3353  So it is necessary to tell bison where those files are located if they
3354  are not in such directory.
3355  That is the function of the environment variables BISON_SIMPLE and BISON_HAIRY.
3356 \newline
3357
3358 \newline
3359 e) In the Visual C++ IDE click Tools, Options, select the Directory tab,
3360  in 'Show directories for:' select 'Executable files', and in the directories
3361  window add a new path: 'c:
3362 \backslash
3363 util', click ok.
3364  Note that you can use any other path instead of 'c:
3365 \backslash
3366 util', even the path where the Visual C++ tools are, probably: 'C:
3367 \backslash
3368 Program Files
3369 \backslash
3370 Microsoft Visual Studio
3371 \backslash
3372 Common
3373 \backslash
3374 Tools'.
3375  So you don't have to execute step 'e' :)
3376 \layout Standard
3377
3378 That is it.
3379  Open 'sdcc.dsw' in Visual Studio, click 'build all', when it finishes copy
3380  the executables from sdcc
3381 \backslash
3382 bin_vc to sdcc
3383 \backslash
3384 bin, and you can compile using SDCC.
3385 \layout Subsection
3386
3387 Building SDCC Using Borland
3388 \layout Enumerate
3389
3390 From the sdcc directory, run the command "make -f Makefile.bcc".
3391  This should regenerate all the .exe files in the bin directory except for
3392  sdcdb.exe (which currently doesn't build under Borland C++).
3393 \layout Enumerate
3394
3395 If you modify any source files and need to rebuild, be aware that the dependenci
3396 es may not be correctly calculated.
3397  The safest option is to delete all .obj files and run the build again.
3398  From a Cygwin BASH prompt, this can easily be done with the command (be
3399  sure you are in the sdcc directory):
3400 \newline
3401
3402 \newline
3403
3404 \family sans
3405 \series bold
3406 find .
3407
3408 \backslash
3409 ( -name '*.obj' -o -name '*.lib' -o -name '*.rul'
3410 \backslash
3411 ) -print -exec rm {}
3412 \backslash
3413 ;
3414 \family default
3415 \series default
3416
3417 \newline
3418
3419 \newline
3420 or on Windows NT/2000/XP from the command prompt with the command:
3421 \newline
3422
3423 \family sans
3424 \series bold
3425
3426 \newline
3427 del /s *.obj *.lib *.rul
3428 \family default
3429 \series default
3430  from the sdcc directory.
3431 \layout Subsection
3432
3433 Windows Install Using a Binary Package
3434 \begin_inset LatexCommand \label{sub:Windows-Install}
3435
3436 \end_inset
3437
3438
3439 \layout Enumerate
3440
3441 Download the binary package from
3442 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3443
3444 \end_inset
3445
3446  and unpack it using your favorite unpacking tool (gunzip, WinZip, etc).
3447  This should unpack to a group of sub-directories.
3448  An example directory structure after unpacking the mingw32 package is:
3449  c:
3450 \backslash
3451 sdcc
3452 \backslash
3453 bin for the executables, c:
3454 \backslash
3455 sdcc
3456 \backslash
3457 include and c:
3458 \backslash
3459 sdcc
3460 \backslash
3461 lib for the include and libraries.
3462 \layout Enumerate
3463
3464 Adjust your environment variable PATH to include the location of the bin
3465  directory or start sdcc using the full path.
3466 \layout Section
3467
3468 Building the Documentation
3469 \layout Standard
3470
3471 If the necessary tools (LyX, LaTeX, LaTeX2HTML) are installed it is as easy
3472  as changing into the doc directory and typing
3473 \family sans
3474 \series bold
3475
3476 \begin_inset Quotes srd
3477 \end_inset
3478
3479 make
3480 \begin_inset Quotes srd
3481 \end_inset
3482
3483
3484 \family default
3485 \series default
3486  there.
3487  You're invited to make changes and additions to this manual (sdcc/doc/sdccman.ly
3488 x).
3489  Using LyX
3490 \begin_inset LatexCommand \url{www.lyx.org}
3491
3492 \end_inset
3493
3494  as editor this is straightforward.
3495  Prebuilt documentation in html and pdf format is available from
3496 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/snap.php}
3497
3498 \end_inset
3499
3500 .
3501 \layout Section
3502
3503 Reading the Documentation
3504 \layout Standard
3505
3506 Currently reading the document in pdf format is recommended, as for unknown
3507  reason the hyperlinks are working there whereas in the html version they
3508  are not
3509 \begin_inset Foot
3510 collapsed false
3511
3512 \layout Standard
3513
3514 If you should know why please drop us a note
3515 \end_inset
3516
3517 .
3518  You'll find the pdf version at
3519 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net/doc/sdccman.pdf}
3520
3521 \end_inset
3522
3523 .
3524 \newline
3525 This documentation is in some aspects different from a commercial documentation:
3526
3527 \layout Itemize
3528
3529 It tries to document SDCC for several processor architectures in one document
3530  (commercially these probably would be separate documents/products).
3531  This document
3532 \begin_inset LatexCommand \index{Status of documentation}
3533
3534 \end_inset
3535
3536  currently matches SDCC for mcs51 and DS390 best and does give too few informati
3537 on about f.e.
3538  Z80, PIC14, PIC16 and HC08.
3539 \layout Itemize
3540
3541 There are many references pointing away from this documentation.
3542  Don't let this distract you.
3543  If there f.e.
3544  was a reference like
3545 \begin_inset LatexCommand \url{www.opencores.org}
3546
3547 \end_inset
3548
3549  together with a statement
3550 \begin_inset Quotes sld
3551 \end_inset
3552
3553 some processors which are targetted by SDCC can be implemented in a
3554 \emph on
3555 f
3556 \emph default
3557 ield
3558 \emph on
3559 p
3560 \emph default
3561 rogrammable
3562 \emph on
3563 g
3564 \emph default
3565 ate
3566 \emph on
3567 a
3568 \emph default
3569 rray
3570 \begin_inset LatexCommand \index{fpga (field programmable gate array)}
3571
3572 \end_inset
3573
3574
3575 \begin_inset Quotes srd
3576 \end_inset
3577
3578  we expect you to have a quick look there and come back.
3579  If you read this you are on the right track.
3580 \layout Itemize
3581
3582 Some sections attribute more space to problems, restrictions and warnings
3583  than to the solution.
3584 \layout Itemize
3585
3586 The installation section and the section about the debugger is intimidating.
3587 \layout Itemize
3588
3589 There are still lots of typos and there are more different writing styles
3590  than pictures.
3591 \layout Section
3592
3593 Testing the SDCC Compiler
3594 \begin_inset LatexCommand \label{sec:Testing-the-SDCC}
3595
3596 \end_inset
3597
3598
3599 \layout Standard
3600
3601 The first thing you should do after installing your SDCC compiler is to
3602  see if it runs.
3603  Type
3604 \family sans
3605 \series bold
3606 "sdcc -
3607 \begin_inset ERT
3608 status Collapsed
3609
3610 \layout Standard
3611
3612 \backslash
3613 /
3614 \end_inset
3615
3616 -version"
3617 \begin_inset LatexCommand \index{version}
3618
3619 \end_inset
3620
3621
3622 \family default
3623 \series default
3624  at the prompt, and the program should run and tell you the version.
3625  If it doesn't run, or gives a message about not finding sdcc program, then
3626  you need to check over your installation.
3627  Make sure that the sdcc bin directory is in your executable search path
3628  defined by the PATH environment setting (
3629 \series medium
3630 see
3631 \series default
3632 section
3633 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3634
3635 \end_inset
3636
3637 \SpecialChar ~
3638
3639 \series medium
3640 Install trouble-shooting for suggestions
3641 \series default
3642 ).
3643  Make sure that the sdcc program is in the bin folder, if not perhaps something
3644  did not install correctly.
3645 \newline
3646
3647 \newline
3648
3649 \series medium
3650 SDCC
3651 \series default
3652 is commonly installed as described in section
3653 \begin_inset Quotes sld
3654 \end_inset
3655
3656 Install and search paths
3657 \begin_inset Quotes srd
3658 \end_inset
3659
3660 .
3661 \newline
3662
3663 \newline
3664
3665 \series medium
3666 Make sure the compiler works on a very simple example.
3667  Type in the following test.c program using your favorite
3668 \series default
3669 ASCII
3670 \series medium
3671 editor:
3672 \layout Verse
3673
3674
3675 \family typewriter
3676 char test;
3677 \newline
3678
3679 \newline
3680 void main(void) {
3681 \newline
3682 \SpecialChar ~
3683 \SpecialChar ~
3684 \SpecialChar ~
3685 \SpecialChar ~
3686 test=0;
3687 \newline
3688 }
3689 \layout Standard
3690
3691
3692 \series medium
3693 Compile this using the following command:
3694 \family sans
3695 \series bold
3696 "sdcc -c test.c".
3697
3698 \family default
3699 \series default
3700
3701 \series medium
3702 If all goes well, the compiler will generate a test.asm and test.rel file.
3703  Congratulations, you've just compiled your first program with SDCC.
3704  We used the -c option to tell SDCC not to link the generated code, just
3705  to keep things simple for this step.
3706 \series default
3707
3708 \newline
3709
3710 \newline
3711
3712 \series medium
3713 The next step is to try it with the linker.
3714  Type in
3715 \family sans
3716 \series bold
3717 "sdcc test.c
3718 \family default
3719 \series default
3720 "
3721 \series medium
3722 .
3723  If all goes well the compiler will link with the libraries and produce
3724  a test.ihx output file.
3725  If this step fails
3726 \series default
3727
3728 \series medium
3729 (no test.ihx, and the linker generates warnings), then the problem is most
3730  likely that
3731 \series default
3732 SDCC
3733 \series medium
3734  cannot find the
3735 \series default
3736 /
3737 \series medium
3738 usr/local/share/sdcc/lib directory
3739 \series default
3740
3741 \series medium
3742 (see
3743 \series default
3744 section
3745 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3746
3747 \end_inset
3748
3749 \SpecialChar ~
3750
3751 \series medium
3752 Install trouble-shooting for suggestions).
3753 \series default
3754
3755 \newline
3756
3757 \newline
3758
3759 \series medium
3760 The final test is to ensure
3761 \series default
3762 SDCC
3763 \series medium
3764  can use the
3765 \series default
3766 standard
3767 \series medium
3768  header files and libraries.
3769  Edit test.c and change it to the following:
3770 \layout Verse
3771
3772
3773 \family typewriter
3774 #include <string.h>
3775 \newline
3776
3777 \newline
3778 char str1[10];
3779 \newline
3780
3781 \newline
3782 void main(void) {
3783 \newline
3784 \SpecialChar ~
3785 \SpecialChar ~
3786 strcpy(str1, "testing");
3787 \newline
3788 }
3789 \layout Standard
3790
3791
3792 \series medium
3793 Compile this by typing
3794 \family sans
3795 \series bold
3796 "sdcc test.c"
3797 \family default
3798 \series medium
3799 .
3800  This should generate a test.ihx output file, and it should give no warnings
3801  such as not finding the string.h file.
3802  If it cannot find the string.h file, then the problem is that
3803 \series default
3804 SDCC
3805 \series medium
3806  cannot find the /usr/local/share/sdcc/include directory
3807 \series default
3808
3809 \series medium
3810 (see the
3811 \series default
3812 section
3813 \begin_inset LatexCommand \ref{sub:Install-Trouble-shooting}
3814
3815 \end_inset
3816
3817 \SpecialChar ~
3818
3819 \series medium
3820 Install trouble-shooting section for suggestions).
3821
3822 \series default
3823  Use option
3824 \series bold
3825 -
3826 \begin_inset ERT
3827 status Collapsed
3828
3829 \layout Standard
3830
3831 \backslash
3832 /
3833 \end_inset
3834
3835 -print-search-dirs
3836 \series default
3837
3838 \begin_inset LatexCommand \index{-\/-print-search-dirs}
3839
3840 \end_inset
3841
3842  to find exactly where SDCC is looking for the include and lib files.
3843 \layout Section
3844
3845 Install Trouble-shooting
3846 \begin_inset LatexCommand \label{sub:Install-Trouble-shooting}
3847
3848 \end_inset
3849
3850
3851 \begin_inset LatexCommand \index{Install trouble-shooting}
3852
3853 \end_inset
3854
3855
3856 \layout Subsection
3857
3858 If SDCC does not build correctly
3859 \layout Standard
3860
3861 A thing to try is starting from scratch by unpacking the .tgz source package
3862  again in an empty directory.
3863  Configure it like:
3864 \newline
3865
3866 \newline
3867
3868 \family sans
3869 \series bold
3870 ./configure 2>&1 | tee configure.log
3871 \family default
3872 \series default
3873
3874 \newline
3875
3876 \newline
3877 and build it like:
3878 \newline
3879
3880 \newline
3881
3882 \family sans
3883 \series bold
3884 make 2>&1 | tee make.log
3885 \family default
3886 \series default
3887
3888 \newline
3889
3890 \newline
3891 If anything goes wrong, you can review the log files to locate the problem.
3892  Or a relevant part of this can be attached to an email that could be helpful
3893  when requesting help from the mailing list.
3894 \layout Subsection
3895
3896 What the
3897 \begin_inset Quotes sld
3898 \end_inset
3899
3900 ./configure
3901 \begin_inset Quotes srd
3902 \end_inset
3903
3904  does
3905 \layout Standard
3906
3907 The
3908 \begin_inset Quotes sld
3909 \end_inset
3910
3911 ./configure
3912 \begin_inset Quotes srd
3913 \end_inset
3914
3915  command is a script that analyzes your system and performs some configuration
3916  to ensure the source package compiles on your system.
3917  It will take a few minutes to run, and will compile a few tests to determine
3918  what compiler features are installed.
3919 \layout Subsection
3920
3921 What the
3922 \begin_inset Quotes sld
3923 \end_inset
3924
3925 make
3926 \begin_inset Quotes srd
3927 \end_inset
3928
3929  does
3930 \layout Standard
3931
3932 This runs the GNU make tool, which automatically compiles all the source
3933  packages into the final installed binary executables.
3934 \layout Subsection
3935
3936 What the
3937 \begin_inset Quotes sld
3938 \end_inset
3939
3940 make install
3941 \begin_inset Quotes erd
3942 \end_inset
3943
3944  command does.
3945 \layout Standard
3946
3947 This will install the compiler, other executables libraries and include
3948  files into the appropriate directories.
3949  See sections
3950 \begin_inset LatexCommand \ref{sub:Install-paths}
3951
3952 \end_inset
3953
3954 ,\SpecialChar ~
3955
3956 \begin_inset LatexCommand \ref{sub:Search-Paths}
3957
3958 \end_inset
3959
3960 \SpecialChar ~
3961 about install and search paths.
3962 \newline
3963 On most systems you will need super-user privileges to do this.
3964 \layout Section
3965
3966 Components of SDCC
3967 \layout Standard
3968
3969 SDCC is not just a compiler, but a collection of tools by various developers.
3970  These include linkers, assemblers, simulators and other components.
3971  Here is a summary of some of the components.
3972  Note that the included simulator and assembler have separate documentation
3973  which you can find in the source package in their respective directories.
3974  As SDCC grows to include support for other processors, other packages from
3975  various developers are included and may have their own sets of documentation.
3976 \newline
3977
3978 \newline
3979 You might want to look at the files which are installed in <installdir>.
3980  At the time of this writing, we find the following programs for gcc-builds:
3981 \newline
3982
3983 \newline
3984 In <installdir>/bin:
3985 \layout Itemize
3986
3987 sdcc - The compiler.
3988 \layout Itemize
3989
3990 sdcpp - The C preprocessor.
3991 \layout Itemize
3992
3993 asx8051 - The assembler for 8051 type processors.
3994 \layout Itemize
3995
3996 as-z80
3997 \series bold
3998 ,
3999 \series default
4000 as-gbz80 - The Z80 and GameBoy Z80 assemblers.
4001 \layout Itemize
4002
4003 aslink -The linker for 8051 type processors.
4004 \layout Itemize
4005
4006 link-z80
4007 \series bold
4008 ,
4009 \series default
4010 link-gbz80 - The Z80 and GameBoy Z80 linkers.
4011 \layout Itemize
4012
4013 s51 - The ucSim 8051 simulator.
4014 \layout Itemize
4015
4016 sdcdb - The source debugger.
4017 \layout Itemize
4018
4019 packihx - A tool to pack (compress) Intel hex files.
4020 \layout Standard
4021
4022 In <installdir>/share/sdcc/include
4023 \layout Itemize
4024
4025 the include files
4026 \layout Standard
4027
4028 In <installdir>/share/sdcc/lib
4029 \layout Itemize
4030
4031 the subdirs src and small, large, z80, gbz80 and ds390 with the precompiled
4032  relocatables.
4033 \layout Standard
4034
4035 In <installdir>/share/sdcc/doc
4036 \layout Itemize
4037
4038 the documentation
4039 \layout Standard
4040
4041 As development for other processors proceeds, this list will expand to include
4042  executables to support processors like AVR, PIC, etc.
4043 \layout Subsection
4044
4045 sdcc - The Compiler
4046 \layout Standard
4047
4048 This is the actual compiler, it in turn uses the c-preprocessor and invokes
4049  the assembler and linkage editor.
4050 \layout Subsection
4051
4052 sdcpp - The C-Preprocessor
4053 \layout Standard
4054
4055 The preprocessor
4056 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
4057
4058 \end_inset
4059
4060  is a modified version of the GNU preprocessor.
4061  The C preprocessor is used to pull in #include sources, process #ifdef
4062  statements, #defines and so on.
4063 \layout Subsection
4064
4065 as
4066 \emph on
4067 xxxx
4068 \emph default
4069 , aslink, link-
4070 \emph on
4071 xxx
4072 \emph default
4073  - The Assemblers and Linkage Editors
4074 \layout Standard
4075
4076 This is retargettable assembler & linkage editor, it was developed by Alan
4077  Baldwin.
4078  John Hartman created the version for 8051, and I (Sandeep) have made some
4079  enhancements and bug fixes for it to work properly with SDCC.
4080 \layout Subsection
4081
4082 s51 - The Simulator
4083 \layout Standard
4084
4085 S51
4086 \begin_inset LatexCommand \index{s51}
4087
4088 \end_inset
4089
4090  is a freeware, opensource simulator developed by Daniel Drotos (
4091 \begin_inset LatexCommand \url{mailto:drdani@mazsola.iit.uni-miskolc.hu}
4092
4093 \end_inset
4094
4095 ).
4096  The simulator is built as part of the build process.
4097  For more information visit Daniel's web site at:
4098 \begin_inset LatexCommand \url{http://mazsola.iit.uni-miskolc.hu/~drdani/embedded/s51}
4099
4100 \end_inset
4101
4102 .
4103  It currently supports the core mcs51, the Dallas DS80C390 and the Phillips
4104  XA51 family.
4105 \layout Subsection
4106
4107 sdcdb - Source Level Debugger
4108 \layout Standard
4109
4110 Sdcdb
4111 \begin_inset LatexCommand \index{sdcdb (debugger)}
4112
4113 \end_inset
4114
4115  is the companion source level debugger.
4116  More about sdcdb in section
4117 \begin_inset LatexCommand \ref{cha:Debugging-with-SDCDB}
4118
4119 \end_inset
4120
4121 .
4122  The current version of the debugger uses Daniel's Simulator S51
4123 \begin_inset LatexCommand \index{s51}
4124
4125 \end_inset
4126
4127 , but can be easily changed to use other simulators.
4128
4129 \layout Chapter
4130
4131 Using SDCC
4132 \layout Section
4133
4134 Compiling
4135 \layout Subsection
4136
4137 Single Source File Projects
4138 \layout Standard
4139
4140 For single source file 8051 projects the process is very simple.
4141  Compile your programs with the following command
4142 \family sans
4143 \series bold
4144 "sdcc sourcefile.c".
4145
4146 \family default
4147 \series default
4148  This will compile, assemble and link your source file.
4149  Output files are as follows:
4150 \layout Itemize
4151
4152 sourcefile.asm
4153 \begin_inset LatexCommand \index{<file>.asm}
4154
4155 \end_inset
4156
4157  - Assembler source
4158 \begin_inset LatexCommand \index{Assembler source}
4159
4160 \end_inset
4161
4162  file created by the compiler
4163 \layout Itemize
4164
4165 sourcefile.lst
4166 \begin_inset LatexCommand \index{<file>.lst}
4167
4168 \end_inset
4169
4170  - Assembler listing
4171 \begin_inset LatexCommand \index{Assembler listing}
4172
4173 \end_inset
4174
4175  file created by the Assembler
4176 \layout Itemize
4177
4178 sourcefile.rst
4179 \begin_inset LatexCommand \index{<file>.rst}
4180
4181 \end_inset
4182
4183  - Assembler listing
4184 \begin_inset LatexCommand \index{Assembler listing}
4185
4186 \end_inset
4187
4188  file updated with linkedit information, created by linkage editor
4189 \layout Itemize
4190
4191 sourcefile.sym
4192 \begin_inset LatexCommand \index{<file>.sym}
4193
4194 \end_inset
4195
4196  - symbol listing
4197 \begin_inset LatexCommand \index{Symbol listing}
4198
4199 \end_inset
4200
4201  for the sourcefile, created by the assembler
4202 \layout Itemize
4203
4204 sourcefile.rel
4205 \begin_inset LatexCommand \index{<file>.rel}
4206
4207 \end_inset
4208
4209  or sourcefile.o
4210 \begin_inset LatexCommand \index{<file>.o}
4211
4212 \end_inset
4213
4214  - Object file
4215 \begin_inset LatexCommand \index{Object file}
4216
4217 \end_inset
4218
4219  created by the assembler, input to Linkage editor
4220 \layout Itemize
4221
4222 sourcefile.map
4223 \begin_inset LatexCommand \index{<file>.map}
4224
4225 \end_inset
4226
4227  - The memory map
4228 \begin_inset LatexCommand \index{Memory map}
4229
4230 \end_inset
4231
4232  for the load module, created by the Linker
4233 \layout Itemize
4234
4235 sourcefile.mem
4236 \begin_inset LatexCommand \index{<file>.mem}
4237
4238 \end_inset
4239
4240  - A file with a summary of the memory usage
4241 \layout Itemize
4242
4243 sourcefile.ihx
4244 \begin_inset LatexCommand \index{<file>.ihx}
4245
4246 \end_inset
4247
4248  - The load module in Intel hex format
4249 \begin_inset LatexCommand \index{Intel hex format}
4250
4251 \end_inset
4252
4253  (you can select the Motorola S19 format
4254 \begin_inset LatexCommand \index{Motorola S19 format}
4255
4256 \end_inset
4257
4258  with -
4259 \begin_inset ERT
4260 status Collapsed
4261
4262 \layout Standard
4263
4264 \backslash
4265 /
4266 \end_inset
4267
4268 -out-fmt-s19
4269 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
4270
4271 \end_inset
4272
4273 .
4274  If you need another format you might want to use
4275 \family sans
4276 \shape italic
4277 objdump
4278 \family default
4279 \shape default
4280
4281 \begin_inset LatexCommand \index{objdump (tool)}
4282
4283 \end_inset
4284
4285  or
4286 \family sans
4287 \shape italic
4288  srecord
4289 \family default
4290 \shape default
4291
4292 \begin_inset LatexCommand \index{srecord (tool)}
4293
4294 \end_inset
4295
4296 ).
4297  Both formats are documented in the documentation of srecord
4298 \begin_inset LatexCommand \index{srecord (tool)}
4299
4300 \end_inset
4301
4302
4303 \layout Itemize
4304
4305 sourcefile.adb
4306 \begin_inset LatexCommand \index{<file>.adb}
4307
4308 \end_inset
4309
4310  - An intermediate file containing debug information needed to create the
4311  .cdb file (with -
4312 \begin_inset ERT
4313 status Open
4314
4315 \layout Standard
4316
4317 \backslash
4318 /
4319 \end_inset
4320
4321 -debug
4322 \begin_inset LatexCommand \index{-\/-debug}
4323
4324 \end_inset
4325
4326 )
4327 \layout Itemize
4328
4329 sourcefile.cdb
4330 \begin_inset LatexCommand \index{<file>.cdb}
4331
4332 \end_inset
4333
4334  - An optional file (with -
4335 \begin_inset ERT
4336 status Collapsed
4337
4338 \layout Standard
4339
4340 \backslash
4341 /
4342 \end_inset
4343
4344 -debug) containing debug information.
4345  The format is documented in cdbfileformat.pdf.
4346 \layout Itemize
4347
4348 sourcefile.
4349  - (no extension)
4350 \begin_inset LatexCommand \index{<file> (no extension)}
4351
4352 \end_inset
4353
4354  An optional AOMF or AOMF51
4355 \begin_inset LatexCommand \index{AOMF, AOMF51}
4356
4357 \end_inset
4358
4359  file containing debug information (generated with option -
4360 \begin_inset ERT
4361 status Collapsed
4362
4363 \layout Standard
4364
4365 \backslash
4366 /
4367 \end_inset
4368
4369 -debug).
4370  The (Intel)
4371 \emph on
4372  a
4373 \emph default
4374 bsolute
4375 \emph on
4376 o
4377 \emph default
4378 bject
4379 \emph on
4380 m
4381 \emph default
4382 odule
4383 \emph on
4384 f
4385 \emph default
4386 ormat is commonly used by third party tools (debuggers
4387 \begin_inset LatexCommand \index{Debugger}
4388
4389 \end_inset
4390
4391 , simulators, emulators)
4392 \layout Itemize
4393
4394 sourcefile.dump*
4395 \begin_inset LatexCommand \index{<file>.dump*}
4396
4397 \end_inset
4398
4399  - Dump file to debug the compiler it self (generated with option -
4400 \begin_inset ERT
4401 status Collapsed
4402
4403 \layout Standard
4404
4405 \backslash
4406 /
4407 \end_inset
4408
4409 -dumpall) (see section
4410 \begin_inset LatexCommand \ref{sub:Intermediate-Dump-Options}
4411
4412 \end_inset
4413
4414 \SpecialChar ~
4415  and section
4416 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
4417
4418 \end_inset
4419
4420 \SpecialChar ~
4421
4422 \begin_inset Quotes sld
4423 \end_inset
4424
4425 Anatomy of the compiler
4426 \begin_inset Quotes srd
4427 \end_inset
4428
4429 ).
4430 \layout Subsection
4431
4432 Projects with Multiple Source Files
4433 \layout Standard
4434
4435 SDCC can compile only ONE file at a time.
4436  Let us for example assume that you have a project containing the following
4437  files:
4438 \newline
4439
4440 \newline
4441 foo1.c (contains some functions)
4442 \newline
4443 foo2.c (contains some more functions)
4444 \newline
4445 foomain.c (contains more functions and the function main)
4446 \newline
4447
4448 \size footnotesize
4449
4450 \newline
4451
4452 \size default
4453 The first two files will need to be compiled separately with the commands:
4454 \size footnotesize
4455
4456 \size default
4457
4458 \newline
4459
4460 \newline
4461
4462 \family sans
4463 \series bold
4464 sdcc\SpecialChar ~
4465 -c\SpecialChar ~
4466 foo1.c
4467 \family default
4468 \series default
4469 \size footnotesize
4470
4471 \newline
4472
4473 \family sans
4474 \series bold
4475 \size default
4476 sdcc\SpecialChar ~
4477 -c\SpecialChar ~
4478 foo2.c
4479 \family default
4480 \series default
4481
4482 \newline
4483
4484 \newline
4485 Then compile the source file containing the
4486 \emph on
4487 main()
4488 \emph default
4489  function and link
4490 \begin_inset LatexCommand \index{Linker}
4491
4492 \end_inset
4493
4494  the files together with the following command:
4495 \newline
4496
4497 \newline
4498
4499 \family sans
4500 \series bold
4501 sdcc\SpecialChar ~
4502 foomain.c\SpecialChar ~
4503 foo1.rel\SpecialChar ~
4504 foo2.rel
4505 \family default
4506 \series default
4507
4508 \begin_inset LatexCommand \index{<file>.rel}
4509
4510 \end_inset
4511
4512
4513 \newline
4514
4515 \newline
4516 Alternatively,
4517 \emph on
4518 foomain.c
4519 \emph default
4520 can be separately compiled as well:
4521 \family sans
4522 \series bold
4523
4524 \newline
4525
4526 \newline
4527 sdcc\SpecialChar ~
4528 -c\SpecialChar ~
4529 foomain.c
4530 \newline
4531 sdcc foomain.rel foo1.rel foo2.rel
4532 \newline
4533
4534 \newline
4535
4536 \family default
4537 \series default
4538 The file containing the
4539 \emph on
4540 main()
4541 \emph default
4542  function
4543 \emph on
4544
4545 \emph default
4546 \noun on
4547 must
4548 \noun default
4549  be the
4550 \noun on
4551 first
4552 \noun default
4553  file specified in the command line, since the linkage editor processes
4554  file in the order they are presented to it.
4555  The linker is invoked from SDCC using a script file with extension .lnk
4556 \begin_inset LatexCommand \index{<file>.lnk}
4557
4558 \end_inset
4559
4560 .
4561  You can view this file to troubleshoot linking problems such as those arising
4562  from missing libraries.
4563 \layout Subsection
4564
4565 Projects with Additional Libraries
4566 \begin_inset LatexCommand \index{Libraries}
4567
4568 \end_inset
4569
4570
4571 \layout Standard
4572
4573 Some reusable routines may be compiled into a library, see the documentation
4574  for the assembler and linkage editor (which are in <installdir>/share/sdcc/doc)
4575  for how to create a
4576 \emph on
4577 .lib
4578 \begin_inset LatexCommand \index{<file>.lib}
4579
4580 \end_inset
4581
4582
4583 \emph default
4584  library file.
4585  Libraries created in this manner can be included in the command line.
4586  Make sure you include the -L <library-path> option to tell the linker where
4587  to look for these files if they are not in the current directory.
4588  Here is an example, assuming you have the source file
4589 \emph on
4590 foomain.c
4591 \emph default
4592  and a library
4593 \emph on
4594  foolib.lib
4595 \emph default
4596  in the directory
4597 \emph on
4598 mylib
4599 \emph default
4600  (if that is not the same as your current project):
4601 \newline
4602
4603 \newline
4604
4605 \family sans
4606 \series bold
4607 sdcc foomain.c foolib.lib -L mylib
4608 \newline
4609
4610 \newline
4611
4612 \family default
4613 \series default
4614 Note here that
4615 \emph on
4616  mylib
4617 \emph default
4618  must be an absolute path name.
4619 \newline
4620
4621 \newline
4622 The most efficient way to use libraries is to keep separate modules in separate
4623  source files.
4624  The lib file now should name all the modules.rel
4625 \begin_inset LatexCommand \index{<file>.rel}
4626
4627 \end_inset
4628
4629  files.
4630  For an example see the standard library file
4631 \emph on
4632 libsdcc.lib
4633 \emph default
4634  in the directory <installdir>/share/lib/small.
4635 \layout Subsection
4636
4637 Using sdcclib to Create and Manage Libraries
4638 \begin_inset LatexCommand \index{sdcclib}
4639
4640 \end_inset
4641
4642
4643 \layout Standard
4644
4645 Alternatively, instead of having a .rel file for each entry on the library
4646  file as described in the preceding section, sdcclib can be used to embed
4647  all the modules belonging to such library in the library file itself.
4648  This results in a larger library file, but it greatly reduces the number
4649  of disk files accessed by the linker.
4650   Additionally, the packed library file contains an index of all include
4651  modules and symbols that significantly speeds up the linking process.
4652  To display a list of options supported by sdcclib type:
4653 \newline
4654
4655 \layout Standard
4656
4657
4658 \family sans
4659 \series bold
4660 sdcclib -?
4661 \begin_inset LatexCommand \index{sdcclib}
4662
4663 \end_inset
4664
4665
4666 \newline
4667
4668 \newline
4669
4670 \family default
4671 \series default
4672 To create a new library file, start by compiling all the required modules.
4673  For example:
4674 \newline
4675
4676 \layout Standard
4677
4678
4679 \family sans
4680 \series bold
4681 sdcc -c _divsint.c
4682 \layout Standard
4683
4684
4685 \family sans
4686 \series bold
4687 sdcc -c _divuint.c
4688 \layout Standard
4689
4690
4691 \family sans
4692 \series bold
4693 sdcc -c _modsint.c
4694 \layout Standard
4695
4696
4697 \family sans
4698 \series bold
4699 sdcc -c _moduint.c
4700 \layout Standard
4701
4702
4703 \family sans
4704 \series bold
4705 sdcc -c _mulint.c
4706 \newline
4707
4708 \layout Standard
4709
4710 This will create files _divsint.rel, _divuint.rel, _modsint.rel, _moduint.rel,
4711  and _mulint.rel.
4712  The next step is to add the .rel files to the library file:
4713 \newline
4714
4715 \layout Standard
4716
4717
4718 \family sans
4719 \series bold
4720 sdcclib libint.lib _divsint.rel
4721 \family default
4722
4723 \begin_inset LatexCommand \index{sdcclib}
4724
4725 \end_inset
4726
4727
4728 \layout Standard
4729
4730
4731 \family sans
4732 \series bold
4733 sdcclib libint.lib _divuint.rel
4734 \layout Standard
4735
4736
4737 \family sans
4738 \series bold
4739 sdcclib libint.lib _modsint.rel
4740 \layout Standard
4741
4742
4743 \family sans
4744 \series bold
4745 sdcclib libint.lib _moduint.rel
4746 \layout Standard
4747
4748
4749 \family sans
4750 \series bold
4751 sdcclib libint.lib _mulint.rel
4752 \series default
4753
4754 \newline
4755
4756 \layout Standard
4757
4758 If the file already exists in the library, it will be replaced.
4759  To see what modules and symbols are included in the library, options -s
4760  and -m are available.
4761  For example:
4762 \newline
4763
4764 \newline
4765
4766 \family sans
4767 \series bold
4768 sdcclib -s libint.lib
4769 \family default
4770
4771 \begin_inset LatexCommand \index{sdcclib}
4772
4773 \end_inset
4774
4775
4776 \newline
4777
4778 \family typewriter
4779 \series default
4780 _divsint.rel:
4781 \layout Standard
4782
4783
4784 \family typewriter
4785 __divsint_a_1_1
4786 \layout Standard
4787
4788
4789 \family typewriter
4790 __divsint_PARM_2
4791 \layout Standard
4792
4793
4794 \family typewriter
4795 __divsint
4796 \newline
4797 _divuint.rel:
4798 \layout Standard
4799
4800
4801 \family typewriter
4802 __divuint_a_1_1
4803 \layout Standard
4804
4805
4806 \family typewriter
4807 __divuint_PARM_2
4808 \layout Standard
4809
4810
4811 \family typewriter
4812 __divuint_reste_1_1
4813 \layout Standard
4814
4815
4816 \family typewriter
4817 __divuint_count_1_1
4818 \layout Standard
4819
4820
4821 \family typewriter
4822 __divuint
4823 \newline
4824 _modsint.rel:
4825 \layout Standard
4826
4827
4828 \family typewriter
4829 __modsint_a_1_1
4830 \layout Standard
4831
4832
4833 \family typewriter
4834 __modsint_PARM_2
4835 \layout Standard
4836
4837
4838 \family typewriter
4839 __modsint
4840 \newline
4841 _moduint.rel:
4842 \layout Standard
4843
4844
4845 \family typewriter
4846 __moduint_a_1_1
4847 \layout Standard
4848
4849
4850 \family typewriter
4851 __moduint_PARM_2
4852 \layout Standard
4853
4854
4855 \family typewriter
4856 __moduint_count_1_1
4857 \layout Standard
4858
4859
4860 \family typewriter
4861 __moduint
4862 \newline
4863 _mulint.rel:
4864 \layout Standard
4865
4866
4867 \family typewriter
4868 __mulint_PARM_2
4869 \layout Standard
4870
4871
4872 \family typewriter
4873 __mulint
4874 \family default
4875 \series bold
4876
4877 \newline
4878
4879 \layout Standard
4880
4881 If the source files are compiled using -
4882 \begin_inset ERT
4883 status Open
4884
4885 \layout Standard
4886
4887 \backslash
4888 /
4889 \end_inset
4890
4891 -debug
4892 \begin_inset LatexCommand \index{-\/-debug}
4893
4894 \end_inset
4895
4896 , the corresponding debug information file .adb will be include in the library
4897  file as well.
4898  The library files created with sdcclib are plain text files, so they can
4899  be viewed with a text editor.
4900  It is not recomended to modify a library file created with sdcclib using
4901  a text editor, as there are file indexes numbers located accross the file
4902  used by the linker to quickly locate the required module to link.
4903  Once a .rel file (as well as a .adb file) is added to a library using sdcclib,
4904  it can be safely deleted, since all the information required for linking
4905  is embedded in the library file itself.
4906  Library files created using sdcclib are used as described in the preceding
4907  sections.
4908 \layout Section
4909
4910 Command Line Options
4911 \begin_inset LatexCommand \index{Command Line Options}
4912
4913 \end_inset
4914
4915
4916 \layout Subsection
4917
4918 Processor Selection Options
4919 \begin_inset LatexCommand \index{Options processor selection}
4920
4921 \end_inset
4922
4923
4924 \begin_inset LatexCommand \index{Processor selection options}
4925
4926 \end_inset
4927
4928
4929 \layout List
4930 \labelwidthstring 00.00.0000
4931
4932
4933 \series bold
4934 -mmcs51
4935 \begin_inset LatexCommand \index{-mmcs51}
4936
4937 \end_inset
4938
4939
4940 \series default
4941  Generate code for the Intel MCS51
4942 \begin_inset LatexCommand \index{MCS51}
4943
4944 \end_inset
4945
4946  family of processors.
4947  This is the default processor target.
4948 \layout List
4949 \labelwidthstring 00.00.0000
4950
4951
4952 \series bold
4953 -mds390
4954 \begin_inset LatexCommand \index{-mds390}
4955
4956 \end_inset
4957
4958
4959 \series default
4960  Generate code for the Dallas DS80C390
4961 \begin_inset LatexCommand \index{DS80C390}
4962
4963 \end_inset
4964
4965  processor.
4966 \layout List
4967 \labelwidthstring 00.00.0000
4968
4969
4970 \series bold
4971 -mds400
4972 \begin_inset LatexCommand \index{-mds400}
4973
4974 \end_inset
4975
4976
4977 \series default
4978  Generate code for the Dallas DS80C400
4979 \begin_inset LatexCommand \index{DS80C400}
4980
4981 \end_inset
4982
4983  processor.
4984 \layout List
4985 \labelwidthstring 00.00.0000
4986
4987
4988 \series bold
4989 -mhc08
4990 \begin_inset LatexCommand \index{-mhc08}
4991
4992 \end_inset
4993
4994
4995 \series default
4996  Generate code for the Motorola HC08
4997 \begin_inset LatexCommand \index{HC08}
4998
4999 \end_inset
5000
5001  family of processors (added Oct 2003).
5002 \layout List
5003 \labelwidthstring 00.00.0000
5004
5005
5006 \series bold
5007 -mz80
5008 \begin_inset LatexCommand \index{-mz80}
5009
5010 \end_inset
5011
5012
5013 \series default
5014  Generate code for the Zilog Z80
5015 \begin_inset LatexCommand \index{Z80}
5016
5017 \end_inset
5018
5019  family of processors.
5020 \layout List
5021 \labelwidthstring 00.00.0000
5022
5023
5024 \series bold
5025 -mgbz80
5026 \begin_inset LatexCommand \index{-mgbz80}
5027
5028 \end_inset
5029
5030
5031 \series default
5032  Generate code for the GameBoy Z80
5033 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
5034
5035 \end_inset
5036
5037  processor (Not actively maintained).
5038 \layout List
5039 \labelwidthstring 00.00.0000
5040
5041
5042 \series bold
5043 -mavr
5044 \begin_inset LatexCommand \index{-mavr}
5045
5046 \end_inset
5047
5048
5049 \series default
5050  Generate code for the Atmel AVR
5051 \begin_inset LatexCommand \index{AVR}
5052
5053 \end_inset
5054
5055  processor (In development, not complete).
5056  AVR users should probably have a look at avr-gcc
5057 \begin_inset LatexCommand \url{ http://savannah.nongnu.org/download/avr-libc/snapshots/}
5058
5059 \end_inset
5060
5061  or winavr
5062 \begin_inset LatexCommand \url{http://winavr.sourceforge.net}
5063
5064 \end_inset
5065
5066 .
5067 \layout Comment
5068
5069 I think it is fair to direct users there for now.
5070  Open source is also about avoiding unnecessary work .
5071  But I didn't find the 'official' link.
5072 \layout List
5073 \labelwidthstring 00.00.0000
5074
5075
5076 \series bold
5077 -mpic14
5078 \begin_inset LatexCommand \index{-mpic14}
5079
5080 \end_inset
5081
5082
5083 \series default
5084  Generate code for the Microchip PIC 14
5085 \begin_inset LatexCommand \index{PIC14}
5086
5087 \end_inset
5088
5089 -bit processors (p16f84 and variants.
5090  In development, not complete).
5091 \layout Comment
5092
5093 p16f627 p16f628 p16f84 p16f873 p16f877?
5094 \layout List
5095 \labelwidthstring 00.00.0000
5096
5097
5098 \series bold
5099 -mpic16
5100 \begin_inset LatexCommand \index{-mpic16}
5101
5102 \end_inset
5103
5104
5105 \series default
5106  Generate code for the Microchip PIC 16
5107 \begin_inset LatexCommand \index{PIC16}
5108
5109 \end_inset
5110
5111 -bit processors (p18f452 and variants.
5112  In development, not complete).
5113 \layout List
5114 \labelwidthstring 00.00.0000
5115
5116
5117 \series bold
5118 -mtlcs900h
5119 \series default
5120  Generate code for the Toshiba TLCS-900H
5121 \begin_inset LatexCommand \index{TLCS-900H}
5122
5123 \end_inset
5124
5125  processor (Not maintained, not complete).
5126 \layout List
5127 \labelwidthstring 00.00.0000
5128
5129
5130 \series bold
5131 -mxa51
5132 \begin_inset LatexCommand \index{-mxa51}
5133
5134 \end_inset
5135
5136
5137 \series default
5138  Generate code for the Phillips XA51
5139 \begin_inset LatexCommand \index{XA51}
5140
5141 \end_inset
5142
5143  processor (Not maintained, not complete).
5144 \layout Subsection
5145
5146 Preprocessor Options
5147 \begin_inset LatexCommand \index{Options preprocessor}
5148
5149 \end_inset
5150
5151
5152 \begin_inset LatexCommand \index{Preprocessor options}
5153
5154 \end_inset
5155
5156
5157 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5158
5159 \end_inset
5160
5161
5162 \layout List
5163 \labelwidthstring 00.00.0000
5164
5165
5166 \series bold
5167 -I<path>
5168 \begin_inset LatexCommand \index{-I<path>}
5169
5170 \end_inset
5171
5172
5173 \series default
5174  The additional location where the pre processor will look for <..h> or
5175 \begin_inset Quotes eld
5176 \end_inset
5177
5178 ..h
5179 \begin_inset Quotes erd
5180 \end_inset
5181
5182  files.
5183 \layout List
5184 \labelwidthstring 00.00.0000
5185
5186
5187 \series bold
5188 -D<macro[=value]>
5189 \begin_inset LatexCommand \index{-D<macro[=value]>}
5190
5191 \end_inset
5192
5193
5194 \series default
5195  Command line definition of macros.
5196  Passed to the preprocessor.
5197 \layout List
5198 \labelwidthstring 00.00.0000
5199
5200
5201 \series bold
5202 -M
5203 \begin_inset LatexCommand \index{-M}
5204
5205 \end_inset
5206
5207
5208 \series default
5209  Tell the preprocessor to output a rule suitable for make describing the
5210  dependencies of each object file.
5211  For each source file, the preprocessor outputs one make-rule whose target
5212  is the object file name for that source file and whose dependencies are
5213  all the files `#include'd in it.
5214  This rule may be a single line or may be continued with `
5215 \backslash
5216 '-newline if it is long.
5217  The list of rules is printed on standard output instead of the preprocessed
5218  C program.
5219  `-M' implies `-E
5220 \begin_inset LatexCommand \index{-E}
5221
5222 \end_inset
5223
5224 '.
5225 \layout List
5226 \labelwidthstring 00.00.0000
5227
5228
5229 \series bold
5230 -C
5231 \begin_inset LatexCommand \index{-C}
5232
5233 \end_inset
5234
5235
5236 \series default
5237  Tell the preprocessor not to discard comments.
5238  Used with the `-E' option.
5239 \layout List
5240 \labelwidthstring 00.00.0000
5241
5242
5243 \series bold
5244 -MM
5245 \begin_inset LatexCommand \index{-MM}
5246
5247 \end_inset
5248
5249
5250 \size large
5251 \bar under
5252
5253 \series default
5254 \size default
5255 \bar default
5256 Like `-M' but the output mentions only the user header files included with
5257  `#include
5258 \begin_inset Quotes eld
5259 \end_inset
5260
5261 file"'.
5262  System header files included with `#include <file>' are omitted.
5263 \layout List
5264 \labelwidthstring 00.00.0000
5265
5266
5267 \series bold
5268 -Aquestion(answer)
5269 \begin_inset LatexCommand \index{-Aquestion(answer)}
5270
5271 \end_inset
5272
5273
5274 \series default
5275  Assert the answer answer for question, in case it is tested with a preprocessor
5276  conditional such as `#if #question(answer)'.
5277  `-A-' disables the standard assertions that normally describe the target
5278  machine.
5279 \layout List
5280 \labelwidthstring 00.00.0000
5281
5282
5283 \series bold
5284 -Umacro
5285 \begin_inset LatexCommand \index{-Umacro}
5286
5287 \end_inset
5288
5289
5290 \series default
5291  Undefine macro macro.
5292  `-U' options are evaluated after all `-D' options, but before any `-include'
5293  and `-imacros' options.
5294 \layout List
5295 \labelwidthstring 00.00.0000
5296
5297
5298 \series bold
5299 -dM
5300 \begin_inset LatexCommand \index{-dM}
5301
5302 \end_inset
5303
5304
5305 \series default
5306  Tell the preprocessor to output only a list of the macro definitions that
5307  are in effect at the end of preprocessing.
5308  Used with the `-E' option.
5309 \layout List
5310 \labelwidthstring 00.00.0000
5311
5312
5313 \series bold
5314 -dD
5315 \begin_inset LatexCommand \index{-dD}
5316
5317 \end_inset
5318
5319
5320 \series default
5321  Tell the preprocessor to pass all macro definitions into the output, in
5322  their proper sequence in the rest of the output.
5323 \layout List
5324 \labelwidthstring 00.00.0000
5325
5326
5327 \series bold
5328 -dN
5329 \begin_inset LatexCommand \index{-dN}
5330
5331 \end_inset
5332
5333
5334 \size large
5335 \bar under
5336
5337 \series default
5338 \size default
5339 \bar default
5340 Like `-dD' except that the macro arguments and contents are omitted.
5341  Only `#define name' is included in the output.
5342 \layout List
5343 \labelwidthstring 00.00.0000
5344
5345
5346 \series bold
5347 -Wp\SpecialChar ~
5348 preprocessorOption[,preprocessorOption]
5349 \series default
5350
5351 \begin_inset LatexCommand \index{-Wp preprocessorOption[,preprocessorOption]}
5352
5353 \end_inset
5354
5355 ...
5356  Pass the preprocessorOption to the preprocessor
5357 \family typewriter
5358 sdcpp
5359 \family default
5360
5361 \begin_inset LatexCommand \index{sdcpp (preprocessor)}
5362
5363 \end_inset
5364
5365 .
5366  SDCC uses an adapted version of the preprocessor cpp of the GNU Compiler
5367  Collection (gcc), if you need more dedicated options please refer to the
5368  documentation at
5369 \begin_inset LatexCommand \htmlurl{http://www.gnu.org/software/gcc/onlinedocs/}
5370
5371 \end_inset
5372
5373 .
5374 \layout Subsection
5375
5376 Linker Options
5377 \begin_inset LatexCommand \index{Options linker}
5378
5379 \end_inset
5380
5381
5382 \begin_inset LatexCommand \index{Linker options}
5383
5384 \end_inset
5385
5386
5387 \layout List
5388 \labelwidthstring 00.00.0000
5389
5390
5391 \series bold
5392 -L\SpecialChar ~
5393 -
5394 \series default
5395
5396 \begin_inset ERT
5397 status Collapsed
5398
5399 \layout Standard
5400
5401 \backslash
5402 /
5403 \end_inset
5404
5405
5406 \series bold
5407 -lib-path
5408 \begin_inset LatexCommand \index{-\/-lib-path <path>}
5409
5410 \end_inset
5411
5412
5413 \begin_inset LatexCommand \index{-L -\/-lib-path}
5414
5415 \end_inset
5416
5417
5418 \series default
5419 \SpecialChar ~
5420 <absolute path to additional libraries> This option is passed to the linkage
5421  editor's additional libraries
5422 \begin_inset LatexCommand \index{Libraries}
5423
5424 \end_inset
5425
5426  search path.
5427  The path name must be absolute.
5428  Additional library files may be specified in the command line.
5429  See section Compiling programs for more details.
5430 \layout List
5431 \labelwidthstring 00.00.0000
5432
5433
5434 \series bold
5435 -
5436 \begin_inset ERT
5437 status Collapsed
5438
5439 \layout Standard
5440
5441 \backslash
5442 /
5443 \end_inset
5444
5445 -xram-loc
5446 \series default
5447
5448 \begin_inset LatexCommand \index{-\/-xram-loc <Value>}
5449
5450 \end_inset
5451
5452 \SpecialChar ~
5453 <Value> The start location of the external ram
5454 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
5455
5456 \end_inset
5457
5458 , default value is 0.
5459  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5460 \begin_inset ERT
5461 status Collapsed
5462
5463 \layout Standard
5464
5465 \backslash
5466 /
5467 \end_inset
5468
5469 -xram-loc 0x8000 or -
5470 \begin_inset ERT
5471 status Collapsed
5472
5473 \layout Standard
5474
5475 \backslash
5476 /
5477 \end_inset
5478
5479 -xram-loc 32768.
5480 \layout List
5481 \labelwidthstring 00.00.0000
5482
5483
5484 \series bold
5485 -
5486 \begin_inset ERT
5487 status Collapsed
5488
5489 \layout Standard
5490
5491 \backslash
5492 /
5493 \end_inset
5494
5495 -code-loc
5496 \series default
5497
5498 \begin_inset LatexCommand \index{-\/-code-loc <Value>}
5499
5500 \end_inset
5501
5502 \SpecialChar ~
5503 <Value> The start location of the code
5504 \begin_inset LatexCommand \index{code}
5505
5506 \end_inset
5507
5508  segment, default value 0.
5509  Note when this option is used the interrupt vector table is also relocated
5510  to the given address.
5511  The value entered can be in Hexadecimal or Decimal format, e.g.: -
5512 \begin_inset ERT
5513 status Collapsed
5514
5515 \layout Standard
5516
5517 \backslash
5518 /
5519 \end_inset
5520
5521 -code-loc 0x8000 or -
5522 \begin_inset ERT
5523 status Collapsed
5524
5525 \layout Standard
5526
5527 \backslash
5528 /
5529 \end_inset
5530
5531 -code-loc 32768.
5532 \layout List
5533 \labelwidthstring 00.00.0000
5534
5535
5536 \series bold
5537 -
5538 \begin_inset ERT
5539 status Collapsed
5540
5541 \layout Standard
5542
5543 \backslash
5544 /
5545 \end_inset
5546
5547 -stack-loc
5548 \series default
5549
5550 \begin_inset LatexCommand \index{-\/-stack-loc <Value>}
5551
5552 \end_inset
5553
5554 \SpecialChar ~
5555 <Value> By default the stack
5556 \begin_inset LatexCommand \index{stack}
5557
5558 \end_inset
5559
5560  is placed after the data segment.
5561  Using this option the stack can be placed anywhere in the internal memory
5562  space of the 8051.
5563  The value entered can be in Hexadecimal or Decimal format, e.g.
5564  -
5565 \begin_inset ERT
5566 status Collapsed
5567
5568 \layout Standard
5569
5570 \backslash
5571 /
5572 \end_inset
5573
5574 -stack-loc 0x20 or -
5575 \begin_inset ERT
5576 status Collapsed
5577
5578 \layout Standard
5579
5580 \backslash
5581 /
5582 \end_inset
5583
5584 -stack-loc 32.
5585  Since the sp register is incremented before a push or call, the initial
5586  sp will be set to one byte prior the provided value.
5587  The provided value should not overlap any other memory areas such as used
5588  register banks or the data segment and with enough space for the current
5589  application.
5590 \layout List
5591 \labelwidthstring 00.00.0000
5592
5593
5594 \series bold
5595 -
5596 \begin_inset ERT
5597 status Collapsed
5598
5599 \layout Standard
5600
5601 \backslash
5602 /
5603 \end_inset
5604
5605 -data-loc
5606 \series default
5607
5608 \begin_inset LatexCommand \index{-\/-data-loc <Value>}
5609
5610 \end_inset
5611
5612 \SpecialChar ~
5613 <Value> The start location of the internal ram data
5614 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
5615
5616 \end_inset
5617
5618  segment.
5619  The value entered can be in Hexadecimal or Decimal format, eg.
5620  -
5621 \begin_inset ERT
5622 status Collapsed
5623
5624 \layout Standard
5625
5626 \backslash
5627 /
5628 \end_inset
5629
5630 -data-loc 0x20 or -
5631 \begin_inset ERT
5632 status Collapsed
5633
5634 \layout Standard
5635
5636 \backslash
5637 /
5638 \end_inset
5639
5640 -data-loc 32.
5641  (By default, the start location of the internal ram data segment  is set
5642  as low as possible in memory, taking into account the used register banks
5643  and the bit segment at address 0x20.
5644  For example if register banks 0 and 1 are used without bit variables, the
5645  data segment will be set, if -
5646 \begin_inset ERT
5647 status Collapsed
5648
5649 \layout Standard
5650
5651 \backslash
5652 /
5653 \end_inset
5654
5655 -data-loc is not used, to location 0x10.)
5656 \layout List
5657 \labelwidthstring 00.00.0000
5658
5659
5660 \series bold
5661 -
5662 \begin_inset ERT
5663 status Collapsed
5664
5665 \layout Standard
5666
5667 \backslash
5668 /
5669 \end_inset
5670
5671 -idata-loc
5672 \series default
5673
5674 \begin_inset LatexCommand \index{-\/-idata-loc <Value>}
5675
5676 \end_inset
5677
5678 \SpecialChar ~
5679 <Value> The start location of the indirectly addressable internal ram
5680 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
5681
5682 \end_inset
5683
5684  of the 8051, default value is 0x80.
5685  The value entered can be in Hexadecimal or Decimal format, eg.
5686  -
5687 \begin_inset ERT
5688 status Collapsed
5689
5690 \layout Standard
5691
5692 \backslash
5693 /
5694 \end_inset
5695
5696 -idata-loc 0x88 or -
5697 \begin_inset ERT
5698 status Collapsed
5699
5700 \layout Standard
5701
5702 \backslash
5703 /
5704 \end_inset
5705
5706 -idata-loc 136.
5707 \layout List
5708 \labelwidthstring 00.00.0000
5709
5710
5711 \series bold
5712 -
5713 \begin_inset ERT
5714 status Collapsed
5715
5716 \layout Standard
5717
5718 \backslash
5719 /
5720 \end_inset
5721
5722 -bit-loc
5723 \series default
5724 \SpecialChar ~
5725 <Value> The start location of the bit
5726 \begin_inset LatexCommand \index{bit}
5727
5728 \end_inset
5729
5730  addressable internal ram of the 8051.
5731  This is
5732 \emph on
5733 not
5734 \emph default
5735  implemented yet.
5736  Instead an option can be passed directly to the linker: -Wl\SpecialChar ~
5737 -bBSEG=<Value>.
5738 \layout List
5739 \labelwidthstring 00.00.0000
5740
5741
5742 \series bold
5743 -
5744 \begin_inset ERT
5745 status Collapsed
5746
5747 \layout Standard
5748
5749 \backslash
5750 /
5751 \end_inset
5752
5753 -out-fmt-ihx
5754 \begin_inset LatexCommand \index{-\/-out-fmt-ihx}
5755
5756 \end_inset
5757
5758
5759 \bar under
5760
5761 \series default
5762 \bar default
5763 The linker output (final object code) is in Intel Hex format.
5764 \begin_inset LatexCommand \index{Intel hex format}
5765
5766 \end_inset
5767
5768  This is the default option.
5769  The format itself is documented in the documentation of srecord
5770 \begin_inset LatexCommand \index{srecord (tool)}
5771
5772 \end_inset
5773
5774 .
5775 \layout List
5776 \labelwidthstring 00.00.0000
5777
5778
5779 \series bold
5780 -
5781 \begin_inset ERT
5782 status Collapsed
5783
5784 \layout Standard
5785
5786 \backslash
5787 /
5788 \end_inset
5789
5790 -out-fmt-s19
5791 \begin_inset LatexCommand \index{-\/-out-fmt-s19}
5792
5793 \end_inset
5794
5795
5796 \bar under
5797
5798 \series default
5799 \bar default
5800 The linker output (final object code) is in Motorola S19 format
5801 \begin_inset LatexCommand \index{Motorola S19 format}
5802
5803 \end_inset
5804
5805 .
5806  The format itself is documented in the documentation of srecord.
5807 \layout List
5808 \labelwidthstring 00.00.0000
5809
5810
5811 \series bold
5812 -Wl\SpecialChar ~
5813 linkOption[,linkOption]
5814 \series default
5815
5816 \begin_inset LatexCommand \index{-Wl linkOption[,linkOption]}
5817
5818 \end_inset
5819
5820 ...
5821  Pass the linkOption to the linker.
5822  See file sdcc/as/doc/asxhtm.html for more on linker options.
5823 \layout Subsection
5824
5825 MCS51 Options
5826 \begin_inset LatexCommand \index{Options MCS51}
5827
5828 \end_inset
5829
5830
5831 \begin_inset LatexCommand \index{MCS51 options}
5832
5833 \end_inset
5834
5835
5836 \layout List
5837 \labelwidthstring 00.00.0000
5838
5839
5840 \series bold
5841 -
5842 \begin_inset ERT
5843 status Collapsed
5844
5845 \layout Standard
5846
5847 \backslash
5848 /
5849 \end_inset
5850
5851 -model-small
5852 \begin_inset LatexCommand \index{-\/-model-small}
5853
5854 \end_inset
5855
5856
5857 \series default
5858 \size large
5859 \emph on
5860
5861 \size default
5862 \emph default
5863 Generate code for Small Model programs, see section Memory Models for more
5864  details.
5865  This is the default model.
5866 \layout List
5867 \labelwidthstring 00.00.0000
5868
5869
5870 \series bold
5871 -
5872 \begin_inset ERT
5873 status Collapsed
5874
5875 \layout Standard
5876
5877 \backslash
5878 /
5879 \end_inset
5880
5881 -model-large
5882 \begin_inset LatexCommand \index{-\/-model-large}
5883
5884 \end_inset
5885
5886
5887 \series default
5888  Generate code for Large model programs, see section Memory Models for more
5889  details.
5890  If this option is used all source files in the project have to be compiled
5891  with this option.
5892 \layout List
5893 \labelwidthstring 00.00.0000
5894
5895
5896 \series bold
5897 -
5898 \begin_inset ERT
5899 status Collapsed
5900
5901 \layout Standard
5902
5903 \backslash
5904 /
5905 \end_inset
5906
5907 -xstack
5908 \begin_inset LatexCommand \index{-\/-xstack}
5909
5910 \end_inset
5911
5912
5913 \series default
5914  Uses a pseudo stack in the first 256 bytes in the external ram for allocating
5915  variables and passing parameters.
5916  See section
5917 \begin_inset LatexCommand \ref{sub:External-Stack}
5918
5919 \end_inset
5920
5921 \SpecialChar ~
5922  External Stack for more details.
5923 \layout List
5924 \labelwidthstring 00.00.0000
5925
5926
5927 \series bold
5928 -
5929 \begin_inset ERT
5930 status Collapsed
5931
5932 \layout Standard
5933
5934 \backslash
5935 /
5936 \end_inset
5937
5938 -iram-size
5939 \series default
5940 \SpecialChar ~
5941 <Value>
5942 \begin_inset LatexCommand \index{-\/-iram-size <Value>}
5943
5944 \end_inset
5945
5946  Causes the linker to check if the internal ram usage is within limits of
5947  the given value.
5948 \layout List
5949 \labelwidthstring 00.00.0000
5950
5951
5952 \series bold
5953 -
5954 \begin_inset ERT
5955 status Collapsed
5956
5957 \layout Standard
5958
5959 \backslash
5960 /
5961 \end_inset
5962
5963 -xram-size
5964 \series default
5965 \SpecialChar ~
5966 <Value>
5967 \begin_inset LatexCommand \index{-\/-xram-size <Value>}
5968
5969 \end_inset
5970
5971  Causes the linker to check if the external ram usage is within limits of
5972  the given value.
5973 \layout List
5974 \labelwidthstring 00.00.0000
5975
5976
5977 \series bold
5978 -
5979 \begin_inset ERT
5980 status Collapsed
5981
5982 \layout Standard
5983
5984 \backslash
5985 /
5986 \end_inset
5987
5988 -code-size
5989 \series default
5990 \SpecialChar ~
5991 <Value>
5992 \begin_inset LatexCommand \index{-\/-code-size <Value>}
5993
5994 \end_inset
5995
5996  Causes the linker to check if the code memory usage is within limits of
5997  the given value.
5998 \layout List
5999 \labelwidthstring 00.00.0000
6000
6001
6002 \series bold
6003 -
6004 \begin_inset ERT
6005 status Collapsed
6006
6007 \layout Standard
6008
6009 \backslash
6010 /
6011 \end_inset
6012
6013 -stack-size
6014 \series default
6015 \SpecialChar ~
6016 <Value>
6017 \begin_inset LatexCommand \index{-\/-stack-size <Value>}
6018
6019 \end_inset
6020
6021  Causes the linker to check if there is at minimum <Value> bytes for stack.
6022 \layout List
6023 \labelwidthstring 00.00.0000
6024
6025
6026 \series bold
6027 -
6028 \begin_inset ERT
6029 status Collapsed
6030
6031 \layout Standard
6032
6033 \backslash
6034 /
6035 \end_inset
6036
6037 -pack-iram
6038 \series default
6039 \SpecialChar ~
6040
6041 \begin_inset LatexCommand \index{-\/-pack-iram}
6042
6043 \end_inset
6044
6045  Causes the linker use unused register banks for data variables or stack.
6046 \layout Subsection
6047
6048 DS390 / DS400 Options
6049 \begin_inset LatexCommand \index{Options DS390}
6050
6051 \end_inset
6052
6053
6054 \begin_inset LatexCommand \index{DS390 options}
6055
6056 \end_inset
6057
6058
6059 \layout List
6060 \labelwidthstring 00.00.0000
6061
6062
6063 \series bold
6064 -
6065 \begin_inset ERT
6066 status Collapsed
6067
6068 \layout Standard
6069
6070 \backslash
6071 /
6072 \end_inset
6073
6074 -model-flat24
6075 \series default
6076
6077 \begin_inset LatexCommand \index{-\/-model-flat24}
6078
6079 \end_inset
6080
6081
6082 \size large
6083 \emph on
6084
6085 \size default
6086 \emph default
6087 Generate 24-bit flat mode code.
6088  This is the one and only that the ds390 code generator supports right now
6089  and is default when using
6090 \emph on
6091 -mds390
6092 \emph default
6093 .
6094  See section Memory Models for more details.
6095 \layout List
6096 \labelwidthstring 00.00.0000
6097
6098
6099 \series bold
6100 -
6101 \begin_inset ERT
6102 status Collapsed
6103
6104 \layout Standard
6105
6106 \backslash
6107 /
6108 \end_inset
6109
6110 -protect-sp-update
6111 \begin_inset LatexCommand \index{-\/-protect-sp-update}
6112
6113 \end_inset
6114
6115
6116 \series default
6117  disable interrupts during ESP:SP updates.
6118 \layout List
6119 \labelwidthstring 00.00.0000
6120
6121
6122 \series bold
6123 -
6124 \begin_inset ERT
6125 status Collapsed
6126
6127 \layout Standard
6128
6129 \backslash
6130 /
6131 \end_inset
6132
6133 -stack-10bit
6134 \series default
6135
6136 \begin_inset LatexCommand \index{-\/-stack-10bit}
6137
6138 \end_inset
6139
6140  Generate code for the 10 bit stack mode of the Dallas DS80C390 part.
6141  This is the one and only that the ds390 code generator supports right now
6142  and is default when using
6143 \emph on
6144 -mds390
6145 \emph default
6146 .
6147  In this mode, the stack is located in the lower 1K of the internal RAM,
6148  which is mapped to 0x400000.
6149  Note that the support is incomplete, since it still uses a single byte
6150  as the stack pointer.
6151  This means that only the lower 256 bytes of the potential 1K stack space
6152  will actually be used.
6153  However, this does allow you to reclaim the precious 256 bytes of low RAM
6154  for use for the DATA and IDATA segments.
6155  The compiler will not generate any code to put the processor into 10 bit
6156  stack mode.
6157  It is important to ensure that the processor is in this mode before calling
6158  any re-entrant functions compiled with this option.
6159  In principle, this should work with the
6160 \emph on
6161 -
6162 \begin_inset ERT
6163 status Collapsed
6164
6165 \layout Standard
6166
6167 \backslash
6168 /
6169 \end_inset
6170
6171 -stack-auto
6172 \begin_inset LatexCommand \index{-\/-stack-auto}
6173
6174 \end_inset
6175
6176
6177 \emph default
6178  option, but that has not been tested.
6179  It is incompatible with the
6180 \emph on
6181 -
6182 \begin_inset ERT
6183 status Collapsed
6184
6185 \layout Standard
6186
6187 \backslash
6188 /
6189 \end_inset
6190
6191 -xstack
6192 \begin_inset LatexCommand \index{-\/-xstack}
6193
6194 \end_inset
6195
6196
6197 \emph default
6198  option.
6199  It also only makes sense if the processor is in 24 bit contiguous addressing
6200  mode (see the
6201 \emph on
6202 -
6203 \begin_inset ERT
6204 status Collapsed
6205
6206 \layout Standard
6207
6208 \backslash
6209 /
6210 \end_inset
6211
6212 -model-flat24 option
6213 \emph default
6214 ).
6215 \layout List
6216 \labelwidthstring 00.00.0000
6217
6218
6219 \series bold
6220 -
6221 \begin_inset ERT
6222 status Collapsed
6223
6224 \layout Standard
6225
6226 \backslash
6227 /
6228 \end_inset
6229
6230 -stack-probe
6231 \begin_inset LatexCommand \index{-\/-stack-probe}
6232
6233 \end_inset
6234
6235
6236 \series default
6237  insert call to function __stack_probe at each function prologue.
6238 \layout List
6239 \labelwidthstring 00.00.0000
6240
6241
6242 \series bold
6243 -
6244 \begin_inset ERT
6245 status Collapsed
6246
6247 \layout Standard
6248
6249 \backslash
6250 /
6251 \end_inset
6252
6253 -tini-libid
6254 \begin_inset LatexCommand \index{-\/-tini-libid}
6255
6256 \end_inset
6257
6258
6259 \series default
6260  <nnnn> LibraryID used in -mTININative.
6261
6262 \layout List
6263 \labelwidthstring 00.00.0000
6264
6265
6266 \series bold
6267 -
6268 \begin_inset ERT
6269 status Collapsed
6270
6271 \layout Standard
6272
6273 \backslash
6274 /
6275 \end_inset
6276
6277 -use-accelerator
6278 \begin_inset LatexCommand \index{-\/-use-accelerator}
6279
6280 \end_inset
6281
6282
6283 \series default
6284  generate code for DS390 Arithmetic Accelerator.
6285
6286 \layout Subsection
6287
6288 Z80 Options
6289 \begin_inset LatexCommand \index{Options Z80}
6290
6291 \end_inset
6292
6293
6294 \begin_inset LatexCommand \index{Z80 options}
6295
6296 \end_inset
6297
6298
6299 \layout List
6300 \labelwidthstring 00.00.0000
6301
6302
6303 \series bold
6304 -
6305 \begin_inset ERT
6306 status Collapsed
6307
6308 \layout Standard
6309
6310 \backslash
6311 /
6312 \end_inset
6313
6314 -callee-saves-bc
6315 \series default
6316
6317 \begin_inset LatexCommand \index{-\/-callee-saves-bc}
6318
6319 \end_inset
6320
6321
6322 \size large
6323 \emph on
6324
6325 \size default
6326 \emph default
6327 Force a called function to always save BC.
6328 \layout List
6329 \labelwidthstring 00.00.0000
6330
6331
6332 \series bold
6333 -
6334 \begin_inset ERT
6335 status Collapsed
6336
6337 \layout Standard
6338
6339 \backslash
6340 /
6341 \end_inset
6342
6343 -no-std-crt0
6344 \series default
6345
6346 \begin_inset LatexCommand \index{-\/-no-std-crt0}
6347
6348 \end_inset
6349
6350  When linking, skip the standard crt0.o object file.
6351  You must provide your own crt0.o for your system when linking.
6352
6353 \layout Subsection
6354
6355 Optimization Options
6356 \begin_inset LatexCommand \index{Options optimization}
6357
6358 \end_inset
6359
6360
6361 \begin_inset LatexCommand \index{Optimization options}
6362
6363 \end_inset
6364
6365
6366 \layout List
6367 \labelwidthstring 00.00.0000
6368
6369
6370 \series bold
6371 -
6372 \begin_inset ERT
6373 status Collapsed
6374
6375 \layout Standard
6376
6377 \backslash
6378 /
6379 \end_inset
6380
6381 -nogcse
6382 \begin_inset LatexCommand \index{-\/-nogcse}
6383
6384 \end_inset
6385
6386
6387 \series default
6388  Will not do global subexpression elimination, this option may be used when
6389  the compiler creates undesirably large stack/data spaces to store compiler
6390  temporaries.
6391  A warning message will be generated when this happens and the compiler
6392  will indicate the number of extra bytes it allocated.
6393  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6394 nogcse
6395 \begin_inset LatexCommand \index{\#pragma nogcse}
6396
6397 \end_inset
6398
6399  can be used to turn off global subexpression elimination
6400 \begin_inset LatexCommand \index{Subexpression elimination}
6401
6402 \end_inset
6403
6404  for a given function only.
6405 \layout List
6406 \labelwidthstring 00.00.0000
6407
6408
6409 \series bold
6410 -
6411 \begin_inset ERT
6412 status Collapsed
6413
6414 \layout Standard
6415
6416 \backslash
6417 /
6418 \end_inset
6419
6420 -noinvariant
6421 \begin_inset LatexCommand \index{-\/-noinvariant}
6422
6423 \end_inset
6424
6425
6426 \series default
6427  Will not do loop invariant optimizations, this may be turned off for reasons
6428  explained for the previous option.
6429  For more details of loop optimizations performed see Loop Invariants in
6430  section
6431 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
6432
6433 \end_inset
6434
6435 .
6436  It is recommended that this option NOT be used, #pragma\SpecialChar ~
6437 noinvariant
6438 \begin_inset LatexCommand \index{\#pragma noinvariant}
6439
6440 \end_inset
6441
6442  can be used to turn off invariant optimizations for a given function only.
6443 \layout List
6444 \labelwidthstring 00.00.0000
6445
6446
6447 \series bold
6448 -
6449 \begin_inset ERT
6450 status Collapsed
6451
6452 \layout Standard
6453
6454 \backslash
6455 /
6456 \end_inset
6457
6458 -noinduction
6459 \begin_inset LatexCommand \index{-\/-noinduction}
6460
6461 \end_inset
6462
6463
6464 \series default
6465  Will not do loop induction optimizations, see section strength reduction
6466  for more details.
6467  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6468 noinduction
6469 \begin_inset LatexCommand \index{\#pragma noinduction}
6470
6471 \end_inset
6472
6473  can be used to turn off induction optimizations for a given function only.
6474 \layout List
6475 \labelwidthstring 00.00.0000
6476
6477
6478 \series bold
6479 -
6480 \begin_inset ERT
6481 status Collapsed
6482
6483 \layout Standard
6484
6485 \backslash
6486 /
6487 \end_inset
6488
6489 -nojtbound
6490 \begin_inset LatexCommand \index{-\/-nojtbound}
6491
6492 \end_inset
6493
6494
6495 \size large
6496 \bar under
6497
6498 \series default
6499 \size default
6500 \bar default
6501  Will not generate boundary condition check when switch statements
6502 \begin_inset LatexCommand \index{switch statement}
6503
6504 \end_inset
6505
6506  are implemented using jump-tables.
6507  See section
6508 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
6509
6510 \end_inset
6511
6512 \SpecialChar ~
6513 Switch Statements for more details.
6514  It is recommended that this option is NOT used, #pragma\SpecialChar ~
6515 nojtbound
6516 \begin_inset LatexCommand \index{\#pragma nojtbound}
6517
6518 \end_inset
6519
6520  can be used to turn off boundary checking for jump tables for a given function
6521  only.
6522 \layout List
6523 \labelwidthstring 00.00.0000
6524
6525
6526 \series bold
6527 -
6528 \begin_inset ERT
6529 status Collapsed
6530
6531 \layout Standard
6532
6533 \backslash
6534 /
6535 \end_inset
6536
6537 -noloopreverse
6538 \begin_inset LatexCommand \index{-\/-noloopreverse}
6539
6540 \end_inset
6541
6542
6543 \series default
6544 \size large
6545
6546 \size default
6547 Will not do loop reversal
6548 \begin_inset LatexCommand \index{Loop reversing}
6549
6550 \end_inset
6551
6552 optimization.
6553 \layout List
6554 \labelwidthstring 00.00.0000
6555
6556 -
6557 \begin_inset ERT
6558 status Collapsed
6559
6560 \layout Standard
6561
6562 \backslash
6563 /
6564 \end_inset
6565
6566 -
6567 \series bold
6568 nolabelopt
6569 \series default
6570
6571 \begin_inset LatexCommand \index{-\/-nolabelopt }
6572
6573 \end_inset
6574
6575 Will not optimize labels (makes the dumpfiles more readable).
6576 \layout List
6577 \labelwidthstring 00.00.0000
6578
6579
6580 \series bold
6581 -
6582 \begin_inset ERT
6583 status Collapsed
6584
6585 \layout Standard
6586
6587 \backslash
6588 /
6589 \end_inset
6590
6591 -no-xinit-opt
6592 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
6593
6594 \end_inset
6595
6596
6597 \series default
6598  Will not memcpy initialized data from code space into xdata space.
6599  This saves a few bytes in code space if you don't have initialized data.
6600 \layout List
6601 \labelwidthstring 00.00.0000
6602
6603
6604 \series bold
6605 -
6606 \begin_inset ERT
6607 status Collapsed
6608
6609 \layout Standard
6610
6611 \backslash
6612 /
6613 \end_inset
6614
6615 -nooverlay
6616 \begin_inset LatexCommand \index{-\/-nooverlay}
6617
6618 \end_inset
6619
6620
6621 \series default
6622   The compiler will not overlay parameters and local variables of any function,
6623  see section Parameters and local variables for more details.
6624 \layout List
6625 \labelwidthstring 00.00.0000
6626
6627
6628 \series bold
6629 -
6630 \begin_inset ERT
6631 status Collapsed
6632
6633 \layout Standard
6634
6635 \backslash
6636 /
6637 \end_inset
6638
6639 -no-peep
6640 \begin_inset LatexCommand \index{-\/-no-peep}
6641
6642 \end_inset
6643
6644
6645 \series default
6646  Disable peep-hole optimization.
6647 \layout List
6648 \labelwidthstring 00.00.0000
6649
6650
6651 \series bold
6652 -
6653 \begin_inset ERT
6654 status Collapsed
6655
6656 \layout Standard
6657
6658 \backslash
6659 /
6660 \end_inset
6661
6662 -peep-file
6663 \series default
6664
6665 \begin_inset LatexCommand \index{-\/-peep-file}
6666
6667 \end_inset
6668
6669 \SpecialChar ~
6670 <filename> This option can be used to use additional rules to be used by
6671  the peep hole optimizer.
6672  See section
6673 \begin_inset LatexCommand \ref{sub:Peephole-Optimizer}
6674
6675 \end_inset
6676
6677 \SpecialChar ~
6678 Peep Hole optimizations for details on how to write these rules.
6679 \layout List
6680 \labelwidthstring 00.00.0000
6681
6682
6683 \series bold
6684 -
6685 \begin_inset ERT
6686 status Collapsed
6687
6688 \layout Standard
6689
6690 \backslash
6691 /
6692 \end_inset
6693
6694 -peep-asm
6695 \begin_inset LatexCommand \index{-\/-peep-asm}
6696
6697 \end_inset
6698
6699
6700 \series default
6701   Pass the inline assembler code through the peep hole optimizer.
6702  This can cause unexpected changes to inline assembler code, please go through
6703  the peephole optimizer
6704 \begin_inset LatexCommand \index{Peephole optimizer}
6705
6706 \end_inset
6707
6708  rules defined in the source file tree '<target>/peeph.def' before using
6709  this option.
6710 \layout Subsection
6711
6712 Other Options
6713 \begin_inset LatexCommand \index{Options other}
6714
6715 \end_inset
6716
6717
6718 \layout List
6719 \labelwidthstring 00.00.0000
6720
6721
6722 \series bold
6723 -c\SpecialChar ~
6724 -
6725 \begin_inset ERT
6726 status Collapsed
6727
6728 \layout Standard
6729
6730 \backslash
6731 /
6732 \end_inset
6733
6734 -compile-only
6735 \begin_inset LatexCommand \index{-\/-compile-only}
6736
6737 \end_inset
6738
6739
6740 \begin_inset LatexCommand \index{-c -\/-compile-only}
6741
6742 \end_inset
6743
6744
6745 \series default
6746  will compile and assemble the source, but will not call the linkage editor.
6747 \layout List
6748 \labelwidthstring 00.00.0000
6749
6750
6751 \series bold
6752 -
6753 \series default
6754
6755 \begin_inset ERT
6756 status Collapsed
6757
6758 \layout Standard
6759
6760 \backslash
6761 /
6762 \end_inset
6763
6764
6765 \series bold
6766 -c1mode
6767 \begin_inset LatexCommand \index{-\/-c1mode}
6768
6769 \end_inset
6770
6771
6772 \series default
6773  reads the preprocessed source from standard input and compiles it.
6774  The file name for the assembler output must be specified using the -o option.
6775 \layout List
6776 \labelwidthstring 00.00.0000
6777
6778
6779 \series bold
6780 -E
6781 \begin_inset LatexCommand \index{-E}
6782
6783 \end_inset
6784
6785
6786 \series default
6787  Run only the C preprocessor.
6788  Preprocess all the C source files specified and output the results to standard
6789  output.
6790 \layout List
6791 \labelwidthstring 00.00.0000
6792
6793
6794 \series bold
6795 -o\SpecialChar ~
6796 <path/file>
6797 \begin_inset LatexCommand \index{-o <path/file>}
6798
6799 \end_inset
6800
6801
6802 \series default
6803 The output path resp.
6804  file where everything will be placed.
6805  If the parameter is a path, it must have a trailing slash (or backslash
6806  for the Windows binaries) to be recognized as a path.
6807
6808 \layout List
6809 \labelwidthstring 00.00.0000
6810
6811
6812 \series bold
6813 -
6814 \begin_inset ERT
6815 status Collapsed
6816
6817 \layout Standard
6818
6819 \backslash
6820 /
6821 \end_inset
6822
6823 -stack-auto
6824 \begin_inset LatexCommand \index{-\/-stack-auto}
6825
6826 \end_inset
6827
6828
6829 \series default
6830 \size large
6831 \emph on
6832
6833 \size default
6834 \emph default
6835 All functions in the source file will be compiled as
6836 \emph on
6837 reentrant
6838 \emph default
6839
6840 \begin_inset LatexCommand \index{reentrant}
6841
6842 \end_inset
6843
6844 , i.e.
6845  the parameters and local variables will be allocated on the stack
6846 \begin_inset LatexCommand \index{stack}
6847
6848 \end_inset
6849
6850 .
6851  See section
6852 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
6853
6854 \end_inset
6855
6856  Parameters and Local Variables for more details.
6857  If this option is used all source files in the project should be compiled
6858  with this option.
6859
6860 \layout List
6861 \labelwidthstring 00.00.0000
6862
6863
6864 \series bold
6865 -
6866 \begin_inset ERT
6867 status Collapsed
6868
6869 \layout Standard
6870
6871 \backslash
6872 /
6873 \end_inset
6874
6875 -callee-saves
6876 \begin_inset LatexCommand \index{-\/-callee-saves}
6877
6878 \end_inset
6879
6880  function1[,function2][,function3]....
6881
6882 \series default
6883  The compiler by default uses a caller saves convention for register saving
6884  across function calls, however this can cause unnecessary register pushing
6885  & popping when calling small functions from larger functions.
6886  This option can be used to switch the register saving convention for the
6887  function names specified.
6888  The compiler will not save registers when calling these functions, no extra
6889  code will be generated at the entry & exit (function prologue
6890 \series bold
6891
6892 \begin_inset LatexCommand \index{function prologue}
6893
6894 \end_inset
6895
6896
6897 \series default
6898  & epilogue
6899 \series bold
6900
6901 \begin_inset LatexCommand \index{function epilogue}
6902
6903 \end_inset
6904
6905
6906 \series default
6907 ) for these functions to save & restore the registers used by these functions,
6908  this can SUBSTANTIALLY reduce code & improve run time performance of the
6909  generated code.
6910  In the future the compiler (with inter procedural analysis) will be able
6911  to determine the appropriate scheme to use for each function call.
6912  DO NOT use this option for built-in functions such as _mulint..., if this
6913  option is used for a library function the appropriate library function
6914  needs to be recompiled with the same option.
6915  If the project consists of multiple source files then all the source file
6916  should be compiled with the same -
6917 \begin_inset ERT
6918 status Collapsed
6919
6920 \layout Standard
6921
6922 \backslash
6923 /
6924 \end_inset
6925
6926 -callee-saves option string.
6927  Also see #pragma\SpecialChar ~
6928 callee_saves
6929 \begin_inset LatexCommand \index{\#pragma callee\_saves}
6930
6931 \end_inset
6932
6933 .
6934 \layout List
6935 \labelwidthstring 00.00.0000
6936
6937
6938 \series bold
6939 -
6940 \begin_inset ERT
6941 status Open
6942
6943 \layout Standard
6944
6945 \backslash
6946 /
6947 \end_inset
6948
6949 -debug
6950 \begin_inset LatexCommand \index{-\/-debug}
6951
6952 \end_inset
6953
6954
6955 \bar under
6956
6957 \series default
6958 \bar default
6959 When this option is used the compiler will generate debug information.
6960  The debug information collected in a file with .cdb extension can be used
6961  with the SDCDB.
6962  For more information see documentation for SDCDB.
6963  Another file with no extension contains debug information in AOMF or AOMF51
6964 \begin_inset LatexCommand \index{AOMF, AOMF51}
6965
6966 \end_inset
6967
6968  format which is commonly used by third party tools.
6969 \layout List
6970 \labelwidthstring 00.00.0000
6971
6972
6973 \series bold
6974 -S
6975 \begin_inset LatexCommand \index{-S}
6976
6977 \end_inset
6978
6979
6980 \size large
6981 \bar under
6982
6983 \series default
6984 \size default
6985 \bar default
6986 Stop after the stage of compilation proper; do not assemble.
6987  The output is an assembler code file for the input file specified.
6988 \layout List
6989 \labelwidthstring 00.00.0000
6990
6991
6992 \series bold
6993 -
6994 \begin_inset ERT
6995 status Collapsed
6996
6997 \layout Standard
6998
6999 \backslash
7000 /
7001 \end_inset
7002
7003 -int-long-reent
7004 \begin_inset LatexCommand \index{-\/-int-long-reent}
7005
7006 \end_inset
7007
7008
7009 \series default
7010  Integer (16 bit) and long (32 bit) libraries have been compiled as reentrant.
7011  Note by default these libraries are compiled as non-reentrant.
7012  See section Installation for more details.
7013 \layout List
7014 \labelwidthstring 00.00.0000
7015
7016
7017 \series bold
7018 -
7019 \begin_inset ERT
7020 status Collapsed
7021
7022 \layout Standard
7023
7024 \backslash
7025 /
7026 \end_inset
7027
7028 -cyclomatic
7029 \begin_inset LatexCommand \index{-\/-cyclomatic}
7030
7031 \end_inset
7032
7033
7034 \bar under
7035
7036 \series default
7037 \bar default
7038 This option will cause the compiler to generate an information message for
7039  each function in the source file.
7040  The message contains some
7041 \emph on
7042 important
7043 \emph default
7044  information about the function.
7045  The number of edges and nodes the compiler detected in the control flow
7046  graph of the function, and most importantly the
7047 \emph on
7048 cyclomatic complexity
7049 \begin_inset LatexCommand \index{Cyclomatic complexity}
7050
7051 \end_inset
7052
7053
7054 \emph default
7055  see section on Cyclomatic Complexity for more details.
7056 \layout List
7057 \labelwidthstring 00.00.0000
7058
7059
7060 \series bold
7061 -
7062 \begin_inset ERT
7063 status Collapsed
7064
7065 \layout Standard
7066
7067 \backslash
7068 /
7069 \end_inset
7070
7071 -float-reent
7072 \begin_inset LatexCommand \index{-\/-float-reent}
7073
7074 \end_inset
7075
7076
7077 \series default
7078  Floating point library is compiled as reentrant
7079 \begin_inset LatexCommand \index{reentrant}
7080
7081 \end_inset
7082
7083 .
7084  See section Installation for more details.
7085 \layout List
7086 \labelwidthstring 00.00.0000
7087
7088
7089 \series bold
7090 -
7091 \begin_inset ERT
7092 status Collapsed
7093
7094 \layout Standard
7095
7096 \backslash
7097 /
7098 \end_inset
7099
7100 -main-return
7101 \begin_inset LatexCommand \index{-\/-main-return}
7102
7103 \end_inset
7104
7105
7106 \series default
7107  This option can be used if the code generated is called by a monitor program
7108  or if the main routine includes an endless loop.
7109  This option might result in slightly smaller code and save two bytes of
7110  stack space.
7111  The return from the 'main'
7112 \begin_inset LatexCommand \index{main return}
7113
7114 \end_inset
7115
7116  function will return to the function calling main.
7117  The default setting is to lock up i.e.
7118  generate a '
7119 \family typewriter
7120 sjmp .
7121 \family default
7122 '.
7123 \layout List
7124 \labelwidthstring 00.00.0000
7125
7126
7127 \series bold
7128 -
7129 \begin_inset ERT
7130 status Collapsed
7131
7132 \layout Standard
7133
7134 \backslash
7135 /
7136 \end_inset
7137
7138 -nostdincl
7139 \begin_inset LatexCommand \index{-\/-nostdincl}
7140
7141 \end_inset
7142
7143
7144 \series default
7145  This will prevent the compiler from passing on the default include path
7146  to the preprocessor.
7147 \layout List
7148 \labelwidthstring 00.00.0000
7149
7150
7151 \series bold
7152 -
7153 \begin_inset ERT
7154 status Collapsed
7155
7156 \layout Standard
7157
7158 \backslash
7159 /
7160 \end_inset
7161
7162 -nostdlib
7163 \begin_inset LatexCommand \index{-\/-nostdlib}
7164
7165 \end_inset
7166
7167
7168 \series default
7169  This will prevent the compiler from passing on the default library
7170 \begin_inset LatexCommand \index{Libraries}
7171
7172 \end_inset
7173
7174  path to the linker.
7175 \layout List
7176 \labelwidthstring 00.00.0000
7177
7178
7179 \series bold
7180 -
7181 \begin_inset ERT
7182 status Collapsed
7183
7184 \layout Standard
7185
7186 \backslash
7187 /
7188 \end_inset
7189
7190 -verbose
7191 \begin_inset LatexCommand \index{-\/-verbose}
7192
7193 \end_inset
7194
7195
7196 \series default
7197  Shows the various actions the compiler is performing.
7198 \layout List
7199 \labelwidthstring 00.00.0000
7200
7201
7202 \series bold
7203 -V
7204 \begin_inset LatexCommand \index{-V}
7205
7206 \end_inset
7207
7208
7209 \series default
7210  Shows the actual commands the compiler is executing.
7211 \layout List
7212 \labelwidthstring 00.00.0000
7213
7214
7215 \series bold
7216 -
7217 \begin_inset ERT
7218 status Collapsed
7219
7220 \layout Standard
7221
7222 \backslash
7223 /
7224 \end_inset
7225
7226 -no-c-code-in-asm
7227 \begin_inset LatexCommand \index{-\/-no-c-code-in-asm}
7228
7229 \end_inset
7230
7231
7232 \series default
7233  Hides your ugly and inefficient c-code from the asm file, so you can always
7234  blame the compiler :)
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 -no-peep-comments
7251 \begin_inset LatexCommand \index{-\/-no-peep-comments}
7252
7253 \end_inset
7254
7255
7256 \series default
7257  Will not include peep-hole comments in the generated files.
7258 \layout List
7259 \labelwidthstring 00.00.0000
7260
7261
7262 \series bold
7263 -
7264 \begin_inset ERT
7265 status Collapsed
7266
7267 \layout Standard
7268
7269 \backslash
7270 /
7271 \end_inset
7272
7273 -i-code-in-asm
7274 \begin_inset LatexCommand \index{-\/-i-code-in-asm}
7275
7276 \end_inset
7277
7278
7279 \series default
7280  Include i-codes in the asm file.
7281  Sounds like noise but is most helpful for debugging the compiler itself.
7282 \layout List
7283 \labelwidthstring 00.00.0000
7284
7285
7286 \series bold
7287 -
7288 \begin_inset ERT
7289 status Collapsed
7290
7291 \layout Standard
7292
7293 \backslash
7294 /
7295 \end_inset
7296
7297 -less-pedantic
7298 \begin_inset LatexCommand \index{-\/-less-pedantic}
7299
7300 \end_inset
7301
7302
7303 \series default
7304  Disable some of the more pedantic warnings
7305 \begin_inset LatexCommand \index{Warnings}
7306
7307 \end_inset
7308
7309  (jwk burps: please be more specific here, please!).
7310  If you want rather more than less warnings you should consider using a
7311  separate tool dedicated to syntax checking like splint
7312 \begin_inset LatexCommand \url{www.splint.org}
7313
7314 \end_inset
7315
7316 .
7317 \layout List
7318 \labelwidthstring 00.00.0000
7319
7320
7321 \series bold
7322 -
7323 \begin_inset ERT
7324 status Collapsed
7325
7326 \layout Standard
7327
7328 \backslash
7329 /
7330 \end_inset
7331
7332 -print-search-dirs
7333 \begin_inset LatexCommand \index{-\/-print-search-dirs}
7334
7335 \end_inset
7336
7337
7338 \series default
7339  Display the directories in the compiler's search path
7340 \layout List
7341 \labelwidthstring 00.00.0000
7342
7343
7344 \series bold
7345 -
7346 \begin_inset ERT
7347 status Collapsed
7348
7349 \layout Standard
7350
7351 \backslash
7352 /
7353 \end_inset
7354
7355 -vc
7356 \begin_inset LatexCommand \index{-\/-vc}
7357
7358 \end_inset
7359
7360
7361 \series default
7362  Display errors and warnings using MSVC style, so you can use SDCC with
7363  visual studio.
7364 \layout List
7365 \labelwidthstring 00.00.0000
7366
7367
7368 \series bold
7369 -
7370 \begin_inset ERT
7371 status Collapsed
7372
7373 \layout Standard
7374
7375 \backslash
7376 /
7377 \end_inset
7378
7379 -use-stdout
7380 \begin_inset LatexCommand \index{-\/-use-stdout}
7381
7382 \end_inset
7383
7384
7385 \series default
7386  Send errors and warnings to stdout instead of stderr.
7387 \layout List
7388 \labelwidthstring 00.00.0000
7389
7390
7391 \series bold
7392 -Wa\SpecialChar ~
7393 asmOption[,asmOption]
7394 \series default
7395
7396 \begin_inset LatexCommand \index{-Wa asmOption[,asmOption]}
7397
7398 \end_inset
7399
7400 ...
7401  Pass the asmOption to the assembler
7402 \begin_inset LatexCommand \index{Options assembler}
7403
7404 \end_inset
7405
7406
7407 \begin_inset LatexCommand \index{Assembler options}
7408
7409 \end_inset
7410
7411 .
7412  See file sdcc/as/doc/asxhtm.html for assembler options.
7413 \layout Subsection
7414
7415 Intermediate Dump Options
7416 \begin_inset LatexCommand \label{sub:Intermediate-Dump-Options}
7417
7418 \end_inset
7419
7420
7421 \begin_inset LatexCommand \index{Options intermediate dump}
7422
7423 \end_inset
7424
7425
7426 \begin_inset LatexCommand \index{Intermediate dump options}
7427
7428 \end_inset
7429
7430
7431 \layout Standard
7432
7433 The following options are provided for the purpose of retargetting and debugging
7434  the compiler.
7435  These provided a means to dump the intermediate code (iCode
7436 \begin_inset LatexCommand \index{iCode}
7437
7438 \end_inset
7439
7440 ) generated by the compiler in human readable form at various stages of
7441  the compilation process.
7442  More on iCodes see chapter
7443 \begin_inset LatexCommand \ref{sub:The-anatomy-of}
7444
7445 \end_inset
7446
7447
7448 \begin_inset Quotes srd
7449 \end_inset
7450
7451 The anatomy of the compiler
7452 \begin_inset Quotes srd
7453 \end_inset
7454
7455 .
7456 \layout List
7457 \labelwidthstring 00.00.0000
7458
7459
7460 \series bold
7461 -
7462 \begin_inset ERT
7463 status Collapsed
7464
7465 \layout Standard
7466
7467 \backslash
7468 /
7469 \end_inset
7470
7471 -dumpraw
7472 \begin_inset LatexCommand \index{-\/-dumpraw}
7473
7474 \end_inset
7475
7476
7477 \series default
7478  This option will cause the compiler to dump the intermediate code into
7479  a file of named
7480 \emph on
7481 <source filename>.dumpraw
7482 \emph default
7483  just after the intermediate code has been generated for a function, i.e.
7484  before any optimizations are done.
7485  The basic blocks
7486 \begin_inset LatexCommand \index{Basic blocks}
7487
7488 \end_inset
7489
7490  at this stage ordered in the depth first number, so they may not be in
7491  sequence of execution.
7492 \layout List
7493 \labelwidthstring 00.00.0000
7494
7495
7496 \series bold
7497 -
7498 \begin_inset ERT
7499 status Collapsed
7500
7501 \layout Standard
7502
7503 \backslash
7504 /
7505 \end_inset
7506
7507 -dumpgcse
7508 \begin_inset LatexCommand \index{-\/-dumpgcse}
7509
7510 \end_inset
7511
7512
7513 \series default
7514  Will create a dump of iCode's, after global subexpression elimination
7515 \begin_inset LatexCommand \index{Global subexpression elimination}
7516
7517 \end_inset
7518
7519 , into a file named
7520 \emph on
7521 <source filename>.dumpgcse.
7522 \layout List
7523 \labelwidthstring 00.00.0000
7524
7525
7526 \series bold
7527 -
7528 \begin_inset ERT
7529 status Collapsed
7530
7531 \layout Standard
7532
7533 \backslash
7534 /
7535 \end_inset
7536
7537 -dumpdeadcode
7538 \begin_inset LatexCommand \index{-\/-dumpdeadcode}
7539
7540 \end_inset
7541
7542
7543 \series default
7544  Will create a dump of iCode's, after deadcode elimination
7545 \begin_inset LatexCommand \index{Dead-code elimination}
7546
7547 \end_inset
7548
7549 , into a file named
7550 \emph on
7551 <source filename>.dumpdeadcode.
7552 \layout List
7553 \labelwidthstring 00.00.0000
7554
7555
7556 \series bold
7557 -
7558 \begin_inset ERT
7559 status Collapsed
7560
7561 \layout Standard
7562
7563 \backslash
7564 /
7565 \end_inset
7566
7567 -dumploop
7568 \begin_inset LatexCommand \index{-\/-dumploop}
7569
7570 \end_inset
7571
7572
7573 \series default
7574 \size large
7575
7576 \size default
7577 Will create a dump of iCode's, after loop optimizations
7578 \begin_inset LatexCommand \index{Loop optimization}
7579
7580 \end_inset
7581
7582 , into a file named
7583 \emph on
7584 <source filename>.dumploop.
7585 \layout List
7586 \labelwidthstring 00.00.0000
7587
7588
7589 \series bold
7590 -
7591 \begin_inset ERT
7592 status Collapsed
7593
7594 \layout Standard
7595
7596 \backslash
7597 /
7598 \end_inset
7599
7600 -dumprange
7601 \begin_inset LatexCommand \index{-\/-dumprange}
7602
7603 \end_inset
7604
7605
7606 \series default
7607 \size large
7608
7609 \size default
7610 Will create a dump of iCode's, after live range analysis
7611 \begin_inset LatexCommand \index{Live range analysis}
7612
7613 \end_inset
7614
7615 , into a file named
7616 \emph on
7617 <source filename>.dumprange.
7618 \layout List
7619 \labelwidthstring 00.00.0000
7620
7621
7622 \series bold
7623 -
7624 \begin_inset ERT
7625 status Collapsed
7626
7627 \layout Standard
7628
7629 \backslash
7630 /
7631 \end_inset
7632
7633 -dumlrange
7634 \begin_inset LatexCommand \index{-\/-dumlrange}
7635
7636 \end_inset
7637
7638
7639 \series default
7640  Will dump the life ranges
7641 \begin_inset LatexCommand \index{Live range analysis}
7642
7643 \end_inset
7644
7645  for all symbols.
7646 \layout List
7647 \labelwidthstring 00.00.0000
7648
7649
7650 \series bold
7651 -
7652 \begin_inset ERT
7653 status Collapsed
7654
7655 \layout Standard
7656
7657 \backslash
7658 /
7659 \end_inset
7660
7661 -dumpregassign
7662 \begin_inset LatexCommand \index{-\/-dumpregassign}
7663
7664 \end_inset
7665
7666
7667 \bar under
7668
7669 \series default
7670 \bar default
7671 Will create a dump of iCode's, after register assignment
7672 \begin_inset LatexCommand \index{Register assignment}
7673
7674 \end_inset
7675
7676 , into a file named
7677 \emph on
7678 <source filename>.dumprassgn.
7679 \layout List
7680 \labelwidthstring 00.00.0000
7681
7682
7683 \series bold
7684 -
7685 \begin_inset ERT
7686 status Collapsed
7687
7688 \layout Standard
7689
7690 \backslash
7691 /
7692 \end_inset
7693
7694 -dumplrange
7695 \begin_inset LatexCommand \index{-\/-dumplrange}
7696
7697 \end_inset
7698
7699
7700 \series default
7701  Will create a dump of the live ranges of iTemp's
7702 \layout List
7703 \labelwidthstring 00.00.0000
7704
7705
7706 \series bold
7707 -
7708 \begin_inset ERT
7709 status Collapsed
7710
7711 \layout Standard
7712
7713 \backslash
7714 /
7715 \end_inset
7716
7717 -dumpall
7718 \begin_inset LatexCommand \index{-\/-dumpall}
7719
7720 \end_inset
7721
7722
7723 \size large
7724 \bar under
7725
7726 \series default
7727 \size default
7728 \bar default
7729 Will cause all the above mentioned dumps to be created.
7730 \layout Subsection
7731
7732 Redirecting output on Windows Shells
7733 \layout Standard
7734
7735 By default SDCC writes it's error messages to
7736 \begin_inset Quotes sld
7737 \end_inset
7738
7739 standard error
7740 \begin_inset Quotes srd
7741 \end_inset
7742
7743 .
7744  To force all messages to
7745 \begin_inset Quotes sld
7746 \end_inset
7747
7748 standard output
7749 \begin_inset Quotes srd
7750 \end_inset
7751
7752  use
7753 \series bold
7754 -
7755 \series default
7756 \emph on
7757
7758 \begin_inset ERT
7759 status Collapsed
7760
7761 \layout Standard
7762
7763 \backslash
7764 /
7765 \end_inset
7766
7767
7768 \series bold
7769 \emph default
7770 -
7771 \series default
7772 use-stdout
7773 \begin_inset LatexCommand \index{-\/-use-stdout}
7774
7775 \end_inset
7776
7777 .
7778  Additionally, if you happen to have visual studio installed in your windows
7779  machine, you can use it to compile your sources using a custom build and
7780  the SDCC -
7781 \emph on
7782
7783 \begin_inset ERT
7784 status Collapsed
7785
7786 \layout Standard
7787
7788 \backslash
7789 /
7790 \end_inset
7791
7792
7793 \emph default
7794 -vc
7795 \begin_inset LatexCommand \index{-\/-vc}
7796
7797 \end_inset
7798
7799  option.
7800  Something like this should work:
7801 \newline
7802
7803 \newline
7804
7805 \series bold
7806 c:
7807 \backslash
7808 sdcc
7809 \backslash
7810 bin
7811 \backslash
7812 sdcc.exe -
7813 \series default
7814 \emph on
7815
7816 \begin_inset ERT
7817 status Collapsed
7818
7819 \layout Standard
7820
7821 \backslash
7822 /
7823 \end_inset
7824
7825
7826 \series bold
7827 \emph default
7828 -vc -
7829 \series default
7830 \emph on
7831
7832 \begin_inset ERT
7833 status Collapsed
7834
7835 \layout Standard
7836
7837 \backslash
7838 /
7839 \end_inset
7840
7841
7842 \series bold
7843 \emph default
7844 -model-large -c $(InputPath)
7845 \layout Section
7846
7847 Environment variables
7848 \begin_inset LatexCommand \index{Environment variables}
7849
7850 \end_inset
7851
7852
7853 \layout Standard
7854
7855 SDCC recognizes the following environment variables:
7856 \layout List
7857 \labelwidthstring 00.00.0000
7858
7859
7860 \series bold
7861 SDCC_LEAVE_SIGNALS
7862 \begin_inset LatexCommand \index{SDCC\_LEAVE\_SIGNALS}
7863
7864 \end_inset
7865
7866
7867 \series default
7868  SDCC installs a signal handler
7869 \begin_inset LatexCommand \index{signal handler}
7870
7871 \end_inset
7872
7873  to be able to delete temporary files after an user break (^C) or an exception.
7874  If this environment variable is set, SDCC won't install the signal handler
7875  in order to be able to debug SDCC.
7876 \layout List
7877 \labelwidthstring 00.00.0000
7878
7879
7880 \series bold
7881 TMP,\SpecialChar ~
7882 TEMP,\SpecialChar ~
7883 TMPDIR
7884 \begin_inset LatexCommand \index{TMP, TEMP, TMPDIR}
7885
7886 \end_inset
7887
7888
7889 \series default
7890  Path, where temporary files will be created.
7891  The order of the variables is the search order.
7892  In a standard *nix environment these variables are not set, and there's
7893  no need to set them.
7894  On Windows it's recommended to set one of them.
7895 \layout List
7896 \labelwidthstring 00.00.0000
7897
7898
7899 \series bold
7900 SDCC_HOME
7901 \begin_inset LatexCommand \index{SDCC\_HOME}
7902
7903 \end_inset
7904
7905
7906 \series default
7907  Path, see section
7908 \begin_inset LatexCommand \ref{sub:Install-paths}
7909
7910 \end_inset
7911
7912 \SpecialChar ~
7913
7914 \begin_inset Quotes sld
7915 \end_inset
7916
7917  Install Paths
7918 \begin_inset Quotes srd
7919 \end_inset
7920
7921 .
7922 \layout List
7923 \labelwidthstring 00.00.0000
7924
7925
7926 \series bold
7927 SDCC_INCLUDE
7928 \begin_inset LatexCommand \index{SDCC\_INCLUDE}
7929
7930 \end_inset
7931
7932
7933 \series default
7934  Path, see section
7935 \begin_inset LatexCommand \ref{sub:Search-Paths}
7936
7937 \end_inset
7938
7939 \SpecialChar ~
7940
7941 \begin_inset Quotes sld
7942 \end_inset
7943
7944 Search Paths
7945 \begin_inset Quotes srd
7946 \end_inset
7947
7948 .
7949 \layout List
7950 \labelwidthstring 00.00.0000
7951
7952
7953 \series bold
7954 SDCC_LIB
7955 \begin_inset LatexCommand \index{SDCC\_LIB}
7956
7957 \end_inset
7958
7959
7960 \series default
7961  Path, see section
7962 \begin_inset LatexCommand \ref{sub:Search-Paths}
7963
7964 \end_inset
7965
7966 \SpecialChar ~
7967
7968 \begin_inset Quotes sld
7969 \end_inset
7970
7971 Search Paths
7972 \begin_inset Quotes srd
7973 \end_inset
7974
7975 ..
7976 \layout Standard
7977
7978 There are some more environment variables recognized by SDCC, but these
7979  are solely used for debugging purposes.
7980  They can change or disappear very quickly, and will never be documented.
7981 \layout Section
7982
7983 Storage Class Language Extensions
7984 \layout Subsection
7985
7986 MCS51/DS390 Storage Class
7987 \begin_inset LatexCommand \index{Storage class}
7988
7989 \end_inset
7990
7991  Language Extensions
7992 \layout Standard
7993
7994 In addition to the ANSI storage classes SDCC allows the following MCS51
7995  specific storage classes:
7996 \layout Subsubsection
7997
7998 data
7999 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8000
8001 \end_inset
8002
8003  / near
8004 \begin_inset LatexCommand \index{near (storage class)}
8005
8006 \end_inset
8007
8008
8009 \layout Standard
8010
8011 This is the
8012 \series bold
8013 default
8014 \series default
8015  storage class for the Small Memory model (
8016 \emph on
8017 data
8018 \emph default
8019  and
8020 \emph on
8021 near
8022 \emph default
8023  can be used synonymously).
8024  Variables declared with this storage class will be allocated in the directly
8025  addressable portion of the internal RAM of a 8051, e.g.:
8026 \layout Verse
8027
8028
8029 \family typewriter
8030 data unsigned char test_data;
8031 \layout Standard
8032
8033 Writing 0x01 to this variable generates the assembly code:
8034 \layout Verse
8035
8036
8037 \family typewriter
8038 75*00 01\SpecialChar ~
8039 \SpecialChar ~
8040 \SpecialChar ~
8041 mov\SpecialChar ~
8042 \SpecialChar ~
8043 _test_data,#0x01
8044 \layout Subsubsection
8045
8046 xdata
8047 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8048
8049 \end_inset
8050
8051  / far
8052 \begin_inset LatexCommand \index{far (storage class)}
8053
8054 \end_inset
8055
8056
8057 \layout Standard
8058
8059 Variables declared with this storage class will be placed in the external
8060  RAM.
8061  This is the
8062 \series bold
8063 default
8064 \series default
8065  storage class for the Large Memory model, e.g.:
8066 \layout Verse
8067
8068
8069 \family typewriter
8070 xdata unsigned char test_xdata;
8071 \layout Standard
8072
8073 Writing 0x01 to this variable generates the assembly code:
8074 \layout Verse
8075
8076
8077 \family typewriter
8078 90s00r00\SpecialChar ~
8079 \SpecialChar ~
8080 \SpecialChar ~
8081 mov\SpecialChar ~
8082 \SpecialChar ~
8083 dptr,#_test_xdata
8084 \newline
8085 74\SpecialChar ~
8086 01\SpecialChar ~
8087 \SpecialChar ~
8088 \SpecialChar ~
8089 \SpecialChar ~
8090 \SpecialChar ~
8091 \SpecialChar ~
8092 mov\SpecialChar ~
8093 \SpecialChar ~
8094 a,#0x01
8095 \newline
8096 F0\SpecialChar ~
8097 \SpecialChar ~
8098 \SpecialChar ~
8099 \SpecialChar ~
8100 \SpecialChar ~
8101 \SpecialChar ~
8102 \SpecialChar ~
8103 \SpecialChar ~
8104 \SpecialChar ~
8105 movx\SpecialChar ~
8106 @dptr,a
8107 \layout Subsubsection
8108
8109 idata
8110 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8111
8112 \end_inset
8113
8114
8115 \layout Standard
8116
8117 Variables declared with this storage class will be allocated into the indirectly
8118  addressable portion of the internal ram of a 8051, e.g.:
8119 \layout Verse
8120
8121
8122 \family typewriter
8123 idata unsigned char test_idata;
8124 \layout Standard
8125
8126 Writing 0x01 to this variable generates the assembly code:
8127 \layout Verse
8128
8129
8130 \family typewriter
8131 78r00\SpecialChar ~
8132 \SpecialChar ~
8133 \SpecialChar ~
8134 \SpecialChar ~
8135 \SpecialChar ~
8136 \SpecialChar ~
8137 \SpecialChar ~
8138 mov\SpecialChar ~
8139 \SpecialChar ~
8140 r0,#_test_idata
8141 \newline
8142 76\SpecialChar ~
8143 01\SpecialChar ~
8144 \SpecialChar ~
8145 \SpecialChar ~
8146 \SpecialChar ~
8147 \SpecialChar ~
8148 \SpecialChar ~
8149 \SpecialChar ~
8150 mov\SpecialChar ~
8151 \SpecialChar ~
8152 @r0,#0x01
8153 \layout Standard
8154
8155 Please note, the first 128 byte of idata physically access the same RAM
8156  as the data memory.
8157  The original 8051 had 128 byte idata memory, nowadays most devices have
8158  256 byte idata memory.
8159  The stack
8160 \begin_inset LatexCommand \index{stack}
8161
8162 \end_inset
8163
8164  is located in idata memory.
8165 \layout Subsubsection
8166
8167 pdata
8168 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
8169
8170 \end_inset
8171
8172
8173 \layout Standard
8174
8175 Paged xdata access is currently not as straightforward as using the other
8176  addressing modes of a 8051.
8177  The following example writes 0x01 to the address pointed to.
8178  Please note, pdata access physically accesses xdata memory.
8179  The high byte of the address is determined by port P2
8180 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
8181
8182 \end_inset
8183
8184 (or in case of some 8051 variants by a separate Special Function Register,
8185  see section
8186 \begin_inset LatexCommand \ref{sub:MCS51-variants}
8187
8188 \end_inset
8189
8190 ).
8191 \layout Verse
8192
8193
8194 \family typewriter
8195 pdata unsigned char *test_pdata_ptr;
8196 \newline
8197
8198 \newline
8199 void main()
8200 \newline
8201 {
8202 \newline
8203 \SpecialChar ~
8204 \SpecialChar ~
8205 \SpecialChar ~
8206 \SpecialChar ~
8207 test_pdata_ptr = (pdata *)0xfe;
8208 \newline
8209 \SpecialChar ~
8210 \SpecialChar ~
8211 \SpecialChar ~
8212 \SpecialChar ~
8213 *test_pdata_ptr = 1;
8214 \newline
8215 }
8216 \layout Standard
8217
8218 Generates the assembly code:
8219 \layout Verse
8220
8221
8222 \family typewriter
8223 75*01 FE\SpecialChar ~
8224 \SpecialChar ~
8225 \SpecialChar ~
8226 mov\SpecialChar ~
8227  _test_pdata_ptr,#0xFE
8228 \newline
8229 78 FE\SpecialChar ~
8230 \SpecialChar ~
8231 \SpecialChar ~
8232 \SpecialChar ~
8233 \SpecialChar ~
8234 \SpecialChar ~
8235 mov\SpecialChar ~
8236  r0,#0xFE
8237 \newline
8238 74 01\SpecialChar ~
8239 \SpecialChar ~
8240 \SpecialChar ~
8241 \SpecialChar ~
8242 \SpecialChar ~
8243 \SpecialChar ~
8244 mov\SpecialChar ~
8245  a,#0x01
8246 \newline
8247 F2\SpecialChar ~
8248 \SpecialChar ~
8249 \SpecialChar ~
8250 \SpecialChar ~
8251 \SpecialChar ~
8252 \SpecialChar ~
8253 \SpecialChar ~
8254 \SpecialChar ~
8255 \SpecialChar ~
8256 movx @r0,a
8257 \layout Standard
8258
8259 Be extremely carefull if you use pdata together with the -
8260 \begin_inset ERT
8261 status Collapsed
8262
8263 \layout Standard
8264
8265 \backslash
8266 /
8267 \end_inset
8268
8269 -xstack
8270 \begin_inset LatexCommand \index{-\/-xstack}
8271
8272 \end_inset
8273
8274  option.
8275 \layout Subsubsection
8276
8277 code
8278 \begin_inset LatexCommand \index{code}
8279
8280 \end_inset
8281
8282
8283 \layout Standard
8284
8285 'Variables' declared with this storage class will be placed in the code
8286  memory:
8287 \layout Verse
8288
8289
8290 \family typewriter
8291 code unsigned char test_code;
8292 \layout Standard
8293
8294 Read access to this variable generates the assembly code:
8295 \layout Verse
8296
8297
8298 \family typewriter
8299 90s00r6F\SpecialChar ~
8300 \SpecialChar ~
8301 \SpecialChar ~
8302 mov dptr,#_test_code
8303 \newline
8304 E4\SpecialChar ~
8305 \SpecialChar ~
8306 \SpecialChar ~
8307 \SpecialChar ~
8308 \SpecialChar ~
8309 \SpecialChar ~
8310 \SpecialChar ~
8311 \SpecialChar ~
8312 \SpecialChar ~
8313 clr a
8314 \newline
8315 93\SpecialChar ~
8316 \SpecialChar ~
8317 \SpecialChar ~
8318 \SpecialChar ~
8319 \SpecialChar ~
8320 \SpecialChar ~
8321 \SpecialChar ~
8322 \SpecialChar ~
8323 \SpecialChar ~
8324 movc a,@a+dptr
8325 \layout Standard
8326
8327
8328 \family typewriter
8329 char
8330 \family default
8331  indexed arrays of characters in code memory can be accessed efficiently:
8332 \layout Verse
8333
8334
8335 \family typewriter
8336 code char test_array[] = {'c','h','e','a','p'};
8337 \layout Standard
8338
8339 Read access to this array using an 8-bit unsigned index generates the assembly
8340  code:
8341 \layout Verse
8342
8343
8344 \family typewriter
8345 E5*00\SpecialChar ~
8346 \SpecialChar ~
8347 \SpecialChar ~
8348 \SpecialChar ~
8349 \SpecialChar ~
8350 \SpecialChar ~
8351 mov a,_index
8352 \layout Verse
8353
8354
8355 \family typewriter
8356 90s00r41\SpecialChar ~
8357 \SpecialChar ~
8358 \SpecialChar ~
8359 mov dptr,#_test_array
8360 \layout Verse
8361
8362
8363 \family typewriter
8364 93\SpecialChar ~
8365 \SpecialChar ~
8366 \SpecialChar ~
8367 \SpecialChar ~
8368 \SpecialChar ~
8369 \SpecialChar ~
8370 \SpecialChar ~
8371 \SpecialChar ~
8372 \SpecialChar ~
8373 movc a,@a+dptr
8374 \layout Subsubsection
8375
8376 bit
8377 \begin_inset LatexCommand \index{bit}
8378
8379 \end_inset
8380
8381
8382 \layout Standard
8383
8384 This is a data-type and a storage class specifier.
8385  When a variable is declared as a bit, it is allocated into the bit addressable
8386  memory of 8051, e.g.:
8387 \layout Verse
8388
8389
8390 \family typewriter
8391 bit test_bit;
8392 \layout Standard
8393
8394 Writing 1 to this variable generates the assembly code:
8395 \layout Verse
8396
8397
8398 \family typewriter
8399 D2*00\SpecialChar ~
8400 \SpecialChar ~
8401 \SpecialChar ~
8402 \SpecialChar ~
8403 \SpecialChar ~
8404 \SpecialChar ~
8405 \SpecialChar ~
8406 setb\SpecialChar ~
8407 _test_bit
8408 \layout Standard
8409
8410 The bit addressable memory consists of 128 bits which are located from 0x20
8411  to 0x2f in data memory.
8412
8413 \newline
8414 Apart from this 8051 specific storage class most architectures support ANSI-C
8415  bitfields
8416 \begin_inset LatexCommand \index{bitfields}
8417
8418 \end_inset
8419
8420
8421 \begin_inset Foot
8422 collapsed false
8423
8424 \layout Standard
8425
8426 Not really meant as examples, but nevertheless showing what bitfields are
8427  about: device/include/mc68hc908qy.h and support/regression/tests/bitfields.c
8428 \end_inset
8429
8430 .
8431  In accordance with ISO/IEC 9899 bits and bitfields without an explicit
8432  signed modifier are implemented as unsigned.
8433 \layout Subsubsection
8434
8435 sfr
8436 \begin_inset LatexCommand \index{sfr}
8437
8438 \end_inset
8439
8440  / sbit
8441 \begin_inset LatexCommand \index{sbit}
8442
8443 \end_inset
8444
8445
8446 \layout Standard
8447
8448 Like the bit keyword,
8449 \emph on
8450 sfr / sbit
8451 \emph default
8452 signifies both a data-type and storage class, they are used to describe
8453  the
8454 \emph on
8455 s
8456 \emph default
8457 pecial
8458 \emph on
8459 f
8460 \emph default
8461 unction
8462 \emph on
8463 r
8464 \emph default
8465 egisters and
8466 \emph on
8467 s
8468 \emph default
8469 pecial
8470 \emph on
8471 bit
8472 \emph default
8473  variables of a 8051, eg:
8474 \layout Verse
8475
8476
8477 \family typewriter
8478 sfr at
8479 \begin_inset LatexCommand \index{at}
8480
8481 \end_inset
8482
8483  0x80 P0;\SpecialChar ~
8484  /* special function register P0 at location 0x80 */
8485 \newline
8486 sbit at 0xd7 CY; /* CY (Carry Flag
8487 \begin_inset LatexCommand \index{Flags}
8488
8489 \end_inset
8490
8491
8492 \begin_inset LatexCommand \index{Carry flag}
8493
8494 \end_inset
8495
8496 ) */
8497 \layout Standard
8498
8499 Special function registers which are located on an address dividable by
8500  8 are bit-addressable, an
8501 \emph on
8502  sbit
8503 \emph default
8504  addresses a specific bit within these sfr.
8505 \layout Subsubsection
8506
8507 Pointers
8508 \begin_inset LatexCommand \index{Pointer}
8509
8510 \end_inset
8511
8512  to MCS51/DS390 specific memory spaces
8513 \layout Standard
8514
8515 SDCC allows (via language extensions) pointers to explicitly point to any
8516  of the memory spaces
8517 \begin_inset LatexCommand \index{Memory model}
8518
8519 \end_inset
8520
8521  of the 8051.
8522  In addition to the explicit pointers, the compiler uses (by default) generic
8523  pointers which can be used to point to any of the memory spaces.
8524 \newline
8525
8526 \newline
8527 Pointer declaration examples:
8528 \layout Verse
8529
8530
8531 \family typewriter
8532 /* pointer physically in internal ram pointing to object in external ram
8533  */
8534 \newline
8535 xdata unsigned char * data p;
8536 \newline
8537
8538 \newline
8539 /* pointer physically in external ram pointing to object in internal ram
8540  */
8541 \newline
8542 data unsigned char * xdata p;
8543 \newline
8544
8545 \newline
8546 /* pointer physically in code rom pointing to data in xdata space */
8547 \newline
8548 xdata unsigned char * code p;
8549 \newline
8550
8551 \newline
8552 /* pointer physically in code space pointing to data in code space */
8553 \newline
8554 code unsigned char * code p;
8555 \newline
8556
8557 \newline
8558 /* the following is a generic pointer physically located in xdata space
8559  */
8560 \newline
8561 char * xdata p;
8562 \layout Standard
8563
8564 Well you get the idea.
8565
8566 \newline
8567
8568 \newline
8569 All unqualified pointers are treated as 3-byte (4-byte for the ds390)
8570 \emph on
8571 generic
8572 \emph default
8573  pointers.
8574
8575 \size small
8576
8577 \newline
8578
8579 \newline
8580
8581 \size default
8582 The highest order byte of the
8583 \emph on
8584 generic
8585 \emph default
8586  pointers contains the data space information.
8587  Assembler support routines are called whenever data is stored or retrieved
8588  using
8589 \emph on
8590 generic
8591 \emph default
8592  pointers.
8593  These are useful for developing reusable library
8594 \begin_inset LatexCommand \index{Libraries}
8595
8596 \end_inset
8597
8598  routines.
8599  Explicitly specifying the pointer type will generate the most efficient
8600  code.
8601 \layout Subsubsection
8602
8603 Notes on MCS51 memory
8604 \begin_inset LatexCommand \index{MCS51 memory}
8605
8606 \end_inset
8607
8608  layout
8609 \layout Standard
8610
8611 The 8051 family of microcontrollers have a minimum of 128 bytes of internal
8612  RAM memory which is structured as follows:
8613 \newline
8614
8615 \newline
8616 - Bytes 00-1F - 32 bytes to hold up to 4 banks of the registers R0 to R7,
8617
8618 \newline
8619 - Bytes 20-2F - 16 bytes to hold 128 bit
8620 \begin_inset LatexCommand \index{bit}
8621
8622 \end_inset
8623
8624  variables and,
8625 \newline
8626 - Bytes 30-7F - 80 bytes for general purpose use.
8627 \newline
8628
8629 \layout Standard
8630
8631 Additionally some members of the MCS51 family may have up to 128 bytes of
8632  additional, indirectly addressable, internal RAM memory (
8633 \emph on
8634 idata
8635 \emph default
8636
8637 \begin_inset LatexCommand \index{idata (mcs51, ds390 storage class)}
8638
8639 \end_inset
8640
8641 ).
8642  Furthermore, some chips may have some built in external memory (
8643 \emph on
8644 xdata
8645 \emph default
8646
8647 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
8648
8649 \end_inset
8650
8651 ) which should not be confused with the internal, directly addressable RAM
8652  memory (
8653 \emph on
8654 data
8655 \emph default
8656
8657 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
8658
8659 \end_inset
8660
8661 ).
8662  Sometimes this built in
8663 \emph on
8664 xdata
8665 \emph default
8666  memory has to be activated before using it (you can probably find this
8667  information on the datasheet of the microcontroller your are using, see
8668  also section
8669 \begin_inset LatexCommand \ref{sub:Startup-Code}
8670
8671 \end_inset
8672
8673 \SpecialChar ~
8674 Startup-Code).
8675 \layout Standard
8676
8677 Normally SDCC will only use the first bank
8678 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
8679
8680 \end_inset
8681
8682  of registers (register bank 0), but it is possible to specify that other
8683  banks of registers should be used in interrupt
8684 \begin_inset LatexCommand \index{interrupt}
8685
8686 \end_inset
8687
8688  routines.
8689  By default, the compiler will place the stack after the last byte of allocated
8690  memory for variables.
8691  For example, if the first 2 banks of registers are used, and only four
8692  bytes are used for
8693 \emph on
8694 data
8695 \emph default
8696  variables, it will position the base of the internal stack at address 20
8697  (0x14).
8698  This implies that as the stack
8699 \begin_inset LatexCommand \index{stack}
8700
8701 \end_inset
8702
8703  grows, it will use up the remaining register banks, and the 16 bytes used
8704  by the 128 bit variables, and 80 bytes for general purpose use.
8705  If any bit variables are used, the data variables will be placed after
8706  the byte holding the last bit variable.
8707  For example, if register banks 0 and 1 are used, and there are 9 bit variables
8708  (two bytes used),
8709 \emph on
8710 data
8711 \emph default
8712  variables will be placed starting at address 0x22.
8713  You can also use -
8714 \begin_inset ERT
8715 status Collapsed
8716
8717 \layout Standard
8718
8719 \backslash
8720 /
8721 \end_inset
8722
8723 -data-loc
8724 \begin_inset LatexCommand \index{-\/-data-loc<Value>}
8725
8726 \end_inset
8727
8728  to specify the start address of the
8729 \emph on
8730 data
8731 \emph default
8732  and -
8733 \begin_inset ERT
8734 status Collapsed
8735
8736 \layout Standard
8737
8738 \backslash
8739 /
8740 \end_inset
8741
8742 -iram-size to specify the size of the total internal RAM (
8743 \emph on
8744 data
8745 \emph default
8746 +
8747 \emph on
8748 idata
8749 \emph default
8750 ).
8751
8752 \layout Standard
8753
8754 By default the 8051 linker will place the stack after the last byte of data
8755  variables.
8756  Option -
8757 \begin_inset ERT
8758 status Collapsed
8759
8760 \layout Standard
8761
8762 \backslash
8763 /
8764 \end_inset
8765
8766 -stack-loc
8767 \begin_inset LatexCommand \index{-\/-stack-loc<Value>}
8768
8769 \end_inset
8770
8771  allows you to specify the start of the stack, i.e.
8772  you could start it after any data in the general purpose area.
8773  If your microcontroller has additional indirectly addressable internal
8774  RAM (
8775 \emph on
8776 idata
8777 \emph default
8778 ) you can place the stack on it.
8779  You may also need to use -
8780 \begin_inset ERT
8781 status Collapsed
8782
8783 \layout Standard
8784
8785 \backslash
8786 /
8787 \end_inset
8788
8789 -xdata-loc
8790 \begin_inset LatexCommand \index{-\/-xdata-loc<Value>}
8791
8792 \end_inset
8793
8794  to set the start address of the external RAM (
8795 \emph on
8796 xdata
8797 \emph default
8798 ) and -
8799 \begin_inset ERT
8800 status Collapsed
8801
8802 \layout Standard
8803
8804 \backslash
8805 /
8806 \end_inset
8807
8808 -xram-size
8809 \begin_inset LatexCommand \index{-\/-data-loc}
8810
8811 \end_inset
8812
8813  to specify its size.
8814  Same goes for the code memory, using -
8815 \begin_inset ERT
8816 status Collapsed
8817
8818 \layout Standard
8819
8820 \backslash
8821 /
8822 \end_inset
8823
8824 -code-loc
8825 \begin_inset LatexCommand \index{-\/-data-loc}
8826
8827 \end_inset
8828
8829  and -
8830 \begin_inset ERT
8831 status Collapsed
8832
8833 \layout Standard
8834
8835 \backslash
8836 /
8837 \end_inset
8838
8839 -code-size
8840 \begin_inset LatexCommand \index{-\/-data-loc}
8841
8842 \end_inset
8843
8844 .
8845  If in doubt, don't specify any options and see if the resulting memory
8846  layout is appropriate, then you can adjust it.
8847 \layout Standard
8848
8849 The linker generates two files with memory allocation information.
8850  The first, with extension .map
8851 \begin_inset LatexCommand \index{<file>.map}
8852
8853 \end_inset
8854
8855  shows all the variables and segments.
8856  The second with extension .mem
8857 \begin_inset LatexCommand \index{<file>.mem}
8858
8859 \end_inset
8860
8861  shows the final memory layout.
8862  The linker will complain either if memory segments overlap, there is not
8863  enough memory, or there is not enough space for stack.
8864  If you get any linking warnings and/or errors related to stack or segments
8865  allocation, take a look at either the .map or .mem files to find out what
8866  the problem is.
8867  The .mem file may even suggest a solution to the problem.
8868 \layout Subsection
8869
8870 Z80/Z180 Storage Class
8871 \begin_inset LatexCommand \index{Storage class}
8872
8873 \end_inset
8874
8875  Language Extensions
8876 \layout Subsubsection
8877
8878 sfr
8879 \begin_inset LatexCommand \index{sfr}
8880
8881 \end_inset
8882
8883  (in/out to 8-bit addresses)
8884 \layout Standard
8885
8886 The Z80
8887 \begin_inset LatexCommand \index{Z80}
8888
8889 \end_inset
8890
8891  family has separate address spaces for memory and
8892 \emph on
8893 i
8894 \emph default
8895 nput/
8896 \emph on
8897 o
8898 \emph default
8899 utput memory.
8900  I/O memory
8901 \begin_inset LatexCommand \index{I/O memory (Z80, Z180)}
8902
8903 \end_inset
8904
8905  is accessed with special instructions, e.g.:
8906 \layout Verse
8907
8908
8909 \family typewriter
8910 sfr at 0x78 IoPort;\SpecialChar ~
8911 \SpecialChar ~
8912 /* define a var in I/O space at 78h called IoPort */
8913
8914 \layout Standard
8915
8916 Writing 0x01 to this variable generates the assembly code:
8917 \layout Verse
8918
8919
8920 \family typewriter
8921 3E 01\SpecialChar ~
8922 \SpecialChar ~
8923 \SpecialChar ~
8924 \SpecialChar ~
8925 \SpecialChar ~
8926 \SpecialChar ~
8927 ld a,#0x01
8928 \newline
8929 D3 78\SpecialChar ~
8930 \SpecialChar ~
8931 \SpecialChar ~
8932 \SpecialChar ~
8933 \SpecialChar ~
8934 \SpecialChar ~
8935 out (_IoPort),a
8936 \layout Subsubsection
8937
8938 banked sfr
8939 \begin_inset LatexCommand \index{sfr}
8940
8941 \end_inset
8942
8943  (in/out to 16-bit addresses)
8944 \layout Standard
8945
8946 The keyword
8947 \emph on
8948 banked
8949 \emph default
8950  is used to support 16 bit addresses in I/O memory e.g.:
8951 \layout Verse
8952
8953
8954 \family typewriter
8955 sfr banked at
8956 \begin_inset LatexCommand \index{at}
8957
8958 \end_inset
8959
8960  0x123 IoPort;
8961 \layout Standard
8962
8963 Writing 0x01 to this variable generates the assembly code:
8964 \layout Verse
8965
8966
8967 \family typewriter
8968 01 23 01\SpecialChar ~
8969 \SpecialChar ~
8970 \SpecialChar ~
8971 ld bc,#_IoPort
8972 \newline
8973 3E 01\SpecialChar ~
8974 \SpecialChar ~
8975 \SpecialChar ~
8976 \SpecialChar ~
8977 \SpecialChar ~
8978 \SpecialChar ~
8979 ld a,#0x01
8980 \newline
8981 ED 79\SpecialChar ~
8982 \SpecialChar ~
8983 \SpecialChar ~
8984 \SpecialChar ~
8985 \SpecialChar ~
8986 \SpecialChar ~
8987 out (c),a
8988 \layout Subsubsection
8989
8990 sfr
8991 \begin_inset LatexCommand \index{sfr}
8992
8993 \end_inset
8994
8995  (in0/out0 to 8 bit addresses on Z180
8996 \begin_inset LatexCommand \index{Z180}
8997
8998 \end_inset
8999
9000 /HD64180
9001 \begin_inset LatexCommand \index{HD64180}
9002
9003 \end_inset
9004
9005 )
9006 \layout Standard
9007
9008 The compiler option -
9009 \begin_inset ERT
9010 status Collapsed
9011
9012 \layout Standard
9013
9014 \backslash
9015 /
9016 \end_inset
9017
9018 -portmode=180 (80) and a compiler #pragma\SpecialChar ~
9019 portmode
9020 \begin_inset LatexCommand \index{\#pragma portmode}
9021
9022 \end_inset
9023
9024 =z180 (z80) is used to turn on (off) the Z180/HD64180 port addressing instructio
9025 ns
9026 \family typewriter
9027 in0/out0
9028 \family default
9029  instead of
9030 \family typewriter
9031 in/out
9032 \family default
9033 .
9034  If you include the file z180.h this will be set automatically.
9035 \layout Subsection
9036
9037 HC08 Storage Class
9038 \begin_inset LatexCommand \index{Storage class}
9039
9040 \end_inset
9041
9042  Language Extensions
9043 \layout Subsubsection
9044
9045 data
9046 \begin_inset LatexCommand \index{data (mcs51, ds390 storage class)}
9047
9048 \end_inset
9049
9050
9051 \layout Standard
9052
9053 The data storage class declares a variable that resides in the first 256
9054  bytes of memory (the direct page).
9055  The HC08 is most efficient at accessing variables (especially pointers)
9056  stored here.
9057 \layout Subsubsection
9058
9059 xdata
9060 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9061
9062 \end_inset
9063
9064
9065 \layout Standard
9066
9067 The xdata storage class declares a variable that can reside anywhere in
9068  memory.
9069  This is the default if no storage class is specified.
9070
9071 \layout Section
9072
9073 Absolute Addressing
9074 \begin_inset LatexCommand \index{Absolute addressing}
9075
9076 \end_inset
9077
9078
9079 \layout Standard
9080
9081 Data items can be assigned an absolute address with the
9082 \emph on
9083 at
9084 \begin_inset LatexCommand \index{at}
9085
9086 \end_inset
9087
9088  <address>
9089 \emph default
9090  keyword, in addition to a storage class, e.g.:
9091 \layout Verse
9092
9093
9094 \family typewriter
9095 xdata
9096 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9097
9098 \end_inset
9099
9100  at
9101 \begin_inset LatexCommand \index{at}
9102
9103 \end_inset
9104
9105  0x7ffe unsigned int chksum;
9106 \layout Standard
9107
9108 In the above example the variable chksum will be located at 0x7ffe and 0x7fff
9109  of the external ram.
9110  The compiler does
9111 \emph on
9112 not
9113 \emph default
9114  reserve any space for variables declared in this way (they are implemented
9115  with an equate in the assembler).
9116  Thus it is left to the programmer to make sure there are no overlaps with
9117  other variables that are declared without the absolute address.
9118  The assembler listing file (.lst
9119 \begin_inset LatexCommand \index{<file>.lst}
9120
9121 \end_inset
9122
9123 ) and the linker output files (.rst
9124 \begin_inset LatexCommand \index{<file>.rst}
9125
9126 \end_inset
9127
9128 ) and (.map
9129 \begin_inset LatexCommand \index{<file>.map}
9130
9131 \end_inset
9132
9133 ) are good places to look for such overlaps.
9134  Variables with an absolute address are
9135 \emph on
9136 not
9137 \emph default
9138  initialized
9139 \begin_inset LatexCommand \index{Variable initialization}
9140
9141 \end_inset
9142
9143 .
9144 \layout Standard
9145
9146 In case of memory mapped I/O devices the keyword
9147 \emph on
9148 volatile
9149 \emph default
9150  has to be used to tell the compiler that accesses might not be removed:
9151 \layout Verse
9152
9153
9154 \family typewriter
9155 volatile
9156 \begin_inset LatexCommand \index{volatile}
9157
9158 \end_inset
9159
9160  xdata
9161 \begin_inset LatexCommand \index{xdata (mcs51, ds390 storage class)}
9162
9163 \end_inset
9164
9165  at
9166 \begin_inset LatexCommand \index{at}
9167
9168 \end_inset
9169
9170  0x8000 unsigned char PORTA_8255;
9171 \layout Standard
9172
9173 For some architectures (mcs51) array accesses are more efficient if an (xdata/fa
9174 r) array
9175 \family typewriter
9176 \size footnotesize
9177
9178 \begin_inset LatexCommand \index{Aligned array}
9179
9180 \end_inset
9181
9182
9183 \family default
9184 \size default
9185  starts at a block (256 byte) boundary
9186 \begin_inset LatexCommand \index{block boundary}
9187
9188 \end_inset
9189
9190  (section
9191 \begin_inset LatexCommand \ref{sub:A-Step-by Assembler Introduction}
9192
9193 \end_inset
9194
9195  has an example).
9196 \newline
9197 Absolute addresses can be specified for variables in all storage classes,
9198  e.g.:
9199 \layout Verse
9200
9201
9202 \family typewriter
9203 bit
9204 \begin_inset LatexCommand \index{bit}
9205
9206 \end_inset
9207
9208  at
9209 \begin_inset LatexCommand \index{at}
9210
9211 \end_inset
9212
9213  0x02 bvar;
9214 \layout Standard
9215
9216 The above example will allocate the variable at offset 0x02 in the bit-addressab
9217 le space.
9218  There is no real advantage to assigning absolute addresses to variables
9219  in this manner, unless you want strict control over all the variables allocated.
9220  One possible use would be to write hardware portable code.
9221  For example, if you have a routine that uses one or more of the microcontroller
9222  I/O pins, and such pins are different for two different hardwares, you
9223  can declare the I/O pins in your routine using:
9224 \layout Verse
9225
9226
9227 \family typewriter
9228 extern volatile bit MOSI;\SpecialChar ~
9229 \SpecialChar ~
9230 \SpecialChar ~
9231 \SpecialChar ~
9232 /* master out, slave in */
9233 \newline
9234 extern volatile bit MISO;\SpecialChar ~
9235 \SpecialChar ~
9236 \SpecialChar ~
9237 \SpecialChar ~
9238 /* master in, slave out */
9239 \newline
9240 extern volatile bit MCLK;\SpecialChar ~
9241 \SpecialChar ~
9242 \SpecialChar ~
9243 \SpecialChar ~
9244 /* master clock */
9245 \newline
9246
9247 \newline
9248 /* Input and Output of a byte on a 3-wire serial bus.
9249 \newline
9250 \SpecialChar ~
9251 \SpecialChar ~
9252 \SpecialChar ~
9253 If needed adapt polarity of clock, polarity of data and bit order
9254 \newline
9255 \SpecialChar ~
9256 */
9257 \newline
9258 unsigned char spi_io(unsigned char out_byte)
9259 \newline
9260 {
9261 \newline
9262 \SpecialChar ~
9263 \SpecialChar ~
9264 \SpecialChar ~
9265 \SpecialChar ~
9266 unsigned char i=8;
9267 \newline
9268 \SpecialChar ~
9269 \SpecialChar ~
9270 \SpecialChar ~
9271 \SpecialChar ~
9272 do {
9273 \newline
9274 \SpecialChar ~
9275 \SpecialChar ~
9276 \SpecialChar ~
9277 \SpecialChar ~
9278 \SpecialChar ~
9279 \SpecialChar ~
9280 \SpecialChar ~
9281 \SpecialChar ~
9282 MOSI = out_byte & 0x80;
9283 \newline
9284 \SpecialChar ~
9285 \SpecialChar ~
9286 \SpecialChar ~
9287 \SpecialChar ~
9288 \SpecialChar ~
9289 \SpecialChar ~
9290 \SpecialChar ~
9291 \SpecialChar ~
9292 out_byte <<= 1;
9293 \newline
9294 \SpecialChar ~
9295 \SpecialChar ~
9296 \SpecialChar ~
9297 \SpecialChar ~
9298 \SpecialChar ~
9299 \SpecialChar ~
9300 \SpecialChar ~
9301 \SpecialChar ~
9302 MCLK = 1;
9303 \newline
9304 \SpecialChar ~
9305 \SpecialChar ~
9306 \SpecialChar ~
9307 \SpecialChar ~
9308 \SpecialChar ~
9309 \SpecialChar ~
9310 \SpecialChar ~
9311 \SpecialChar ~
9312 /* _asm nop _endasm; */\SpecialChar ~
9313 \SpecialChar ~
9314 \SpecialChar ~
9315 \SpecialChar ~
9316 \SpecialChar ~
9317 \SpecialChar ~
9318 \SpecialChar ~
9319 \SpecialChar ~
9320 /* for slow peripherals */
9321 \newline
9322 \SpecialChar ~
9323 \SpecialChar ~
9324 \SpecialChar ~
9325 \SpecialChar ~
9326 \SpecialChar ~
9327 \SpecialChar ~
9328 \SpecialChar ~
9329 \SpecialChar ~
9330 if(MISO)
9331 \newline
9332 \SpecialChar ~
9333 \SpecialChar ~
9334 \SpecialChar ~
9335 \SpecialChar ~
9336 \SpecialChar ~
9337 \SpecialChar ~
9338 \SpecialChar ~
9339 \SpecialChar ~
9340 \SpecialChar ~
9341 \SpecialChar ~
9342 \SpecialChar ~
9343 \SpecialChar ~
9344 out_byte += 1;
9345 \newline
9346 \SpecialChar ~
9347 \SpecialChar ~
9348 \SpecialChar ~
9349 \SpecialChar ~
9350 \SpecialChar ~
9351 \SpecialChar ~
9352 \SpecialChar ~
9353 \SpecialChar ~
9354 MCLK = 0;
9355 \newline
9356 \SpecialChar ~
9357 \SpecialChar ~
9358 \SpecialChar ~
9359 \SpecialChar ~
9360 } while(--i);
9361 \newline
9362 \SpecialChar ~
9363 \SpecialChar ~
9364 \SpecialChar ~
9365 \SpecialChar ~
9366 return out_byte;
9367 \newline
9368 }
9369 \layout Standard
9370
9371 Then, someplace in the code for the first hardware you would use
9372 \layout Verse
9373
9374
9375 \family typewriter
9376 bit at 0x80 MOSI;\SpecialChar ~
9377 \SpecialChar ~
9378 \SpecialChar ~
9379 \SpecialChar ~
9380 /* I/O port 0, bit 0 */
9381 \newline
9382 bit at 0x81 MISO;\SpecialChar ~
9383 \SpecialChar ~
9384 \SpecialChar ~
9385 \SpecialChar ~
9386 /* I/O port 0, bit 1 */
9387 \newline
9388 bit at 0x82 MCLK;\SpecialChar ~
9389 \SpecialChar ~
9390 \SpecialChar ~
9391 \SpecialChar ~
9392 /* I/O port 0, bit 2 */
9393 \layout Standard
9394
9395 Similarly, for the second hardware you would use
9396 \layout Verse
9397
9398
9399 \family typewriter
9400 bit at 0x83 MOSI;\SpecialChar ~
9401 \SpecialChar ~
9402 \SpecialChar ~
9403 \SpecialChar ~
9404 /* I/O port 0, bit 3 */
9405 \newline
9406 bit at 0x91 MISO;\SpecialChar ~
9407 \SpecialChar ~
9408 \SpecialChar ~
9409 \SpecialChar ~
9410 /* I/O port 1, bit 1 */
9411 \newline
9412 bit
9413 \begin_inset LatexCommand \index{bit}
9414
9415 \end_inset
9416
9417  at 0x92 MCLK;\SpecialChar ~
9418 \SpecialChar ~
9419 \SpecialChar ~
9420 \SpecialChar ~
9421 /* I/O port 1, bit 2 */
9422 \layout Standard
9423
9424 and you can use the same hardware dependent routine without changes, as
9425  for example in a library.
9426  This is somehow similar to sbit, but only one absolute address has to be
9427  specified in the whole project.
9428 \layout Section
9429
9430 Parameters
9431 \begin_inset LatexCommand \index{Parameters}
9432
9433 \end_inset
9434
9435
9436 \begin_inset LatexCommand \index{function parameter}
9437
9438 \end_inset
9439
9440  & Local Variables
9441 \begin_inset LatexCommand \index{local variables}
9442
9443 \end_inset
9444
9445
9446 \begin_inset LatexCommand \label{sec:Parameters-and-Local-Variables}
9447
9448 \end_inset
9449
9450
9451 \layout Standard
9452
9453 Automatic (local) variables and parameters to functions can either be placed
9454  on the stack or in data-space.
9455  The default action of the compiler is to place these variables in the internal
9456  RAM (for small model) or external RAM (for large model).
9457  This in fact makes them similar to
9458 \emph on
9459 static
9460 \begin_inset LatexCommand \index{static}
9461
9462 \end_inset
9463
9464
9465 \emph default
9466  so by default functions are non-reentrant
9467 \begin_inset LatexCommand \index{reentrant}
9468
9469 \end_inset
9470
9471 .
9472
9473 \newline
9474
9475 \newline
9476 They can be placed on the stack
9477 \begin_inset LatexCommand \index{stack}
9478
9479 \end_inset
9480
9481  by using the
9482 \emph on
9483  -
9484 \begin_inset ERT
9485 status Collapsed
9486
9487 \layout Standard
9488
9489 \backslash
9490 /
9491 \end_inset
9492
9493 -stack-auto
9494 \begin_inset LatexCommand \index{-\/-stack-auto}
9495
9496 \end_inset
9497
9498
9499 \emph default
9500  option, by using
9501 \emph on
9502 #pragma\SpecialChar ~
9503 stackauto
9504 \emph default
9505
9506 \begin_inset LatexCommand \index{\#pragma stackauto}
9507
9508 \end_inset
9509
9510  or by using the
9511 \emph on
9512 reentrant
9513 \begin_inset LatexCommand \index{reentrant}
9514
9515 \end_inset
9516
9517
9518 \emph default
9519  keyword in the function declaration, e.g.:
9520 \layout Verse
9521
9522
9523 \family typewriter
9524 unsigned char foo(char i) reentrant
9525 \newline
9526 {
9527 \newline
9528 \SpecialChar ~
9529 \SpecialChar ~
9530 \SpecialChar ~
9531 \SpecialChar ~
9532 ...
9533
9534 \newline
9535 }
9536 \layout Standard
9537
9538 Since stack space on 8051 is limited, the
9539 \emph on
9540 reentrant
9541 \emph default
9542 keyword or the
9543 \emph on
9544  -
9545 \begin_inset ERT
9546 status Collapsed
9547
9548 \layout Standard
9549
9550 \backslash
9551 /
9552 \end_inset
9553
9554 -stack-auto
9555 \emph default
9556  option should be used sparingly.
9557  Note that the reentrant keyword just means that the parameters & local
9558  variables will be allocated to the stack, it
9559 \emph on
9560 does not
9561 \emph default
9562  mean that the function is register bank
9563 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
9564
9565 \end_inset
9566
9567  independent.
9568 \newline
9569
9570 \newline
9571 Local variables
9572 \begin_inset LatexCommand \index{local variables}
9573
9574 \end_inset
9575
9576  can be assigned storage classes and absolute
9577 \begin_inset LatexCommand \index{Absolute addressing}
9578
9579 \end_inset
9580
9581  addresses, e.g.:
9582 \layout Verse
9583
9584
9585 \family typewriter
9586 unsigned char foo()
9587 \newline
9588 {
9589 \newline
9590 \SpecialChar ~
9591 \SpecialChar ~
9592 \SpecialChar ~
9593 \SpecialChar ~
9594 xdata unsigned char i;
9595 \newline
9596 \SpecialChar ~
9597 \SpecialChar ~
9598 \SpecialChar ~
9599 \SpecialChar ~
9600 bit bvar;
9601 \newline
9602 \SpecialChar ~
9603 \SpecialChar ~
9604 \SpecialChar ~
9605 \SpecialChar ~
9606 data at
9607 \begin_inset LatexCommand \index{at}
9608
9609 \end_inset
9610
9611  0x31 unsigned char j;
9612 \newline
9613 \SpecialChar ~
9614 \SpecialChar ~
9615 \SpecialChar ~
9616 \SpecialChar ~
9617 ...
9618
9619 \newline
9620 }
9621 \layout Standard
9622
9623 In the above example the variable
9624 \emph on
9625 i
9626 \emph default
9627  will be allocated in the external ram,
9628 \emph on
9629 bvar
9630 \emph default
9631  in bit addressable space and
9632 \emph on
9633  j
9634 \emph default
9635  in internal ram.
9636  When compiled with
9637 \emph on
9638 -
9639 \begin_inset ERT
9640 status Collapsed
9641
9642 \layout Standard
9643
9644 \backslash
9645 /
9646 \end_inset
9647
9648 -stack-auto
9649 \emph default
9650  or when a function is declared as
9651 \emph on
9652 reentrant
9653 \emph default
9654  this should only be done for static variables.
9655 \layout Standard
9656
9657 Parameters
9658 \begin_inset LatexCommand \index{function parameter}
9659
9660 \end_inset
9661
9662  however are not allowed any storage class
9663 \begin_inset LatexCommand \index{Storage class}
9664
9665 \end_inset
9666
9667 , (storage classes for parameters will be ignored), their allocation is
9668  governed by the memory model in use, and the reentrancy options.
9669 \layout Section
9670
9671 Overlaying
9672 \begin_inset LatexCommand \label{sub:Overlaying}
9673
9674 \end_inset
9675
9676
9677 \begin_inset LatexCommand \index{Overlaying}
9678
9679 \end_inset
9680
9681
9682 \layout Standard
9683
9684 For non-reentrant
9685 \begin_inset LatexCommand \index{reentrant}
9686
9687 \end_inset
9688
9689  functions SDCC will try to reduce internal ram space usage by overlaying
9690  parameters and local variables of a function (if possible).
9691  Parameters and local variables
9692 \begin_inset LatexCommand \index{local variables}
9693
9694 \end_inset
9695
9696  of a function will be allocated to an overlayable segment if the function
9697  has
9698 \emph on
9699 no other function calls and the function is non-reentrant and the memory
9700  model
9701 \begin_inset LatexCommand \index{Memory model}
9702
9703 \end_inset
9704
9705  is small.
9706
9707 \emph default
9708  If an explicit storage class
9709 \begin_inset LatexCommand \index{Storage class}
9710
9711 \end_inset
9712
9713  is specified for a local variable, it will NOT be overlayed.
9714 \layout Standard
9715
9716 Note that the compiler (not the linkage editor) makes the decision for overlayin
9717 g the data items.
9718  Functions that are called from an interrupt service routine should be preceded
9719  by a #pragma\SpecialChar ~
9720 nooverlay
9721 \begin_inset LatexCommand \index{\#pragma nooverlay}
9722
9723 \end_inset
9724
9725  if they are not reentrant.
9726 \layout Standard
9727
9728 Also note that the compiler does not do any processing of inline assembler
9729  code, so the compiler might incorrectly assign local variables and parameters
9730  of a function into the overlay segment if the inline assembler code calls
9731  other c-functions that might use the overlay.
9732  In that case the #pragma\SpecialChar ~
9733 nooverlay should be used.
9734 \layout Standard
9735
9736 Parameters and local variables of functions that contain 16 or 32 bit multiplica
9737 tion
9738 \begin_inset LatexCommand \index{Multiplication}
9739
9740 \end_inset
9741
9742  or division
9743 \begin_inset LatexCommand \index{Division}
9744
9745 \end_inset
9746
9747  will NOT be overlayed since these are implemented using external functions,
9748  e.g.:
9749 \layout Verse
9750
9751
9752 \family typewriter
9753 #pragma save
9754 \newline
9755 #pragma nooverlay
9756 \begin_inset LatexCommand \index{\#pragma nooverlay}
9757
9758 \end_inset
9759
9760
9761 \newline
9762 void set_error(unsigned char errcd)
9763 \newline
9764 {
9765 \newline
9766 \SpecialChar ~
9767 \SpecialChar ~
9768 \SpecialChar ~
9769 \SpecialChar ~
9770 P3 = errcd;
9771 \newline
9772 }
9773 \newline
9774 #pragma restore
9775 \newline
9776
9777 \newline
9778 void some_isr () interrupt
9779 \begin_inset LatexCommand \index{interrupt}
9780
9781 \end_inset
9782
9783  2
9784 \newline
9785 {
9786 \newline
9787 \SpecialChar ~
9788 \SpecialChar ~
9789 \SpecialChar ~
9790 \SpecialChar ~
9791 ...
9792 \newline
9793 \SpecialChar ~
9794 \SpecialChar ~
9795 \SpecialChar ~
9796 \SpecialChar ~
9797 set_error(10);
9798 \newline
9799 \SpecialChar ~
9800 \SpecialChar ~
9801 \SpecialChar ~
9802 \SpecialChar ~
9803 ...
9804
9805 \newline
9806 }
9807 \layout Standard
9808
9809 In the above example the parameter
9810 \emph on
9811 errcd
9812 \emph default
9813  for the function
9814 \emph on
9815 set_error
9816 \emph default
9817  would be assigned to the overlayable segment if the #pragma\SpecialChar ~
9818 nooverlay was
9819  not present, this could cause unpredictable runtime behavior when called
9820  from an interrupt service routine.
9821  The #pragma\SpecialChar ~
9822 nooverlay ensures that the parameters and local variables for
9823  the function are NOT overlayed.
9824 \layout Section
9825
9826 Interrupt Service Routines
9827 \begin_inset LatexCommand \label{sub:Interrupt-Service-Routines}
9828
9829 \end_inset
9830
9831
9832 \layout Subsection
9833
9834 General Information
9835 \layout Standard
9836
9837 SDCC allows
9838 \emph on
9839 i
9840 \emph default
9841 nterrupt
9842 \emph on
9843 s
9844 \emph default
9845 ervice
9846 \emph on
9847 r
9848 \emph default
9849 outines to be coded in C, with some extended keywords.
9850 \layout Verse
9851
9852
9853 \family typewriter
9854 void timer_isr (void) interrupt 1 using 1
9855 \newline
9856 {
9857 \newline
9858 \SpecialChar ~
9859 \SpecialChar ~
9860 \SpecialChar ~
9861 \SpecialChar ~
9862 ...
9863
9864 \newline
9865 }
9866 \layout Standard
9867
9868 The optional number following the
9869 \emph on
9870 interrupt
9871 \begin_inset LatexCommand \index{interrupt}
9872
9873 \end_inset
9874
9875
9876 \emph default
9877  keyword is the interrupt number this routine will service.
9878  When present, the compiler will insert a call to this routine in the interrupt
9879  vector table for the interrupt number specified.
9880  If you have multiple source files in your project, interrupt service routines
9881  can be present in any of them, but a prototype of the isr MUST be present
9882  or included in the file that contains the function
9883 \emph on
9884 main
9885 \emph default
9886 .
9887  The
9888 \emph on
9889 using
9890 \emph default
9891  keyword can be used to tell the compiler to use the specified register
9892  bank (8051 specific) when generating code for this function.
9893
9894 \newline
9895
9896 \layout Standard
9897
9898 Interrupt service routines open the door for some very interesting bugs:
9899 \newline
9900 If an interrupt service routine changes variables which are accessed by
9901  other functions these variables have to be declared
9902 \emph on
9903 volatile
9904 \emph default
9905
9906 \begin_inset LatexCommand \index{volatile}
9907
9908 \end_inset
9909
9910 .
9911
9912 \layout Standard
9913
9914 If the access to these variables is not
9915 \emph on
9916 atomic
9917 \begin_inset LatexCommand \index{atomic}
9918
9919 \end_inset
9920
9921
9922 \emph default
9923  (i.e.
9924  the processor needs more than one instruction for the access and could
9925  be interrupted while accessing the variable) the interrupt must be disabled
9926  during the access to avoid inconsistent data.
9927  Access to 16 or 32 bit variables is obviously not atomic on 8 bit CPUs
9928  and should be protected by disabling interrupts.
9929  You're not automatically on the safe side if you use 8 bit variables though.
9930  We need an example here: f.e.
9931  on the 8051 the harmless looking
9932 \begin_inset Quotes srd
9933 \end_inset
9934
9935
9936 \family typewriter
9937 flags\SpecialChar ~
9938 |=\SpecialChar ~
9939 0x80;
9940 \family default
9941
9942 \begin_inset Quotes sld
9943 \end_inset
9944
9945  is not atomic if
9946 \family typewriter
9947 flags
9948 \family default
9949  resides in xdata.
9950  Setting
9951 \begin_inset Quotes srd
9952 \end_inset
9953
9954
9955 \family typewriter
9956 flags\SpecialChar ~
9957 |=\SpecialChar ~
9958 0x40;
9959 \family default
9960
9961 \begin_inset Quotes sld
9962 \end_inset
9963
9964  from within an interrupt routine might get lost if the interrupt occurs
9965  at the wrong time.
9966
9967 \begin_inset Quotes sld
9968 \end_inset
9969
9970
9971 \family typewriter
9972 counter\SpecialChar ~
9973 +=\SpecialChar ~
9974 8;
9975 \family default
9976
9977 \begin_inset Quotes srd
9978 \end_inset
9979
9980  is not atomic on the 8051 even if
9981 \family typewriter
9982 counter
9983 \family default
9984  is located in data memory.
9985  Bugs like these are hard to reproduce and can cause a lot of trouble.
9986
9987 \layout Standard
9988
9989 The return address and the registers used in the interrupt service routine
9990  are saved on the stack
9991 \begin_inset LatexCommand \index{stack}
9992
9993 \end_inset
9994
9995  so there must be sufficient stack space.
9996  If there isn't variables or registers (or even the return address itself)
9997  will be corrupted.
9998  This
9999 \emph on
10000 stack overflow
10001 \emph default
10002
10003 \begin_inset LatexCommand \index{stack overflow}
10004
10005 \end_inset
10006
10007  is most likely to happen if the interrupt occurs during the
10008 \begin_inset Quotes sld
10009 \end_inset
10010
10011 deepest
10012 \begin_inset Quotes srd
10013 \end_inset
10014
10015  subroutine when the stack is already in use for f.e.
10016  many return addresses.
10017 \layout Standard
10018
10019 A special note here, int (16 bit) and long (32 bit) integer division
10020 \begin_inset LatexCommand \index{Division}
10021
10022 \end_inset
10023
10024 , multiplication
10025 \begin_inset LatexCommand \index{Multiplication}
10026
10027 \end_inset
10028
10029  & modulus
10030 \begin_inset LatexCommand \index{Modulus}
10031
10032 \end_inset
10033
10034  and floating-point
10035 \begin_inset LatexCommand \index{Floating point support}
10036
10037 \end_inset
10038
10039  operations are implemented using external support routines developed in
10040  ANSI-C.
10041  If an interrupt service routine needs to do any of these operations then
10042  the support routines (as mentioned in a following section) will have to
10043  be recompiled using the
10044 \emph on
10045  -
10046 \begin_inset ERT
10047 status Collapsed
10048
10049 \layout Standard
10050
10051 \backslash
10052 /
10053 \end_inset
10054
10055 -stack-auto
10056 \begin_inset LatexCommand \index{-\/-stack-auto}
10057
10058 \end_inset
10059
10060
10061 \emph default
10062  option and the source file will need to be compiled using the
10063 \emph on
10064 -
10065 \begin_inset ERT
10066 status Collapsed
10067
10068 \layout Standard
10069
10070 \backslash
10071 /
10072 \end_inset
10073
10074 -int-long-reent
10075 \emph default
10076
10077 \begin_inset LatexCommand \index{-\/-int-long-reent}
10078
10079 \end_inset
10080
10081  compiler option.
10082 \layout Standard
10083
10084 Calling other functions from an interrupt service routine is not recommended,
10085  avoid it if possible.
10086  Note that when some function is called from an interrupt service routine
10087  it should be preceded by a #pragma\SpecialChar ~
10088 nooverlay
10089 \begin_inset LatexCommand \index{\#pragma nooverlay}
10090
10091 \end_inset
10092
10093  if it is not reentrant.
10094  Furthermore nonreentrant functions should not be called from the main program
10095  while the interrupt service routine might be active.
10096
10097 \newline
10098
10099 \newline
10100 Also see section
10101 \begin_inset LatexCommand \ref{sub:Overlaying}
10102
10103 \end_inset
10104
10105 \SpecialChar ~
10106 about Overlaying and section
10107 \begin_inset LatexCommand \ref{sub:Functions-using-private-banks}
10108
10109 \end_inset
10110
10111 \SpecialChar ~
10112 about Functions using private register banks.
10113 \layout Subsection
10114
10115 MCS51/DS390 Interrupt Service Routines
10116 \layout Standard
10117
10118 Interrupt numbers and the corresponding address & descriptions for the Standard
10119  8051/8052 are listed below.
10120  SDCC will automatically adjust the interrupt vector table to the maximum
10121  interrupt number specified.
10122 \newline
10123
10124 \layout Standard
10125 \align center
10126
10127 \begin_inset  Tabular
10128 <lyxtabular version="3" rows="7" columns="3">
10129 <features>
10130 <column alignment="center" valignment="top" leftline="true" width="0in">
10131 <column alignment="center" valignment="top" leftline="true" width="0in">
10132 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0in">
10133 <row topline="true" bottomline="true">
10134 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10135 \begin_inset Text
10136
10137 \layout Standard
10138
10139 Interrupt #
10140 \end_inset
10141 </cell>
10142 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10143 \begin_inset Text
10144
10145 \layout Standard
10146
10147 Description
10148 \end_inset
10149 </cell>
10150 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10151 \begin_inset Text
10152
10153 \layout Standard
10154
10155 Vector Address
10156 \end_inset
10157 </cell>
10158 </row>
10159 <row topline="true">
10160 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10161 \begin_inset Text
10162
10163 \layout Standard
10164
10165 0
10166 \end_inset
10167 </cell>
10168 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10169 \begin_inset Text
10170
10171 \layout Standard
10172
10173 External 0
10174 \end_inset
10175 </cell>
10176 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10177 \begin_inset Text
10178
10179 \layout Standard
10180
10181 0x0003
10182 \end_inset
10183 </cell>
10184 </row>
10185 <row topline="true">
10186 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10187 \begin_inset Text
10188
10189 \layout Standard
10190
10191 1
10192 \end_inset
10193 </cell>
10194 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10195 \begin_inset Text
10196
10197 \layout Standard
10198
10199 Timer 0
10200 \end_inset
10201 </cell>
10202 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10203 \begin_inset Text
10204
10205 \layout Standard
10206
10207 0x000B
10208 \end_inset
10209 </cell>
10210 </row>
10211 <row topline="true">
10212 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10213 \begin_inset Text
10214
10215 \layout Standard
10216
10217 2
10218 \end_inset
10219 </cell>
10220 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10221 \begin_inset Text
10222
10223 \layout Standard
10224
10225 External 1
10226 \end_inset
10227 </cell>
10228 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10229 \begin_inset Text
10230
10231 \layout Standard
10232
10233 0x0013
10234 \end_inset
10235 </cell>
10236 </row>
10237 <row topline="true">
10238 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10239 \begin_inset Text
10240
10241 \layout Standard
10242
10243 3
10244 \end_inset
10245 </cell>
10246 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10247 \begin_inset Text
10248
10249 \layout Standard
10250
10251 Timer 1
10252 \end_inset
10253 </cell>
10254 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10255 \begin_inset Text
10256
10257 \layout Standard
10258
10259 0x001B
10260 \end_inset
10261 </cell>
10262 </row>
10263 <row topline="true">
10264 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10265 \begin_inset Text
10266
10267 \layout Standard
10268
10269 4
10270 \end_inset
10271 </cell>
10272 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10273 \begin_inset Text
10274
10275 \layout Standard
10276
10277 Serial
10278 \end_inset
10279 </cell>
10280 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10281 \begin_inset Text
10282
10283 \layout Standard
10284
10285 0x0023
10286 \end_inset
10287 </cell>
10288 </row>
10289 <row topline="true" bottomline="true">
10290 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10291 \begin_inset Text
10292
10293 \layout Standard
10294
10295 5
10296 \end_inset
10297 </cell>
10298 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
10299 \begin_inset Text
10300
10301 \layout Standard
10302
10303 Timer 2 (8052)
10304 \end_inset
10305 </cell>
10306 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
10307 \begin_inset Text
10308
10309 \layout Standard
10310
10311 0x002B
10312 \end_inset
10313 </cell>
10314 </row>
10315 </lyxtabular>
10316
10317 \end_inset
10318
10319
10320 \newline
10321
10322 \layout Standard
10323
10324 If the interrupt service routine is defined without
10325 \emph on
10326 using
10327 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10328
10329 \end_inset
10330
10331
10332 \emph default
10333  a register bank or with register bank 0 (
10334 \emph on
10335 using
10336 \emph default
10337  0), the compiler will save the registers used by itself on the stack upon
10338  entry and restore them at exit, however if such an interrupt service routine
10339  calls another function then the entire register bank will be saved on the
10340  stack.
10341  This scheme may be advantageous for small interrupt service routines which
10342  have low register usage.
10343 \layout Standard
10344
10345 If the interrupt service routine is defined to be using a specific register
10346  bank then only
10347 \emph on
10348 a, b, dptr
10349 \emph default
10350  & psw are saved and restored, if such an interrupt service routine calls
10351  another function (using another register bank) then the entire register
10352  bank of the called function will be saved on the stack.
10353  This scheme is recommended for larger interrupt service routines.
10354 \layout Subsection
10355
10356 HC08 Interrupt Service Routines
10357 \layout Standard
10358
10359 Since the number of interrupts available is chip specific and the interrupt
10360  vector table always ends at the last byte of memory, the interrupt numbers
10361  corresponds to the interrupt vectors in reverse order of address.
10362  For example, interrupt 1 will use the interrupt vector at 0xfffc, interrupt
10363  2 will use the interrupt vector at 0xfffa, and so on.
10364  However, interrupt 0 (the reset vector at 0xfffe) is not redefinable in
10365  this way; instead see section
10366 \begin_inset LatexCommand \ref{sub:Startup-Code}
10367
10368 \end_inset
10369
10370  for details on customizing startup.
10371 \layout Subsection
10372
10373 Z80 Interrupt Service Routines
10374 \layout Standard
10375
10376 The Z80 uses several different methods for determining the correct interrupt
10377  vector depending on the hardware implementation.
10378  Therefore, SDCC ignores the optional interrupt number and does not attempt
10379  to generate an interrupt vector table.
10380 \layout Standard
10381
10382 By default, SDCC generates code for a maskable interrupt, which uses an
10383  RETI instruction to return from the interrupt.
10384  To write an interrupt handler for the non-maskable interrupt, which needs
10385  an RETN instruction instead, add the
10386 \emph on
10387 critical
10388 \emph default
10389  keyword:
10390 \layout Verse
10391
10392
10393 \family typewriter
10394 void nmi_isr (void) critical interrupt
10395 \newline
10396 {
10397 \newline
10398 \SpecialChar ~
10399 \SpecialChar ~
10400 \SpecialChar ~
10401 \SpecialChar ~
10402 ...
10403
10404 \newline
10405 }
10406 \layout Section
10407
10408 Enabling and Disabling Interrupts
10409 \layout Subsection
10410
10411 Critical Functions and Critical Statements
10412 \layout Standard
10413
10414 A special keyword may be associated with a block or a function declaring
10415  it as
10416 \emph on
10417 critical
10418 \emph default
10419 .
10420  SDCC will generate code to disable all interrupts
10421 \begin_inset LatexCommand \index{interrupt}
10422
10423 \end_inset
10424
10425  upon entry to a critical function and restore the interrupt enable to the
10426  previous state before returning.
10427  Nesting critical functions will need one additional byte on the stack
10428 \begin_inset LatexCommand \index{stack}
10429
10430 \end_inset
10431
10432  for each call.
10433 \layout Verse
10434
10435
10436 \family typewriter
10437 int foo () critical
10438 \begin_inset LatexCommand \index{critical}
10439
10440 \end_inset
10441
10442
10443 \newline
10444 {
10445 \newline
10446 \SpecialChar ~
10447 \SpecialChar ~
10448 \SpecialChar ~
10449 \SpecialChar ~
10450 ...
10451
10452 \newline
10453 \SpecialChar ~
10454 \SpecialChar ~
10455 \SpecialChar ~
10456 \SpecialChar ~
10457 ...
10458
10459 \newline
10460 }
10461 \layout Standard
10462
10463 The critical attribute maybe used with other attributes like
10464 \emph on
10465 reentrant.
10466 \emph default
10467
10468 \newline
10469 The keyword
10470 \emph on
10471 critical
10472 \emph default
10473  may also be used to disable interrupts more locally:
10474 \layout Verse
10475
10476
10477 \family typewriter
10478 critical{ i++; }
10479 \layout Standard
10480
10481 More than one statement could have been included in the block.
10482 \layout Subsection
10483
10484 Enabling and Disabling Interrupts directly
10485 \layout Standard
10486
10487 Interrupts
10488 \begin_inset LatexCommand \index{interrupt}
10489
10490 \end_inset
10491
10492  can also be disabled and enabled directly (8051):
10493 \layout Verse
10494
10495
10496 \family typewriter
10497 EA = 0;\SpecialChar ~
10498 \SpecialChar ~
10499 \SpecialChar ~
10500 \SpecialChar ~
10501 \SpecialChar ~
10502 \SpecialChar ~
10503 \SpecialChar ~
10504 \SpecialChar ~
10505 \SpecialChar ~
10506 \SpecialChar ~
10507 \SpecialChar ~
10508 \SpecialChar ~
10509 or:\SpecialChar ~
10510 \SpecialChar ~
10511 \SpecialChar ~
10512 \SpecialChar ~
10513 \SpecialChar ~
10514 \SpecialChar ~
10515 \SpecialChar ~
10516 \SpecialChar ~
10517 \SpecialChar ~
10518 \SpecialChar ~
10519 \SpecialChar ~
10520 EA_SAVE = EA;
10521 \layout Verse
10522
10523
10524 \family typewriter
10525 ...\SpecialChar ~
10526 \SpecialChar ~
10527 \SpecialChar ~
10528 \SpecialChar ~
10529 \SpecialChar ~
10530 \SpecialChar ~
10531 \SpecialChar ~
10532 \SpecialChar ~
10533 \SpecialChar ~
10534 \SpecialChar ~
10535 \SpecialChar ~
10536 \SpecialChar ~
10537 \SpecialChar ~
10538 \SpecialChar ~
10539 \SpecialChar ~
10540 \SpecialChar ~
10541 \SpecialChar ~
10542 \SpecialChar ~
10543 \SpecialChar ~
10544 \SpecialChar ~
10545 \SpecialChar ~
10546 \SpecialChar ~
10547 \SpecialChar ~
10548 \SpecialChar ~
10549 \SpecialChar ~
10550 \SpecialChar ~
10551 \SpecialChar ~
10552 \SpecialChar ~
10553 \SpecialChar ~
10554 \SpecialChar ~
10555 EA = 0;
10556 \layout Verse
10557
10558
10559 \family typewriter
10560 EA = 1;\SpecialChar ~
10561 \SpecialChar ~
10562 \SpecialChar ~
10563 \SpecialChar ~
10564 \SpecialChar ~
10565 \SpecialChar ~
10566 \SpecialChar ~
10567 \SpecialChar ~
10568 \SpecialChar ~
10569 \SpecialChar ~
10570 \SpecialChar ~
10571 \SpecialChar ~
10572 \SpecialChar ~
10573 \SpecialChar ~
10574 \SpecialChar ~
10575 \SpecialChar ~
10576 \SpecialChar ~
10577 \SpecialChar ~
10578 \SpecialChar ~
10579 \SpecialChar ~
10580 \SpecialChar ~
10581 \SpecialChar ~
10582 \SpecialChar ~
10583 \SpecialChar ~
10584 \SpecialChar ~
10585 \SpecialChar ~
10586 ...
10587 \layout Verse
10588
10589
10590 \family typewriter
10591 \SpecialChar ~
10592 \SpecialChar ~
10593 \SpecialChar ~
10594 \SpecialChar ~
10595 \SpecialChar ~
10596 \SpecialChar ~
10597 \SpecialChar ~
10598 \SpecialChar ~
10599 \SpecialChar ~
10600 \SpecialChar ~
10601 \SpecialChar ~
10602 \SpecialChar ~
10603 \SpecialChar ~
10604 \SpecialChar ~
10605 \SpecialChar ~
10606 \SpecialChar ~
10607 \SpecialChar ~
10608 \SpecialChar ~
10609 \SpecialChar ~
10610 \SpecialChar ~
10611 \SpecialChar ~
10612 \SpecialChar ~
10613 \SpecialChar ~
10614 \SpecialChar ~
10615 \SpecialChar ~
10616 \SpecialChar ~
10617 \SpecialChar ~
10618 \SpecialChar ~
10619 \SpecialChar ~
10620 \SpecialChar ~
10621 \SpecialChar ~
10622 \SpecialChar ~
10623 \SpecialChar ~
10624 EA = EA_SAVE;
10625 \layout Standard
10626
10627 On other architectures which have seperate opcodes for enabling and disabling
10628  interrupts you might want to make use of defines with inline assembly
10629 \begin_inset LatexCommand \index{Assembler routines}
10630
10631 \end_inset
10632
10633  (HC08):
10634 \layout Verse
10635
10636
10637 \family typewriter
10638 #define CLI _asm
10639 \begin_inset LatexCommand \index{\_asm}
10640
10641 \end_inset
10642
10643 \SpecialChar ~
10644 \SpecialChar ~
10645 cli\SpecialChar ~
10646 \SpecialChar ~
10647 _endasm
10648 \begin_inset LatexCommand \index{\_endasm}
10649
10650 \end_inset
10651
10652 ;
10653 \layout Verse
10654
10655
10656 \family typewriter
10657 #define SEI _asm\SpecialChar ~
10658 \SpecialChar ~
10659 sei\SpecialChar ~
10660 \SpecialChar ~
10661 _endasm;
10662 \layout Verse
10663
10664
10665 \family typewriter
10666 ...
10667 \layout Standard
10668
10669 Note: it is sometimes sufficient to disable only a specific interrupt source
10670  like f.e.
10671  a timer or serial interrupt by manipulating an
10672 \emph on
10673 interrupt mask
10674 \begin_inset LatexCommand \index{interrupt mask}
10675
10676 \end_inset
10677
10678
10679 \emph default
10680  register.
10681
10682 \layout Standard
10683
10684 Usually the time during which interrupts are disabled should be kept as
10685  short as possible.
10686  This minimizes both
10687 \emph on
10688 interrupt latency
10689 \emph default
10690
10691 \begin_inset LatexCommand \index{interrupt latency}
10692
10693 \end_inset
10694
10695  (the time between the occurrence of the interrupt and the execution of
10696  the first code in the interrupt routine) and
10697 \emph on
10698 interrupt jitter
10699 \emph default
10700
10701 \begin_inset LatexCommand \index{interrupt jitter}
10702
10703 \end_inset
10704
10705  (the difference between the shortest and the longest interrupt latency).
10706  These really are something different, f.e.
10707  a serial interrupt has to be served before its buffer overruns so it cares
10708  for the maximum interrupt latency, whereas it does not care about jitter.
10709  On a loudspeaker driven via a digital to analog converter which is fed
10710  by an interrupt a latency of a few milliseconds might be tolerable, whereas
10711  a much smaller jitter will be very audible.
10712 \layout Standard
10713
10714 You can reenable interrupts within an interrupt routine and on some architecture
10715 s you can make use of two (or more) levels of
10716 \emph on
10717 interrupt priorities
10718 \emph default
10719
10720 \begin_inset LatexCommand \index{interrupt priority}
10721
10722 \end_inset
10723
10724 .
10725  On some architectures which don't support interrupt priorities these can
10726  be implemented by manipulating the interrupt mask and reenabling interrupts
10727  within the interrupt routine.
10728  Check there is sufficient space on the stack
10729 \begin_inset LatexCommand \index{stack}
10730
10731 \end_inset
10732
10733  and don't add complexity unless you have to.
10734
10735 \layout Subsection
10736
10737 Semaphore
10738 \begin_inset LatexCommand \index{semaphore}
10739
10740 \end_inset
10741
10742  locking (mcs51/ds390)
10743 \layout Standard
10744
10745 Some architectures (mcs51/ds390) have an atomic
10746 \begin_inset LatexCommand \index{atomic}
10747
10748 \end_inset
10749
10750  bit test and
10751 \emph on
10752
10753 \emph default
10754 clear
10755 \emph on
10756
10757 \emph default
10758 instruction.
10759  These type of instructions are typically used in preemptive multitasking
10760  systems, where a routine f.e.
10761  claims the use of a data structure ('acquires a lock
10762 \begin_inset LatexCommand \index{lock}
10763
10764 \end_inset
10765
10766  on it'), makes some modifications and then releases the lock when the data
10767  structure is consistent again.
10768  The instruction may also be used if interrupt and non-interrupt code have
10769  to compete for a resource.
10770  With the atomic bit test and clear instruction interrupts
10771 \begin_inset LatexCommand \index{interrupt}
10772
10773 \end_inset
10774
10775  don't have to be disabled for the locking operation.
10776
10777 \layout Standard
10778
10779 SDCC generates this instruction if the source follows this pattern:
10780 \layout Verse
10781
10782
10783 \family typewriter
10784 volatile bit resource_is_free;
10785 \newline
10786
10787 \newline
10788 if (resource_is_free)
10789 \newline
10790 \SpecialChar ~
10791 \SpecialChar ~
10792 {
10793 \newline
10794 \SpecialChar ~
10795 \SpecialChar ~
10796 \SpecialChar ~
10797 \SpecialChar ~
10798 resource_is_free=0;
10799 \newline
10800 \SpecialChar ~
10801 \SpecialChar ~
10802 \SpecialChar ~
10803 \SpecialChar ~
10804 ...
10805
10806 \newline
10807 \SpecialChar ~
10808 \SpecialChar ~
10809 \SpecialChar ~
10810 \SpecialChar ~
10811 resource_is_free=1;
10812 \newline
10813 \SpecialChar ~
10814 \SpecialChar ~
10815 }
10816 \layout Standard
10817
10818 Note, mcs51 and ds390 support only an atomic
10819 \begin_inset LatexCommand \index{atomic}
10820
10821 \end_inset
10822
10823  bit test and
10824 \emph on
10825 clear
10826 \emph default
10827  instruction (as opposed to atomic bit test and
10828 \emph on
10829 set).
10830 \layout Section
10831
10832 Functions using private register banks
10833 \begin_inset LatexCommand \label{sub:Functions-using-private-banks}
10834
10835 \end_inset
10836
10837  (mcs51/ds390)
10838 \layout Standard
10839
10840 Some architectures have support for quickly changing register sets.
10841  SDCC supports this feature with the
10842 \emph on
10843 using
10844 \begin_inset LatexCommand \index{using (mcs51, ds390 register bank)}
10845
10846 \end_inset
10847
10848
10849 \emph default
10850  attribute (which tells the compiler to use a register bank
10851 \begin_inset LatexCommand \index{register bank (mcs51, ds390)}
10852
10853 \end_inset
10854
10855  other than the default bank zero).
10856  It should only be applied to
10857 \emph on
10858 interrupt
10859 \begin_inset LatexCommand \index{interrupt}
10860
10861 \end_inset
10862
10863
10864 \emph default
10865  functions (see footnote below).
10866  This will in most circumstances make the generated ISR code more efficient
10867  since it will not have to save registers on the stack.
10868 \layout Standard
10869
10870 The
10871 \emph on
10872 using
10873 \emph default
10874  attribute will have no effect on the generated code for a
10875 \emph on
10876 non-interrupt
10877 \emph default
10878  function (but may occasionally be useful anyway
10879 \begin_inset Foot
10880 collapsed false
10881
10882 \layout Standard
10883
10884 possible exception: if a function is called ONLY from 'interrupt' functions
10885  using a particular bank, it can be declared with the same 'using' attribute
10886  as the calling 'interrupt' functions.
10887  For instance, if you have several ISRs using bank one, and all of them
10888  call memcpy(), it might make sense to create a specialized version of memcpy()
10889  'using 1', since this would prevent the ISR from having to save bank zero
10890  to the stack on entry and switch to bank zero before calling the function
10891 \end_inset
10892
10893 ).
10894 \newline
10895
10896 \emph on
10897 (pending: I don't think this has been done yet)
10898 \layout Standard
10899
10900 An
10901 \emph on
10902 interrupt
10903 \emph default
10904  function using a non-zero bank will assume that it can trash that register
10905  bank, and will not save it.
10906  Since high-priority interrupts
10907 \begin_inset LatexCommand \index{interrupt priority}
10908
10909 \end_inset
10910
10911  can interrupt low-priority ones on the 8051 and friends, this means that
10912  if a high-priority ISR
10913 \emph on
10914 using
10915 \emph default
10916  a particular bank occurs while processing a low-priority ISR
10917 \emph on
10918 using
10919 \emph default
10920  the same bank, terrible and bad things can happen.
10921  To prevent this, no single register bank should be
10922 \emph on
10923 used
10924 \emph default
10925  by both a high priority and a low priority ISR.
10926  This is probably most easily done by having all high priority ISRs use
10927  one bank and all low priority ISRs use another.
10928  If you have an ISR which can change priority at runtime, you're on your
10929  own: I suggest using the default bank zero and taking the small performance
10930  hit.
10931 \layout Standard
10932
10933 It is most efficient if your ISR calls no other functions.
10934  If your ISR must call other functions, it is most efficient if those functions
10935  use the same bank as the ISR (see note 1 below); the next best is if the
10936  called functions use bank zero.
10937  It is very inefficient to call a function using a different, non-zero bank
10938  from an ISR.
10939
10940 \layout Section
10941
10942 Startup Code
10943 \begin_inset LatexCommand \label{sub:Startup-Code}
10944
10945 \end_inset
10946
10947
10948 \begin_inset LatexCommand \index{Startup code}
10949
10950 \end_inset
10951
10952
10953 \layout Subsection
10954
10955 MCS51/DS390 Startup Code
10956 \layout Standard
10957
10958 The compiler inserts a call to the C routine
10959 \emph on
10960 _sdcc_external_startup()
10961 \begin_inset LatexCommand \index{\_sdcc\_external\_startup()}
10962
10963 \end_inset
10964
10965
10966 \series bold
10967 \emph default
10968
10969 \series default
10970 at the start of the CODE area.
10971  This routine is in the runtime library
10972 \begin_inset LatexCommand \index{Runtime library}
10973
10974 \end_inset
10975
10976 .
10977  By default this routine returns 0, if this routine returns a non-zero value,
10978  the static & global variable initialization will be skipped and the function
10979  main will be invoked.
10980  Otherwise static & global variables will be initialized before the function
10981  main is invoked.
10982  You could add a
10983 \emph on
10984 _sdcc_external_startup()
10985 \emph default
10986  routine to your program to override the default if you need to setup hardware
10987  or perform some other critical operation prior to static & global variable
10988  initialization.
10989  On some mcs51 variants xdata has to be explicitly enabled before it can
10990  be accessed, this is the place to do it.
10991  The startup code clears the complete 256 byte of idata memory, this might
10992  cause problems for 128 byte devices (endless loop reported for Chipcon
10993  CC1010).
10994 \layout Standard
10995
10996 See also the compiler option
10997 \emph on
10998 -
10999 \begin_inset ERT
11000 status Collapsed
11001
11002 \layout Standard
11003
11004 \backslash
11005 /
11006 \end_inset
11007
11008 -no-xinit
11009 \emph default
11010 -
11011 \emph on
11012 opt
11013 \emph default
11014
11015 \begin_inset LatexCommand \index{-\/-no-xinit-opt}
11016
11017 \end_inset
11018
11019  and section
11020 \begin_inset LatexCommand \ref{sub:MCS51-variants}
11021
11022 \end_inset
11023
11024 \SpecialChar ~
11025 about MCS51-variants.
11026 \layout Subsection
11027
11028 HC08 Startup Code
11029 \layout Standard
11030
11031 The HC08 startup code follows the same scheme as the MCS51 startup code.
11032 \layout Subsection
11033
11034 Z80 Startup Code
11035 \layout Standard
11036
11037 On the Z80 the startup code is inserted by linking with crt0.o which is generated
11038  from sdcc/device/lib/z80/crt0.s.
11039  If you need a different startup code you can use the compiler option
11040 \emph on
11041 -
11042 \series bold
11043 \emph default
11044
11045 \begin_inset ERT
11046 status Collapsed
11047
11048 \layout Standard
11049
11050 \backslash
11051 /
11052 \end_inset
11053
11054
11055 \series default
11056 \emph on
11057 -no-std-crt0
11058 \emph default
11059
11060 \begin_inset LatexCommand \index{-\/-no-std-crt0}
11061
11062 \end_inset
11063
11064  and provide your own crt0.o.
11065
11066 \layout Section
11067
11068 Inline Assembler Code
11069 \begin_inset LatexCommand \index{Assembler routines}
11070
11071 \end_inset
11072
11073
11074 \layout Subsection
11075
11076 A Step by Step Introduction
11077 \begin_inset LatexCommand \label{sub:A-Step-by Assembler Introduction}
11078
11079 \end_inset
11080
11081
11082 \layout Standard
11083
11084 Starting from a small snippet of c-code this example shows for the MCS51
11085  how to use inline assembly, access variables, a function parameter and
11086  an array in xdata memory.
11087  The example uses an MCS51 here but is easily adapted for other architectures.
11088  This is a buffer routine which should be optimized:
11089 \layout Verse
11090
11091
11092 \family typewriter
11093 \size footnotesize
11094 unsigned char far
11095 \begin_inset LatexCommand \index{far (storage class)}
11096
11097 \end_inset
11098
11099  at
11100 \begin_inset LatexCommand \index{at}
11101
11102 \end_inset
11103
11104  0x7f00 buf[0x100];
11105 \begin_inset LatexCommand \index{Aligned array}
11106
11107 \end_inset
11108
11109
11110 \newline
11111 unsigned char head,tail;
11112 \newline
11113
11114 \newline
11115 void to_buffer( unsigned char c )
11116 \newline
11117 {
11118 \newline
11119 \SpecialChar ~
11120 \SpecialChar ~
11121 \SpecialChar ~
11122 \SpecialChar ~
11123 if( head != tail-1 )
11124 \newline
11125 \SpecialChar ~
11126 \SpecialChar ~
11127 \SpecialChar ~
11128 \SpecialChar ~
11129 \SpecialChar ~
11130 \SpecialChar ~
11131 \SpecialChar ~
11132 \SpecialChar ~
11133 buf[ head++ ] = c;\SpecialChar ~
11134 \SpecialChar ~
11135 \SpecialChar ~
11136 \SpecialChar ~
11137 /* access to a 256 byte aligned array */
11138 \newline
11139 }
11140 \layout Standard
11141
11142 If the code snippet (assume it is saved in buffer.c) is compiled with SDCC
11143  then a corresponding buffer.asm file is generated.
11144  We define a new function
11145 \family typewriter
11146 to_buffer_asm()
11147 \family default
11148  in file buffer.c in which we cut and paste the generated code, removing
11149  unwanted comments and some ':'.
11150  Then add
11151 \begin_inset Quotes sld
11152 \end_inset
11153
11154 _asm
11155 \begin_inset Quotes srd
11156 \end_inset
11157
11158  and
11159 \begin_inset Quotes sld
11160 \end_inset
11161
11162 _endasm;
11163 \begin_inset Quotes srd
11164 \end_inset
11165
11166  to the beginning and the end of the function body:
11167 \layout Verse
11168
11169
11170 \family typewriter
11171 \size footnotesize
11172 /* With a cut and paste from the .asm file, we have something to start with.
11173 \newline
11174 \SpecialChar ~
11175 \SpecialChar ~
11176 \SpecialChar ~
11177 The function is not yet OK! (registers aren't saved) */
11178 \newline
11179 void to_buffer_asm( unsigned char c )
11180 \newline
11181 {
11182 \newline
11183 \SpecialChar ~
11184 \SpecialChar ~
11185 \SpecialChar ~
11186 \SpecialChar ~
11187 _asm
11188 \begin_inset LatexCommand \index{\_asm}
11189
11190 \end_inset
11191
11192
11193 \newline
11194 \SpecialChar ~
11195 \SpecialChar ~
11196 \SpecialChar ~
11197 \SpecialChar ~
11198 mov\SpecialChar ~
11199 \SpecialChar ~
11200 r2,dpl
11201 \newline
11202 ;buffer.c if( head != tail-1 )
11203 \newline
11204 \SpecialChar ~
11205 \SpecialChar ~
11206 \SpecialChar ~
11207 \SpecialChar ~
11208 mov\SpecialChar ~
11209 \SpecialChar ~
11210 a,_tail
11211 \newline
11212 \SpecialChar ~
11213 \SpecialChar ~
11214 \SpecialChar ~
11215 \SpecialChar ~
11216 dec\SpecialChar ~
11217 \SpecialChar ~
11218 a
11219 \newline
11220 \SpecialChar ~
11221 \SpecialChar ~
11222 \SpecialChar ~
11223 \SpecialChar ~
11224 mov\SpecialChar ~
11225 \SpecialChar ~
11226 r3,a
11227 \newline
11228 \SpecialChar ~
11229 \SpecialChar ~
11230 \SpecialChar ~
11231 \SpecialChar ~
11232 mov\SpecialChar ~
11233 \SpecialChar ~
11234 a,_head
11235 \newline
11236 \SpecialChar ~
11237 \SpecialChar ~
11238 \SpecialChar ~
11239 \SpecialChar ~
11240 cjne a,ar3,00106$
11241 \newline
11242 \SpecialChar ~
11243 \SpecialChar ~
11244 \SpecialChar ~
11245 \SpecialChar ~
11246 ret
11247 \newline
11248 00106$:
11249 \newline
11250 ;buffer.c buf[ head++ ] = c; /* access to a 256 byte aligned array */
11251 \begin_inset LatexCommand \index{Aligned array}
11252
11253 \end_inset
11254
11255
11256 \newline
11257 \SpecialChar ~
11258 \SpecialChar ~
11259 \SpecialChar ~
11260 \SpecialChar ~
11261 mov\SpecialChar ~
11262 \SpecialChar ~
11263 r3,_head
11264 \newline
11265 \SpecialChar ~
11266 \SpecialChar ~
11267 \SpecialChar ~
11268 \SpecialChar ~
11269 inc\SpecialChar ~
11270 \SpecialChar ~
11271 _head
11272 \newline
11273 \SpecialChar ~
11274 \SpecialChar ~
11275 \SpecialChar ~
11276 \SpecialChar ~
11277 mov\SpecialChar ~
11278 \SpecialChar ~
11279 dpl,r3
11280 \newline
11281 \SpecialChar ~
11282 \SpecialChar ~
11283 \SpecialChar ~
11284 \SpecialChar ~
11285 mov\SpecialChar ~
11286 \SpecialChar ~
11287 dph,#(_buf >> 8)
11288 \newline
11289 \SpecialChar ~
11290 \SpecialChar ~
11291 \SpecialChar ~
11292 \SpecialChar ~
11293 mov\SpecialChar ~
11294 \SpecialChar ~
11295 a,r2
11296 \newline
11297 \SpecialChar ~
11298 \SpecialChar ~
11299 \SpecialChar ~
11300 \SpecialChar ~
11301 movx @dptr,a
11302 \newline
11303 00103$:
11304 \newline
11305 \SpecialChar ~
11306 \SpecialChar ~
11307 \SpecialChar ~
11308 \SpecialChar ~
11309 ret
11310 \newline
11311 \SpecialChar ~
11312 \SpecialChar ~
11313 \SpecialChar ~
11314 \SpecialChar ~
11315 _endasm;
11316 \newline
11317 }
11318 \layout Standard
11319
11320 The new file buffer.c should compile with only one warning about the unreferenced
11321  function argument 'c'.
11322  Now we hand-optimize the assembly code and insert an #define USE_ASSEMBLY
11323  (1) and finally have:
11324 \layout Verse
11325
11326
11327 \family typewriter
11328 \size footnotesize
11329 unsigned char far at 0x7f00 buf[0x100];
11330 \newline
11331 unsigned char head,tail;
11332 \newline
11333 #define USE_ASSEMBLY (1)
11334 \newline
11335
11336 \newline
11337 #if !USE_ASSEMBLY
11338 \newline
11339
11340 \newline
11341 void to_buffer( unsigned char c )
11342 \newline
11343 {
11344 \newline
11345 \SpecialChar ~
11346 \SpecialChar ~
11347 \SpecialChar ~
11348 \SpecialChar ~
11349 if( head != tail-1 )
11350 \newline
11351 \SpecialChar ~
11352 \SpecialChar ~
11353 \SpecialChar ~
11354 \SpecialChar ~
11355 \SpecialChar ~
11356 \SpecialChar ~
11357 \SpecialChar ~
11358 \SpecialChar ~
11359 buf[ head++ ] = c;
11360 \newline
11361 }
11362 \newline
11363
11364 \newline
11365 #else
11366 \newline
11367
11368 \newline
11369 void to_buffer( unsigned char c )
11370 \newline
11371 {
11372 \newline
11373 \SpecialChar ~
11374 \SpecialChar ~
11375 \SpecialChar ~
11376 \SpecialChar ~
11377 c; // to avoid warning: unreferenced function argument
11378 \newline
11379 \SpecialChar ~
11380 \SpecialChar ~
11381 \SpecialChar ~
11382 \SpecialChar ~
11383 _asm
11384 \begin_inset LatexCommand \index{\_asm}
11385
11386 \end_inset
11387
11388
11389 \newline
11390 \SpecialChar ~
11391 \SpecialChar ~
11392 \SpecialChar ~
11393 \SpecialChar ~
11394 \SpecialChar ~
11395 \SpecialChar ~
11396 \SpecialChar ~
11397 \SpecialChar ~
11398 ; save used registers here.
11399
11400 \newline
11401 \SpecialChar ~
11402 \SpecialChar ~
11403 \SpecialChar ~
11404 \SpecialChar ~
11405 \SpecialChar ~
11406 \SpecialChar ~
11407 \SpecialChar ~
11408 \SpecialChar ~
11409 ; If we were still using r2,r3 we would have to push them here.
11410
11411 \newline
11412 ; if( head != tail-1 )
11413 \newline
11414 \SpecialChar ~
11415 \SpecialChar ~
11416 \SpecialChar ~
11417 \SpecialChar ~
11418 \SpecialChar ~
11419 \SpecialChar ~
11420 \SpecialChar ~
11421 \SpecialChar ~
11422 mov\SpecialChar ~
11423  a,_tail
11424 \newline
11425 \SpecialChar ~
11426 \SpecialChar ~
11427 \SpecialChar ~
11428 \SpecialChar ~
11429 \SpecialChar ~
11430 \SpecialChar ~
11431 \SpecialChar ~
11432 \SpecialChar ~
11433 dec\SpecialChar ~
11434  a
11435 \newline
11436 \SpecialChar ~
11437 \SpecialChar ~
11438 \SpecialChar ~
11439 \SpecialChar ~
11440 \SpecialChar ~
11441 \SpecialChar ~
11442 \SpecialChar ~
11443 \SpecialChar ~
11444 xrl\SpecialChar ~
11445  a,_head
11446 \newline
11447 \SpecialChar ~
11448 \SpecialChar ~
11449 \SpecialChar ~
11450 \SpecialChar ~
11451 \SpecialChar ~
11452 \SpecialChar ~
11453 \SpecialChar ~
11454 \SpecialChar ~
11455 ; we could do an ANL a,#0x0f here to use a smaller buffer (see below)
11456 \newline
11457 \SpecialChar ~
11458 \SpecialChar ~
11459 \SpecialChar ~
11460 \SpecialChar ~
11461 \SpecialChar ~
11462 \SpecialChar ~
11463 \SpecialChar ~
11464 \SpecialChar ~
11465 jz\SpecialChar ~
11466 \SpecialChar ~
11467  t_b_end$
11468 \newline
11469 \SpecialChar ~
11470 \SpecialChar ~
11471 \SpecialChar ~
11472 \SpecialChar ~
11473 \SpecialChar ~
11474 \SpecialChar ~
11475 \SpecialChar ~
11476 \SpecialChar ~
11477 ;
11478 \newline
11479 ; buf[ head++ ] = c;
11480 \newline
11481 \SpecialChar ~
11482 \SpecialChar ~
11483 \SpecialChar ~
11484 \SpecialChar ~
11485 \SpecialChar ~
11486 \SpecialChar ~
11487 \SpecialChar ~
11488 \SpecialChar ~
11489 mov\SpecialChar ~
11490  a,dpl \SpecialChar ~
11491 \SpecialChar ~
11492 \SpecialChar ~
11493 \SpecialChar ~
11494 \SpecialChar ~
11495 \SpecialChar ~
11496 \SpecialChar ~
11497 ; dpl holds lower byte of function argument
11498 \newline
11499 \SpecialChar ~
11500 \SpecialChar ~
11501 \SpecialChar ~
11502 \SpecialChar ~
11503 \SpecialChar ~
11504 \SpecialChar ~
11505 \SpecialChar ~
11506 \SpecialChar ~
11507 mov\SpecialChar ~
11508  dpl,_head \SpecialChar ~
11509 \SpecialChar ~
11510 \SpecialChar ~
11511 ; buf is 0x100 byte aligned so head can be used directly
11512 \newline
11513 \SpecialChar ~
11514 \SpecialChar ~
11515 \SpecialChar ~
11516 \SpecialChar ~
11517 \SpecialChar ~
11518 \SpecialChar ~
11519 \SpecialChar ~
11520 \SpecialChar ~
11521 mov\SpecialChar ~
11522  dph,#(_buf>>8)
11523 \newline
11524 \SpecialChar ~
11525 \SpecialChar ~
11526 \SpecialChar ~
11527 \SpecialChar ~
11528 \SpecialChar ~
11529 \SpecialChar ~
11530 \SpecialChar ~
11531 \SpecialChar ~
11532 movx @dptr,a
11533 \newline
11534 \SpecialChar ~
11535 \SpecialChar ~
11536 \SpecialChar ~
11537 \SpecialChar ~
11538 \SpecialChar ~
11539 \SpecialChar ~
11540 \SpecialChar ~
11541 \SpecialChar ~
11542 inc \SpecialChar ~
11543 _head
11544 \newline
11545 \SpecialChar ~
11546 \SpecialChar ~
11547 \SpecialChar ~
11548 \SpecialChar ~
11549 \SpecialChar ~
11550 \SpecialChar ~
11551 \SpecialChar ~
11552 \SpecialChar ~
11553 ; we could do an ANL _head,#0x0f here to use a smaller buffer (see above)
11554 \newline
11555 t_b_end$:
11556 \newline
11557 \SpecialChar ~
11558 \SpecialChar ~
11559 \SpecialChar ~
11560 \SpecialChar ~
11561 \SpecialChar ~
11562 \SpecialChar ~
11563 \SpecialChar ~
11564 \SpecialChar ~
11565 ; restore used registers here
11566 \newline
11567 \SpecialChar ~
11568 \SpecialChar ~
11569 \SpecialChar ~
11570 \SpecialChar ~
11571 _endasm;
11572 \newline
11573 }
11574 \newline
11575 #endif
11576 \layout Standard
11577
11578 The inline assembler code can contain any valid code understood by the assembler
11579 , this includes any assembler directives and comment lines
11580 \begin_inset Foot
11581 collapsed false
11582
11583 \layout Standard
11584
11585 The assembler does not like some characters like ':' or ''' in comments.
11586  You'll find an 100+ pages assembler manual in sdcc/as/doc/asxhtm.html
11587 \end_inset
11588
11589 .
11590  The compiler does not do any validation of the code within the
11591 \family typewriter
11592 _asm
11593 \begin_inset LatexCommand \index{\_asm}
11594
11595 \end_inset
11596
11597  ...
11598  _endasm;
11599 \family default
11600  keyword pair.
11601  Specifically it will not know which registers are used and thus register
11602  pushing/popping
11603 \begin_inset LatexCommand \index{push/pop}
11604
11605 \end_inset
11606
11607  has to be done manually.
11608
11609 \layout Standard
11610
11611 It is recommended that each assembly instruction (including labels) be placed
11612  in a separate line (as the example shows).
11613  When the -
11614 \begin_inset ERT
11615 status Collapsed
11616
11617 \layout Standard
11618
11619 \backslash
11620 /
11621 \end_inset
11622
11623 -
11624 \emph on
11625 peep-asm
11626 \begin_inset LatexCommand \index{-\/-peep-asm}
11627
11628 \end_inset
11629
11630
11631 \emph default
11632  command line option is used, the inline assembler code will be passed through
11633  the peephole optimizer
11634 \begin_inset LatexCommand \index{Peephole optimizer}
11635
11636 \end_inset
11637
11638 .
11639  There are only a few (if any) cases where this option makes sense, it might
11640  cause some unexpected changes in the inline assembler code.
11641  Please go through the peephole optimizer rules defined in file
11642 \emph on
11643 SDCCpeeph.def
11644 \emph default
11645  before using this option.
11646 \layout Subsection
11647
11648 Naked Functions
11649 \begin_inset LatexCommand \label{sub:Naked-Functions}
11650
11651 \end_inset
11652
11653
11654 \begin_inset LatexCommand \index{Naked functions}
11655
11656 \end_inset
11657
11658
11659 \layout Standard
11660
11661 A special keyword may be associated with a function declaring it as
11662 \emph on
11663 _naked
11664 \begin_inset LatexCommand \index{\_naked}
11665
11666 \end_inset
11667
11668 .
11669
11670 \emph default
11671 The
11672 \emph on
11673 _naked
11674 \emph default
11675  function modifier attribute prevents the compiler from generating prologue
11676 \begin_inset LatexCommand \index{function prologue}
11677
11678 \end_inset
11679
11680  and epilogue
11681 \begin_inset LatexCommand \index{function epilogue}
11682
11683 \end_inset
11684
11685  code for that function.
11686  This means that the user is entirely responsible for such things as saving
11687  any registers that may need to be preserved, selecting the proper register
11688  bank, generating the
11689 \emph on
11690 return
11691 \emph default
11692  instruction at the end, etc.
11693  Practically, this means that the contents of the function must be written
11694  in inline assembler.
11695  This is particularly useful for interrupt functions, which can have a large
11696  (and often unnecessary) prologue/epilogue.
11697  For example, compare the code generated by these two functions:
11698 \layout Verse
11699
11700
11701 \family typewriter
11702 volatile
11703 \begin_inset LatexCommand \index{volatile}
11704
11705 \end_inset
11706
11707  data unsigned char counter;
11708 \newline
11709
11710 \newline
11711 void simpleInterrupt(void) interrupt
11712 \begin_inset LatexCommand \index{interrupt}
11713
11714 \end_inset
11715
11716  1
11717 \newline
11718 {
11719 \newline
11720 \SpecialChar ~
11721 \SpecialChar ~
11722 \SpecialChar ~
11723 \SpecialChar ~
11724 counter++;
11725 \newline
11726 }
11727 \newline
11728
11729 \newline
11730 void nakedInterrupt(void) interrupt 2 _naked
11731 \newline
11732 {
11733 \newline
11734 \SpecialChar ~
11735 \SpecialChar ~
11736 \SpecialChar ~
11737 \SpecialChar ~
11738 _asm
11739 \begin_inset LatexCommand \index{\_asm}
11740
11741 \end_inset
11742
11743
11744 \newline
11745 \SpecialChar ~
11746 \SpecialChar ~
11747 \SpecialChar ~
11748 \SpecialChar ~
11749 \SpecialChar ~
11750 \SpecialChar ~
11751 inc\SpecialChar ~
11752 \SpecialChar ~
11753 \SpecialChar ~
11754 \SpecialChar ~
11755 \SpecialChar ~
11756 _counter ; does not change flags, no need to save psw
11757 \newline
11758 \SpecialChar ~
11759 \SpecialChar ~
11760 \SpecialChar ~
11761 \SpecialChar ~
11762 \SpecialChar ~
11763 \SpecialChar ~
11764 reti\SpecialChar ~
11765 \SpecialChar ~
11766 \SpecialChar ~
11767 \SpecialChar ~
11768 ; MUST explicitly include ret or reti in _naked function.
11769 \newline
11770 \SpecialChar ~
11771 \SpecialChar ~
11772 \SpecialChar ~
11773 \SpecialChar ~
11774 _endasm
11775 \begin_inset LatexCommand \index{\_endasm}
11776
11777 \end_inset
11778
11779 ;
11780 \newline
11781 }
11782 \layout Standard
11783
11784 For an 8051 target, the generated simpleInterrupt looks like:
11785 \layout Verse
11786
11787
11788 \family typewriter
11789 _simpleInterrupt:
11790 \newline
11791 \SpecialChar ~
11792 \SpecialChar ~
11793 \SpecialChar ~
11794 \SpecialChar ~
11795 push\SpecialChar ~
11796 \SpecialChar ~
11797 \SpecialChar ~
11798 \SpecialChar ~
11799 acc
11800 \newline
11801 \SpecialChar ~
11802 \SpecialChar ~
11803 \SpecialChar ~
11804 \SpecialChar ~
11805 push\SpecialChar ~
11806 \SpecialChar ~
11807 \SpecialChar ~
11808 \SpecialChar ~
11809 b
11810 \newline
11811 \SpecialChar ~
11812 \SpecialChar ~
11813 \SpecialChar ~
11814 \SpecialChar ~
11815 push\SpecialChar ~
11816 \SpecialChar ~
11817 \SpecialChar ~
11818 \SpecialChar ~
11819 dpl
11820 \newline
11821 \SpecialChar ~
11822 \SpecialChar ~
11823 \SpecialChar ~
11824 \SpecialChar ~
11825 push\SpecialChar ~
11826 \SpecialChar ~
11827 \SpecialChar ~
11828 \SpecialChar ~
11829 dph
11830 \newline
11831 \SpecialChar ~
11832 \SpecialChar ~
11833 \SpecialChar ~
11834 \SpecialChar ~
11835 push\SpecialChar ~
11836 \SpecialChar ~
11837 \SpecialChar ~
11838 \SpecialChar ~
11839 psw
11840 \newline
11841 \SpecialChar ~
11842 \SpecialChar ~
11843 \SpecialChar ~
11844 \SpecialChar ~
11845 mov\SpecialChar ~
11846 \SpecialChar ~
11847 \SpecialChar ~
11848 \SpecialChar ~
11849 \SpecialChar ~
11850 psw,#0x00
11851 \newline
11852 \SpecialChar ~
11853 \SpecialChar ~
11854 \SpecialChar ~
11855 \SpecialChar ~
11856 inc\SpecialChar ~
11857 \SpecialChar ~
11858 \SpecialChar ~
11859 \SpecialChar ~
11860 \SpecialChar ~
11861 _counter
11862 \newline
11863 \SpecialChar ~
11864 \SpecialChar ~
11865 \SpecialChar ~
11866 \SpecialChar ~
11867 pop\SpecialChar ~
11868 \SpecialChar ~
11869 \SpecialChar ~
11870 \SpecialChar ~
11871 \SpecialChar ~
11872 psw
11873 \newline
11874 \SpecialChar ~
11875 \SpecialChar ~
11876 \SpecialChar ~
11877 \SpecialChar ~
11878 pop\SpecialChar ~
11879 \SpecialChar ~
11880 \SpecialChar ~
11881 \SpecialChar ~
11882 \SpecialChar ~
11883 dph
11884 \newline
11885 \SpecialChar ~
11886 \SpecialChar ~
11887 \SpecialChar ~
11888 \SpecialChar ~
11889 pop\SpecialChar ~
11890 \SpecialChar ~
11891 \SpecialChar ~
11892 \SpecialChar ~
11893 \SpecialChar ~
11894 dpl
11895 \newline
11896 \SpecialChar ~
11897 \SpecialChar ~
11898 \SpecialChar ~
11899 \SpecialChar ~
11900 pop\SpecialChar ~
11901 \SpecialChar ~
11902 \SpecialChar ~
11903 \SpecialChar ~
11904 \SpecialChar ~
11905 b
11906 \newline
11907 \SpecialChar ~
11908 \SpecialChar ~
11909 \SpecialChar ~
11910 \SpecialChar ~
11911 pop\SpecialChar ~
11912 \SpecialChar ~
11913 \SpecialChar ~
11914 \SpecialChar ~
11915 \SpecialChar ~
11916 acc
11917 \newline
11918 \SpecialChar ~
11919 \SpecialChar ~
11920 \SpecialChar ~
11921 \SpecialChar ~
11922 reti
11923 \layout Standard
11924
11925 whereas nakedInterrupt looks like:
11926 \layout Verse
11927
11928
11929 \family typewriter
11930 _nakedInterrupt:
11931 \newline
11932 \SpecialChar ~
11933 \SpecialChar ~
11934 \SpecialChar ~
11935 \SpecialChar ~
11936 inc\SpecialChar ~
11937 \SpecialChar ~
11938 \SpecialChar ~
11939 \SpecialChar ~
11940 _counter ; does not change flags, no need to save psw
11941 \newline
11942 \SpecialChar ~
11943 \SpecialChar ~
11944 \SpecialChar ~
11945 \SpecialChar ~
11946 reti\SpecialChar ~
11947 \SpecialChar ~
11948 \SpecialChar ~
11949 \SpecialChar ~
11950 \SpecialChar ~
11951 \SpecialChar ~
11952 \SpecialChar ~
11953 \SpecialChar ~
11954 \SpecialChar ~
11955 \SpecialChar ~
11956 \SpecialChar ~
11957 \SpecialChar ~
11958 ; MUST explicitly include ret or reti in _naked function
11959 \layout Standard
11960
11961 The related directive #pragma exclude
11962 \begin_inset LatexCommand \index{\#pragma exclude}
11963
11964 \end_inset
11965
11966  allows a more fine grained control over pushing & popping
11967 \begin_inset LatexCommand \index{push/pop}
11968
11969 \end_inset
11970
11971  the registers.
11972 \layout Standard
11973
11974 While there is nothing preventing you from writing C code inside a
11975 \family typewriter
11976 _naked
11977 \family default
11978  function, there are many ways to shoot yourself in the foot doing this,
11979  and it is recommended that you stick to inline assembler.
11980 \layout Subsection
11981
11982 Use of Labels within Inline Assembler
11983 \layout Standard
11984
11985 SDCC allows the use of in-line assembler with a few restrictions regarding
11986  labels.
11987  In older versions of the compiler all labels defined within inline assembler
11988  code
11989 \emph on
11990 had to be
11991 \emph default
11992  of the form
11993 \emph on
11994 nnnnn$
11995 \emph default
11996  where nnnn is a number less than 100 (which implies a limit of utmost 100
11997  inline assembler labels
11998 \emph on
11999 per function
12000 \emph default
12001 \noun on
12002 )
12003 \noun default
12004 .
12005
12006 \layout Verse
12007
12008
12009 \family typewriter
12010 _asm
12011 \begin_inset LatexCommand \index{\_asm}
12012
12013 \end_inset
12014
12015
12016 \newline
12017 \SpecialChar ~
12018 \SpecialChar ~
12019 \SpecialChar ~
12020 \SpecialChar ~
12021 mov\SpecialChar ~
12022 \SpecialChar ~
12023 \SpecialChar ~
12024 \SpecialChar ~
12025 \SpecialChar ~
12026 b,#10
12027 \newline
12028 00001$:
12029 \newline
12030 \SpecialChar ~
12031 \SpecialChar ~
12032 \SpecialChar ~
12033 \SpecialChar ~
12034 djnz\SpecialChar ~
12035 \SpecialChar ~
12036 \SpecialChar ~
12037 \SpecialChar ~
12038 b,00001$
12039 \newline
12040 _endasm
12041 \begin_inset LatexCommand \index{\_endasm}
12042
12043 \end_inset
12044
12045  ;
12046 \layout Standard
12047
12048 Inline assembler code cannot reference any C-Labels, however it can reference
12049  labels
12050 \begin_inset LatexCommand \index{Labels}
12051
12052 \end_inset
12053
12054  defined by the inline assembler, e.g.:
12055 \layout Verse
12056
12057
12058 \family typewriter
12059 foo() {
12060 \newline
12061 \SpecialChar ~
12062 \SpecialChar ~
12063 \SpecialChar ~
12064 \SpecialChar ~
12065 /* some c code */
12066 \newline
12067 \SpecialChar ~
12068 \SpecialChar ~
12069 \SpecialChar ~
12070 \SpecialChar ~
12071 _asm
12072 \newline
12073 \SpecialChar ~
12074 \SpecialChar ~
12075 \SpecialChar ~
12076 \SpecialChar ~
12077 \SpecialChar ~
12078 \SpecialChar ~
12079 ; some assembler code
12080 \newline
12081 \SpecialChar ~
12082 \SpecialChar ~
12083 \SpecialChar ~
12084 \SpecialChar ~
12085 \SpecialChar ~
12086 \SpecialChar ~
12087 ljmp $0003
12088 \newline
12089 \SpecialChar ~
12090 \SpecialChar ~
12091 \SpecialChar ~
12092 \SpecialChar ~
12093 _endasm;
12094 \newline
12095 \SpecialChar ~
12096 \SpecialChar ~
12097 \SpecialChar ~
12098 \SpecialChar ~
12099 /* some more c code */
12100 \newline
12101 clabel:\SpecialChar ~
12102 \SpecialChar ~
12103 /* inline assembler cannot reference this label */
12104 \newline
12105 \SpecialChar ~
12106 \SpecialChar ~
12107 \SpecialChar ~
12108 \SpecialChar ~
12109 _asm
12110 \newline
12111 \SpecialChar ~
12112 \SpecialChar ~
12113 \SpecialChar ~
12114 \SpecialChar ~
12115 $0003: ;label (can be referenced by inline assembler only)
12116 \newline
12117 \SpecialChar ~
12118 \SpecialChar ~
12119 \SpecialChar ~
12120 \SpecialChar ~
12121 _endasm ;
12122 \newline
12123 \SpecialChar ~
12124 \SpecialChar ~
12125 \SpecialChar ~
12126 \SpecialChar ~
12127 /* some more c code */
12128 \newline
12129 }
12130 \layout Standard
12131
12132 In other words inline assembly code can access labels defined in inline
12133  assembly within the scope of the function.
12134  The same goes the other way, i.e.
12135  labels defines in inline assembly can not be accessed by C statements.
12136 \layout Section
12137
12138 Interfacing with Assembler Code
12139 \begin_inset LatexCommand \index{Assembler routines}
12140
12141 \end_inset
12142
12143
12144 \layout Subsection
12145
12146 Global Registers used for Parameter Passing
12147 \begin_inset LatexCommand \index{Parameter passing}
12148
12149 \end_inset
12150
12151
12152 \layout Standard
12153
12154 The compiler always uses the global registers
12155 \emph on
12156 DPL, DPH
12157 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12158
12159 \end_inset
12160
12161
12162 \begin_inset LatexCommand \index{DPTR}
12163
12164 \end_inset
12165
12166 , B
12167 \begin_inset LatexCommand \index{B (mcs51, ds390 register)}
12168
12169 \end_inset
12170
12171
12172 \emph default
12173 and
12174 \emph on
12175  ACC
12176 \begin_inset LatexCommand \index{ACC (mcs51, ds390 register)}
12177
12178 \end_inset
12179
12180
12181 \emph default
12182  to pass the first parameter to a routine.
12183  The second parameter onwards is either allocated on the stack (for reentrant
12184  routines or if -
12185 \begin_inset ERT
12186 status Collapsed
12187
12188 \layout Standard
12189
12190 \backslash
12191 /
12192 \end_inset
12193
12194 -stack-auto is used) or in data / xdata memory (depending on the memory
12195  model).
12196
12197 \layout Subsection
12198
12199 Assembler Routine (non-reentrant)
12200 \layout Standard
12201
12202 In the following example
12203 \begin_inset LatexCommand \index{reentrant}
12204
12205 \end_inset
12206
12207
12208 \begin_inset LatexCommand \index{Assembler routines (non-reentrant)}
12209
12210 \end_inset
12211
12212  the function c_func calls an assembler routine asm_func, which takes two
12213  parameters
12214 \begin_inset LatexCommand \index{function parameter}
12215
12216 \end_inset
12217
12218 .
12219 \layout Verse
12220
12221
12222 \family typewriter
12223 extern int asm_func(unsigned char, unsigned char);
12224 \newline
12225
12226 \newline
12227 int c_func (unsigned char i, unsigned char j)
12228 \newline
12229 {
12230 \newline
12231 \SpecialChar ~
12232 \SpecialChar ~
12233 \SpecialChar ~
12234 \SpecialChar ~
12235 return asm_func(i,j);
12236 \newline
12237 }
12238 \newline
12239
12240 \newline
12241 int main()
12242 \newline
12243 {
12244 \newline
12245 \SpecialChar ~
12246 \SpecialChar ~
12247 \SpecialChar ~
12248 \SpecialChar ~
12249 return c_func(10,9);
12250 \newline
12251 }
12252 \layout Standard
12253
12254 The corresponding assembler function is:
12255 \layout Verse
12256
12257
12258 \family typewriter
12259 .globl _asm_func_PARM_2
12260 \newline
12261 \SpecialChar ~
12262 \SpecialChar ~
12263 \SpecialChar ~
12264 \SpecialChar ~
12265 \SpecialChar ~
12266 \SpecialChar ~
12267 \SpecialChar ~
12268 \SpecialChar ~
12269 .globl _asm_func
12270 \newline
12271 \SpecialChar ~
12272 \SpecialChar ~
12273 \SpecialChar ~
12274 \SpecialChar ~
12275 \SpecialChar ~
12276 \SpecialChar ~
12277 \SpecialChar ~
12278 \SpecialChar ~
12279 .area OSEG
12280 \newline
12281 _asm_func_PARM_2:
12282 \newline
12283 \SpecialChar ~
12284 \SpecialChar ~
12285 \SpecialChar ~
12286 \SpecialChar ~
12287 \SpecialChar ~
12288 \SpecialChar ~
12289 \SpecialChar ~
12290 \SpecialChar ~
12291 .ds    1
12292 \newline
12293 \SpecialChar ~
12294 \SpecialChar ~
12295 \SpecialChar ~
12296 \SpecialChar ~
12297 \SpecialChar ~
12298 \SpecialChar ~
12299 \SpecialChar ~
12300 \SpecialChar ~
12301 .area CSEG
12302 \newline
12303 _asm_func:
12304 \newline
12305 \SpecialChar ~
12306 \SpecialChar ~
12307 \SpecialChar ~
12308 \SpecialChar ~
12309 \SpecialChar ~
12310 \SpecialChar ~
12311 \SpecialChar ~
12312 \SpecialChar ~
12313 mov\SpecialChar ~
12314 \SpecialChar ~
12315 \SpecialChar ~
12316 \SpecialChar ~
12317 a,dpl
12318 \newline
12319 \SpecialChar ~
12320 \SpecialChar ~
12321 \SpecialChar ~
12322 \SpecialChar ~
12323 \SpecialChar ~
12324 \SpecialChar ~
12325 \SpecialChar ~
12326 \SpecialChar ~
12327 add\SpecialChar ~
12328 \SpecialChar ~
12329 \SpecialChar ~
12330 \SpecialChar ~
12331 a,_asm_func_PARM_2
12332 \newline
12333 \SpecialChar ~
12334 \SpecialChar ~
12335 \SpecialChar ~
12336 \SpecialChar ~
12337 \SpecialChar ~
12338 \SpecialChar ~
12339 \SpecialChar ~
12340 \SpecialChar ~
12341 mov\SpecialChar ~
12342 \SpecialChar ~
12343 \SpecialChar ~
12344 \SpecialChar ~
12345 dpl,a
12346 \newline
12347 \SpecialChar ~
12348 \SpecialChar ~
12349 \SpecialChar ~
12350 \SpecialChar ~
12351 \SpecialChar ~
12352 \SpecialChar ~
12353 \SpecialChar ~
12354 \SpecialChar ~
12355 mov\SpecialChar ~
12356 \SpecialChar ~
12357 \SpecialChar ~
12358 \SpecialChar ~
12359 dph
12360 \begin_inset LatexCommand \index{DPTR, DPH, DPL}
12361
12362 \end_inset
12363
12364 ,#0x00
12365 \newline
12366 \SpecialChar ~
12367 \SpecialChar ~
12368 \SpecialChar ~
12369 \SpecialChar ~
12370 \SpecialChar ~
12371 \SpecialChar ~
12372 \SpecialChar ~
12373 \SpecialChar ~
12374 ret
12375 \layout Standard
12376
12377 Note here that the return values
12378 \begin_inset LatexCommand \index{return value}
12379
12380 \end_inset
12381
12382  are placed in 'dpl' - One byte return value, 'dpl' LSB & 'dph' MSB for
12383  two byte values.
12384  'dpl', 'dph' and 'b' for three byte values (generic pointers) and 'dpl','dph','
12385 b' & 'acc' for four byte values.
12386 \layout Standard
12387
12388 The parameter naming convention is _<function_name>_PARM_<n>, where n is
12389  the parameter number starting from 1, and counting from the left.
12390  The first parameter is passed in
12391 \begin_inset Quotes eld
12392 \end_inset
12393
12394 dpl
12395 \begin_inset Quotes erd
12396 \end_inset
12397
12398  for a one byte parameter,
12399 \begin_inset Quotes eld
12400 \end_inset
12401
12402 dptr
12403 \begin_inset Quotes erd
12404 \end_inset
12405
12406  for two bytes,
12407 \begin_inset Quotes eld
12408 \end_inset
12409
12410 b,dptr
12411 \begin_inset Quotes erd
12412 \end_inset
12413
12414  for three bytes and
12415 \begin_inset Quotes eld
12416 \end_inset
12417
12418 acc,b,dptr
12419 \begin_inset Quotes erd
12420 \end_inset
12421
12422  for a four bytes parameter.
12423  The variable name for the second parameter will be _<function_name>_PARM_2.
12424 \newline
12425
12426 \newline
12427 Assemble the assembler routine with the following command:
12428 \newline
12429
12430 \newline
12431
12432 \family sans
12433 \series bold
12434 asx8051 -losg asmfunc.asm
12435 \newline
12436
12437 \newline
12438
12439 \family default
12440 \series default
12441 Then compile and link the assembler routine to the C source file with the
12442  following command:
12443 \newline
12444
12445 \newline
12446
12447 \family sans
12448 \series bold
12449 sdcc cfunc.c asmfunc.rel
12450 \layout Subsection
12451
12452 Assembler Routine (reentrant)
12453 \layout Standard
12454
12455 In this case
12456 \begin_inset LatexCommand \index{reentrant}
12457
12458 \end_inset
12459
12460
12461 \begin_inset LatexCommand \index{Assembler routines (reentrant)}
12462
12463 \end_inset
12464
12465  the second parameter
12466 \begin_inset LatexCommand \index{function parameter}
12467
12468 \end_inset
12469
12470  onwards will be passed on the stack, the parameters are pushed from right
12471  to left i.e.
12472  after the call the leftmost parameter will be on the top of the stack.
12473  Here is an example:
12474 \layout Verse
12475
12476
12477 \family typewriter
12478 extern int asm_func(unsigned char, unsigned char);
12479 \newline
12480
12481 \newline
12482 int c_func (unsigned char i, unsigned char j) reentrant
12483 \newline
12484 {
12485 \newline
12486 \SpecialChar ~
12487 \SpecialChar ~
12488 \SpecialChar ~
12489 \SpecialChar ~
12490 return asm_func(i,j);
12491 \newline
12492 }
12493 \newline
12494
12495 \newline
12496 int main()
12497 \newline
12498 {
12499 \newline
12500 \SpecialChar ~
12501 \SpecialChar ~
12502 \SpecialChar ~
12503 \SpecialChar ~
12504 return c_func(10,9);
12505 \newline
12506 }
12507 \layout Standard
12508
12509 The corresponding assembler routine is:
12510 \layout Verse
12511
12512
12513 \family typewriter
12514 .globl _asm_func
12515 \newline
12516 _asm_func:
12517 \newline
12518 \SpecialChar ~
12519 \SpecialChar ~
12520 \SpecialChar ~
12521 \SpecialChar ~
12522 push  _bp
12523 \newline
12524 \SpecialChar ~
12525 \SpecialChar ~
12526 \SpecialChar ~
12527 \SpecialChar ~
12528 mov _bp,sp
12529 \newline
12530 \SpecialChar ~
12531 \SpecialChar ~
12532 \SpecialChar ~
12533 \SpecialChar ~
12534 mov r2,dpl
12535 \newline
12536 \SpecialChar ~
12537 \SpecialChar ~
12538 \SpecialChar ~
12539 \SpecialChar ~
12540 mov a,_bp
12541 \newline
12542 \SpecialChar ~
12543 \SpecialChar ~
12544 \SpecialChar ~
12545 \SpecialChar ~
12546 add a,#0xfd
12547 \newline
12548 \SpecialChar ~
12549 \SpecialChar ~
12550 \SpecialChar ~
12551 \SpecialChar ~
12552 mov r0,a
12553 \newline
12554 \SpecialChar ~
12555 \SpecialChar ~
12556 \SpecialChar ~
12557 \SpecialChar ~
12558 add  a,#0xfc ;?
12559 \newline
12560 \SpecialChar ~
12561 \SpecialChar ~
12562 \SpecialChar ~
12563 \SpecialChar ~
12564 mov  r1,a
12565 \newline
12566 \SpecialChar ~
12567 \SpecialChar ~
12568 \SpecialChar ~
12569 \SpecialChar ~
12570 mov  a,@r0
12571 \newline
12572 \SpecialChar ~
12573 \SpecialChar ~
12574 \SpecialChar ~
12575 \SpecialChar ~
12576 add  a,r2 ;?
12577 \newline
12578 \SpecialChar ~
12579 \SpecialChar ~
12580 \SpecialChar ~
12581 \SpecialChar ~
12582 mov  dpl,a
12583 \newline
12584 \SpecialChar ~
12585 \SpecialChar ~
12586 \SpecialChar ~
12587 \SpecialChar ~
12588 mov  dph,#0x00
12589 \newline
12590 \SpecialChar ~
12591 \SpecialChar ~
12592 \SpecialChar ~
12593 \SpecialChar ~
12594 mov  sp,_bp
12595 \newline
12596 \SpecialChar ~
12597 \SpecialChar ~
12598 \SpecialChar ~
12599 \SpecialChar ~
12600 pop  _bp
12601 \newline
12602 \SpecialChar ~
12603 \SpecialChar ~
12604 \SpecialChar ~
12605 \SpecialChar ~
12606 ret
12607 \layout Standard
12608
12609 The compiling and linking procedure remains the same, however note the extra
12610  entry & exit linkage required for the assembler code, _bp is the stack
12611  frame pointer and is used to compute the offset into the stack for parameters
12612  and local variables.
12613 \layout Section
12614
12615 int (16 bit)
12616 \begin_inset LatexCommand \index{int (16 bit)}
12617
12618 \end_inset
12619
12620  and long (32 bit)
12621 \begin_inset LatexCommand \index{long (32 bit)}
12622
12623 \end_inset
12624
12625  Support
12626 \layout Standard
12627
12628 For signed & unsigned int (16 bit) and long (32 bit) variables, division,
12629  multiplication and modulus operations are implemented by support routines.
12630  These support routines are all developed in ANSI-C to facilitate porting
12631  to other MCUs, although some model specific assembler optimizations are
12632  used.
12633  The following files contain the described routines, all of them can be
12634  found in <installdir>/share/sdcc/lib.
12635 \newline
12636
12637 \layout Standard
12638 \align center
12639
12640 \begin_inset  Tabular
12641 <lyxtabular version="3" rows="11" columns="2">
12642 <features>
12643 <column alignment="center" valignment="top" leftline="true" width="0">
12644 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12645 <row topline="true" bottomline="true">
12646 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12647 \begin_inset Text
12648
12649 \layout Standard
12650
12651
12652 \series bold
12653 Function
12654 \end_inset
12655 </cell>
12656 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12657 \begin_inset Text
12658
12659 \layout Standard
12660
12661
12662 \series bold
12663 Description
12664 \end_inset
12665 </cell>
12666 </row>
12667 <row topline="true">
12668 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12669 \begin_inset Text
12670
12671 \layout Standard
12672
12673 _mulint.c
12674 \end_inset
12675 </cell>
12676 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12677 \begin_inset Text
12678
12679 \layout Standard
12680
12681 16 bit multiplication
12682 \end_inset
12683 </cell>
12684 </row>
12685 <row topline="true">
12686 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12687 \begin_inset Text
12688
12689 \layout Standard
12690
12691 _divsint.c
12692 \end_inset
12693 </cell>
12694 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12695 \begin_inset Text
12696
12697 \layout Standard
12698
12699  signed 16 bit division (calls _divuint)
12700 \end_inset
12701 </cell>
12702 </row>
12703 <row topline="true">
12704 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12705 \begin_inset Text
12706
12707 \layout Standard
12708
12709 _divuint.c
12710 \end_inset
12711 </cell>
12712 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12713 \begin_inset Text
12714
12715 \layout Standard
12716
12717  unsigned 16 bit division
12718 \end_inset
12719 </cell>
12720 </row>
12721 <row topline="true">
12722 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12723 \begin_inset Text
12724
12725 \layout Standard
12726
12727 _modsint.c
12728 \end_inset
12729 </cell>
12730 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12731 \begin_inset Text
12732
12733 \layout Standard
12734
12735 signed 16 bit modulus (calls _moduint)
12736 \end_inset
12737 </cell>
12738 </row>
12739 <row topline="true">
12740 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12741 \begin_inset Text
12742
12743 \layout Standard
12744
12745 _moduint.c
12746 \end_inset
12747 </cell>
12748 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12749 \begin_inset Text
12750
12751 \layout Standard
12752
12753 unsigned 16 bit modulus
12754 \end_inset
12755 </cell>
12756 </row>
12757 <row topline="true">
12758 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12759 \begin_inset Text
12760
12761 \layout Standard
12762
12763 _mullong.c
12764 \end_inset
12765 </cell>
12766 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12767 \begin_inset Text
12768
12769 \layout Standard
12770
12771 32 bit multiplication
12772 \end_inset
12773 </cell>
12774 </row>
12775 <row topline="true">
12776 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12777 \begin_inset Text
12778
12779 \layout Standard
12780
12781 _divslong.c
12782 \end_inset
12783 </cell>
12784 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12785 \begin_inset Text
12786
12787 \layout Standard
12788
12789  signed 32 division (calls _divulong)
12790 \end_inset
12791 </cell>
12792 </row>
12793 <row topline="true">
12794 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12795 \begin_inset Text
12796
12797 \layout Standard
12798
12799 _divulong.c
12800 \end_inset
12801 </cell>
12802 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12803 \begin_inset Text
12804
12805 \layout Standard
12806
12807 unsigned 32 division
12808 \end_inset
12809 </cell>
12810 </row>
12811 <row topline="true">
12812 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12813 \begin_inset Text
12814
12815 \layout Standard
12816
12817 _modslong.c
12818 \end_inset
12819 </cell>
12820 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12821 \begin_inset Text
12822
12823 \layout Standard
12824
12825  signed 32 bit modulus (calls _modulong)
12826 \end_inset
12827 </cell>
12828 </row>
12829 <row topline="true" bottomline="true">
12830 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12831 \begin_inset Text
12832
12833 \layout Standard
12834
12835 _modulong.c
12836 \end_inset
12837 </cell>
12838 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12839 \begin_inset Text
12840
12841 \layout Standard
12842
12843 unsigned 32 bit modulus
12844 \end_inset
12845 </cell>
12846 </row>
12847 </lyxtabular>
12848
12849 \end_inset
12850
12851
12852 \newline
12853
12854 \layout Standard
12855
12856 Since they are compiled as
12857 \emph on
12858 non-reentrant
12859 \emph default
12860
12861 \begin_inset LatexCommand \index{reentrant}
12862
12863 \end_inset
12864
12865 , interrupt
12866 \begin_inset LatexCommand \index{interrupt}
12867
12868 \end_inset
12869
12870  service routines should not do any of the above operations.
12871  If this is unavoidable then the above routines will need to be compiled
12872  with the
12873 \emph on
12874 -
12875 \begin_inset ERT
12876 status Collapsed
12877
12878 \layout Standard
12879
12880 \backslash
12881 /
12882 \end_inset
12883
12884 -stack-auto
12885 \begin_inset LatexCommand \index{-\/-stack-auto}
12886
12887 \end_inset
12888
12889
12890 \emph default
12891  option, after which the source program will have to be compiled with
12892 \emph on
12893 -
12894 \begin_inset ERT
12895 status Collapsed
12896
12897 \layout Standard
12898
12899 \backslash
12900 /
12901 \end_inset
12902
12903 -int-long-reent
12904 \begin_inset LatexCommand \index{-\/-int-long-reent}
12905
12906 \end_inset
12907
12908
12909 \emph default
12910  option.
12911  Notice that you don't have to call these routines directly.
12912  The compiler will use them automatically every time an integer operation
12913  is required.
12914 \layout Section
12915
12916 Floating Point Support
12917 \begin_inset LatexCommand \index{Floating point support}
12918
12919 \end_inset
12920
12921
12922 \layout Standard
12923
12924 SDCC supports IEEE (single precision 4 bytes) floating point numbers.The
12925  floating point support routines are derived from gcc's floatlib.c and consist
12926  of the following routines:
12927 \newline
12928
12929 \layout Standard
12930 \align center
12931
12932 \size footnotesize
12933
12934 \begin_inset  Tabular
12935 <lyxtabular version="3" rows="17" columns="2">
12936 <features>
12937 <column alignment="center" valignment="top" leftline="true" width="0">
12938 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
12939 <row topline="true" bottomline="true">
12940 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
12941 \begin_inset Text
12942
12943 \layout Standard
12944
12945
12946 \family roman
12947 \series medium
12948 \shape up
12949 \size normal
12950 \emph off
12951 \bar no
12952 \noun off
12953 \color none
12954 Function
12955 \end_inset
12956 </cell>
12957 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
12958 \begin_inset Text
12959
12960 \layout Standard
12961
12962 Description
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 _fsadd.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 add floating point numbers
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 _fssub.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 subtract floating point numbers
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 _fsdiv.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 divide floating point numbers
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 _fsmul.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 multiply floating point numbers
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 _fs2uchar.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 floating point to unsigned char
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 _fs2char.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 floating point to signed char
13179 \end_inset
13180 </cell>
13181 </row>
13182 <row topline="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 _fs2uint.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 floating point to unsigned int
13215 \end_inset
13216 </cell>
13217 </row>
13218 <row topline="true">
13219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13220 \begin_inset Text
13221
13222 \layout Standard
13223
13224
13225 \family roman
13226 \series medium
13227 \shape up
13228 \size normal
13229 \emph off
13230 \bar no
13231 \noun off
13232 \color none
13233 _fs2int.c
13234 \end_inset
13235 </cell>
13236 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13237 \begin_inset Text
13238
13239 \layout Standard
13240
13241
13242 \family roman
13243 \series medium
13244 \shape up
13245 \size normal
13246 \emph off
13247 \bar no
13248 \noun off
13249 \color none
13250 convert floating point to signed int
13251 \end_inset
13252 </cell>
13253 </row>
13254 <row topline="true">
13255 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13256 \begin_inset Text
13257
13258 \layout Standard
13259
13260
13261 \family roman
13262 \series medium
13263 \shape up
13264 \size normal
13265 \emph off
13266 \bar no
13267 \noun off
13268 \color none
13269 _fs2ulong.
13270 \family default
13271 \series default
13272 \shape default
13273 \size default
13274 \emph default
13275 \bar default
13276 \noun default
13277 \color default
13278 c
13279 \end_inset
13280 </cell>
13281 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13282 \begin_inset Text
13283
13284 \layout Standard
13285
13286
13287 \family roman
13288 \series medium
13289 \shape up
13290 \size normal
13291 \emph off
13292 \bar no
13293 \noun off
13294 \color none
13295 convert floating point to unsigned long
13296 \end_inset
13297 </cell>
13298 </row>
13299 <row topline="true">
13300 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13301 \begin_inset Text
13302
13303 \layout Standard
13304
13305
13306 \family roman
13307 \series medium
13308 \shape up
13309 \size normal
13310 \emph off
13311 \bar no
13312 \noun off
13313 \color none
13314 _fs2long.c
13315 \end_inset
13316 </cell>
13317 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13318 \begin_inset Text
13319
13320 \layout Standard
13321
13322
13323 \family roman
13324 \series medium
13325 \shape up
13326 \size normal
13327 \emph off
13328 \bar no
13329 \noun off
13330 \color none
13331 convert floating point to signed long
13332 \end_inset
13333 </cell>
13334 </row>
13335 <row topline="true">
13336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13337 \begin_inset Text
13338
13339 \layout Standard
13340
13341
13342 \family roman
13343 \series medium
13344 \shape up
13345 \size normal
13346 \emph off
13347 \bar no
13348 \noun off
13349 \color none
13350 _uchar2fs.c
13351 \end_inset
13352 </cell>
13353 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13354 \begin_inset Text
13355
13356 \layout Standard
13357
13358
13359 \family roman
13360 \series medium
13361 \shape up
13362 \size normal
13363 \emph off
13364 \bar no
13365 \noun off
13366 \color none
13367 convert unsigned char to floating point
13368 \end_inset
13369 </cell>
13370 </row>
13371 <row topline="true">
13372 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13373 \begin_inset Text
13374
13375 \layout Standard
13376
13377
13378 \family roman
13379 \series medium
13380 \shape up
13381 \size normal
13382 \emph off
13383 \bar no
13384 \noun off
13385 \color none
13386 _char2fs.c
13387 \end_inset
13388 </cell>
13389 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13390 \begin_inset Text
13391
13392 \layout Standard
13393
13394
13395 \family roman
13396 \series medium
13397 \shape up
13398 \size normal
13399 \emph off
13400 \bar no
13401 \noun off
13402 \color none
13403 convert char to floating point number
13404 \end_inset
13405 </cell>
13406 </row>
13407 <row topline="true">
13408 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13409 \begin_inset Text
13410
13411 \layout Standard
13412
13413
13414 \family roman
13415 \series medium
13416 \shape up
13417 \size normal
13418 \emph off
13419 \bar no
13420 \noun off
13421 \color none
13422 _uint2fs.c
13423 \end_inset
13424 </cell>
13425 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13426 \begin_inset Text
13427
13428 \layout Standard
13429
13430
13431 \family roman
13432 \series medium
13433 \shape up
13434 \size normal
13435 \emph off
13436 \bar no
13437 \noun off
13438 \color none
13439 convert unsigned int to floating point
13440 \end_inset
13441 </cell>
13442 </row>
13443 <row topline="true">
13444 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13445 \begin_inset Text
13446
13447 \layout Standard
13448
13449
13450 \family roman
13451 \series medium
13452 \shape up
13453 \size normal
13454 \emph off
13455 \bar no
13456 \noun off
13457 \color none
13458 _int2fs.c
13459 \end_inset
13460 </cell>
13461 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13462 \begin_inset Text
13463
13464 \layout Standard
13465
13466
13467 \family roman
13468 \series medium
13469 \shape up
13470 \size normal
13471 \emph off
13472 \bar no
13473 \noun off
13474 \color none
13475 convert int to floating point numbers
13476 \end_inset
13477 </cell>
13478 </row>
13479 <row topline="true">
13480 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13481 \begin_inset Text
13482
13483 \layout Standard
13484
13485
13486 \family roman
13487 \series medium
13488 \shape up
13489 \size normal
13490 \emph off
13491 \bar no
13492 \noun off
13493 \color none
13494 _ulong2fs.c
13495 \end_inset
13496 </cell>
13497 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13498 \begin_inset Text
13499
13500 \layout Standard
13501
13502
13503 \family roman
13504 \series medium
13505 \shape up
13506 \size normal
13507 \emph off
13508 \bar no
13509 \noun off
13510 \color none
13511 convert unsigned long to floating point number
13512 \end_inset
13513 </cell>
13514 </row>
13515 <row topline="true" bottomline="true">
13516 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
13517 \begin_inset Text
13518
13519 \layout Standard
13520
13521
13522 \family roman
13523 \series medium
13524 \shape up
13525 \size normal
13526 \emph off
13527 \bar no
13528 \noun off
13529 \color none
13530 _long2fs.c
13531 \end_inset
13532 </cell>
13533 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
13534 \begin_inset Text
13535
13536 \layout Standard
13537
13538
13539 \family roman
13540 \series medium
13541 \shape up
13542 \size normal
13543 \emph off
13544 \bar no
13545 \noun off
13546 \color none
13547 convert long to floating point number
13548 \end_inset
13549 </cell>
13550 </row>
13551 </lyxtabular>
13552
13553 \end_inset
13554
13555
13556 \newline
13557
13558 \layout Standard
13559
13560 These support routines are developed in ANSI-C so there is room for space
13561  and speed improvement.
13562  Note if all these routines are used simultaneously the data space might
13563  overflow.
13564  For serious floating point usage it is recommended that the large model
13565  be used.
13566  Also notice that you don't have to call this routines directly.
13567  The compiler will use them automatically every time a floating point operation
13568  is required.
13569 \layout Section
13570
13571 Library Routines
13572 \begin_inset LatexCommand \index{Libraries}
13573
13574 \end_inset
13575
13576
13577 \layout Standard
13578
13579
13580 \emph on
13581 <pending: this is messy and incomplete - a little more information is in
13582  sdcc/doc/libdoc.txt
13583 \emph default
13584  >
13585 \layout Subsection
13586
13587 Compiler support routines (_gptrget, _mulint etc.)
13588 \layout Subsection
13589
13590 Stdclib functions (puts, printf, strcat etc.)
13591 \layout Subsubsection
13592
13593 <stdio.h>
13594 \layout Standard
13595
13596
13597 \begin_inset LatexCommand \index{<stdio.h>}
13598
13599 \end_inset
13600
13601 As usual on embedded systems you have to provide your own
13602 \family typewriter
13603 getchar()
13604 \begin_inset LatexCommand \index{getchar()}
13605
13606 \end_inset
13607
13608
13609 \family default
13610 and
13611 \family typewriter
13612 putchar()
13613 \begin_inset LatexCommand \index{putchar()}
13614
13615 \end_inset
13616
13617
13618 \family default
13619  routines.
13620  SDCC does not know whether the system connects to a serial line with or
13621  without handshake, LCD, keyboard or other device.
13622  You'll find examples for serial routines f.e.
13623  in sdcc/device/lib.
13624 \layout Standard
13625
13626 If you're short on memory you might want to use
13627 \family typewriter
13628 printf_small()
13629 \family default
13630
13631 \emph on
13632 instead
13633 \emph default
13634  of
13635 \family typewriter
13636  printf()
13637 \begin_inset LatexCommand \index{printf()}
13638
13639 \end_inset
13640
13641 .
13642
13643 \family default
13644  For the mcs51 there is an assembly version
13645 \family typewriter
13646 printf_fast()
13647 \family default
13648  which should fit the requirements of many embedded systems (by unsetting
13649  #defines it can be customized to
13650 \emph on
13651 not
13652 \emph default
13653  support long variables and field widths).
13654 \layout Subsection
13655
13656 Math functions (sin, pow, sqrt etc.)
13657 \layout Subsection
13658
13659 Other libraries
13660 \layout Standard
13661
13662 Libraries
13663 \begin_inset LatexCommand \index{Libraries}
13664
13665 \end_inset
13666
13667  included in SDCC should have a license at least as liberal as the GNU Lesser
13668  General Public License
13669 \begin_inset LatexCommand \index{GNU Lesser General Public License, LGPL}
13670
13671 \end_inset
13672
13673
13674 \emph on
13675 LGPL
13676 \emph default
13677 .
13678 \layout Comment
13679
13680 license statements for the libraries are missing.
13681  sdcc/device/lib/ser_ir.c
13682 \layout Comment
13683
13684 or _decdptr f.e.
13685  come with a GPL (as opposed to LGPL) License - this will not be liberal
13686  enough for many embedded programmers.
13687 \layout Standard
13688
13689 If you have ported some library or want to share experience about some code
13690  which f.e.
13691  falls into any of these categories Busses (I
13692 \begin_inset Formula $^{\textrm{2}}$
13693 \end_inset
13694
13695 C, CAN, Ethernet, Profibus, Modbus, USB, SPI, JTAG ...), Media (IDE, Memory
13696  cards, eeprom, flash...), En-/Decryption, Remote debugging, Realtime kernel,
13697  Keyboard, LCD, RTC, FPGA, PID then the sdcc-user mailing list
13698 \begin_inset LatexCommand \url{http://sourceforge.net/mail/?group_id=599}
13699
13700 \end_inset
13701
13702 \SpecialChar ~
13703 would certainly like to hear about it.
13704  Programmers coding for embedded systems are not especially famous for being
13705  enthusiastic, so don't expect a big hurray but as the mailing list is searchabl
13706 e these references are very valuable.
13707  Let's help to create a climate where information is shared.
13708 \layout Section
13709
13710 Memory Models
13711 \layout Subsection
13712
13713 MCS51 Memory Models
13714 \begin_inset LatexCommand \index{Memory model}
13715
13716 \end_inset
13717
13718
13719 \begin_inset LatexCommand \index{MCS51 memory model}
13720
13721 \end_inset
13722
13723
13724 \layout Subsubsection
13725
13726 Small and Large
13727 \layout Standard
13728
13729 SDCC allows two memory models for MCS51 code,
13730 \shape slanted
13731 small
13732 \shape default
13733  and
13734 \shape slanted
13735 large
13736 \shape default
13737 .
13738  Modules compiled with different memory models should
13739 \emph on
13740 never
13741 \emph default
13742  be combined together or the results would be unpredictable.
13743  The library routines supplied with the compiler are compiled as both small
13744  and large.
13745  The compiled library modules are contained in separate directories as small
13746  and large so that you can link to either set.
13747
13748 \layout Standard
13749
13750 When the large model is used all variables declared without a storage class
13751  will be allocated into the external ram, this includes all parameters and
13752  local variables (for non-reentrant
13753 \begin_inset LatexCommand \index{reentrant}
13754
13755 \end_inset
13756
13757  functions).
13758  When the small model is used variables without storage class are allocated
13759  in the internal ram.
13760 \layout Standard
13761
13762 Judicious usage of the processor specific storage classes
13763 \begin_inset LatexCommand \index{Storage class}
13764
13765 \end_inset
13766
13767  and the 'reentrant' function type will yield much more efficient code,
13768  than using the large model.
13769  Several optimizations are disabled when the program is compiled using the
13770  large model, it is therefore recommended that the small model be used unless
13771  absolutely required.
13772 \layout Subsubsection
13773
13774 External Stack
13775 \begin_inset LatexCommand \label{sub:External-Stack}
13776
13777 \end_inset
13778
13779
13780 \begin_inset LatexCommand \index{stack}
13781
13782 \end_inset
13783
13784
13785 \begin_inset LatexCommand \index{External stack (mcs51)}
13786
13787 \end_inset
13788
13789
13790 \layout Standard
13791
13792
13793 \series bold
13794 Attention
13795 \series default
13796 : this option wasn't maintained for a long time and is quite buggy.
13797  Small programs might work.
13798  You've been warned!
13799 \layout Standard
13800
13801 The external stack (-
13802 \begin_inset ERT
13803 status Collapsed
13804
13805 \layout Standard
13806
13807 \backslash
13808 /
13809 \end_inset
13810
13811 -xstack option
13812 \begin_inset LatexCommand \index{-\/-xstack}
13813
13814 \end_inset
13815
13816 ) is located in pdata
13817 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
13818
13819 \end_inset
13820
13821  memory (usually at the start of the external ram segment) and is 256 bytes
13822  in size.
13823  When -
13824 \begin_inset ERT
13825 status Collapsed
13826
13827 \layout Standard
13828
13829 \backslash
13830 /
13831 \end_inset
13832
13833 -xstack option is used to compile the program, the parameters and local
13834  variables
13835 \begin_inset LatexCommand \index{local variables}
13836
13837 \end_inset
13838
13839  of all reentrant functions are allocated in this area.
13840  This option is provided for programs with large stack space requirements.
13841  When used with the -
13842 \begin_inset ERT
13843 status Collapsed
13844
13845 \layout Standard
13846
13847 \backslash
13848 /
13849 \end_inset
13850
13851 -stack-auto
13852 \begin_inset LatexCommand \index{-\/-stack-auto}
13853
13854 \end_inset
13855
13856  option, all parameters and local variables are allocated on the external
13857  stack (note: support libraries will need to be recompiled with the same
13858  options).
13859 \layout Standard
13860
13861 The compiler outputs the higher order address byte of the external ram segment
13862  into port P2
13863 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
13864
13865 \end_inset
13866
13867  (see also section
13868 \begin_inset LatexCommand \ref{sub:MCS51-variants}
13869
13870 \end_inset
13871
13872 ), therefore when using the External Stack option, this port
13873 \emph on
13874 may not
13875 \emph default
13876  be used by the application program.
13877 \layout Subsection
13878
13879 DS390 Memory Model
13880 \begin_inset LatexCommand \index{Memory model}
13881
13882 \end_inset
13883
13884
13885 \begin_inset LatexCommand \index{DS390 memory model}
13886
13887 \end_inset
13888
13889
13890 \layout Standard
13891
13892 The only model supported is Flat 24
13893 \begin_inset LatexCommand \index{Flat 24 (DS390 memory model)}
13894
13895 \end_inset
13896
13897 .
13898  This generates code for the 24 bit contiguous addressing mode of the Dallas
13899  DS80C390 part.
13900  In this mode, up to four meg of external RAM or code space can be directly
13901  addressed.
13902  See the data sheets at www.dalsemi.com for further information on this part.
13903 \newline
13904
13905 \newline
13906 Note that the compiler does not generate any code to place the processor
13907  into 24 bitmode (although
13908 \emph on
13909 tinibios
13910 \emph default
13911  in the ds390 libraries will do that for you).
13912  If you don't use
13913 \emph on
13914 tinibios
13915 \emph default
13916
13917 \begin_inset LatexCommand \index{Tinibios (DS390)}
13918
13919 \end_inset
13920
13921 , the boot loader or similar code must ensure that the processor is in 24
13922  bit contiguous addressing mode before calling the SDCC startup code.
13923 \newline
13924
13925 \newline
13926 Like the
13927 \emph on
13928 -
13929 \begin_inset ERT
13930 status Collapsed
13931
13932 \layout Standard
13933
13934 \backslash
13935 /
13936 \end_inset
13937
13938 -model-large
13939 \emph default
13940  option, variables will by default be placed into the XDATA segment.
13941
13942 \newline
13943
13944 \newline
13945 Segments may be placed anywhere in the 4 meg address space using the usual
13946  -
13947 \begin_inset ERT
13948 status Collapsed
13949
13950 \layout Standard
13951
13952 \backslash
13953 /
13954 \end_inset
13955
13956 -*-loc options.
13957  Note that if any segments are located above 64K, the -r flag must be passed
13958  to the linker to generate the proper segment relocations, and the Intel
13959  HEX output format must be used.
13960  The -r flag can be passed to the linker by using the option
13961 \emph on
13962 -Wl-r
13963 \emph default
13964  on the SDCC command line.
13965  However, currently the linker can not handle code segments > 64k.
13966 \layout Section
13967
13968 Pragmas
13969 \begin_inset LatexCommand \index{Pragmas}
13970
13971 \end_inset
13972
13973
13974 \layout Standard
13975
13976 SDCC supports the following #pragma directives:
13977 \layout Itemize
13978
13979 save
13980 \begin_inset LatexCommand \index{\#pragma save}
13981
13982 \end_inset
13983
13984  - this will save all current options to the save/restore stack.
13985  See #pragma\SpecialChar ~
13986 restore.
13987 \layout Itemize
13988
13989 restore
13990 \begin_inset LatexCommand \index{\#pragma restore}
13991
13992 \end_inset
13993
13994  - will restore saved options from the last save.
13995  saves & restores can be nested.
13996  SDCC uses a save/restore stack: save pushes current options to the stack,
13997  restore pulls current options from the stack.
13998  See #pragma\SpecialChar ~
13999 save.
14000 \newline
14001
14002 \layout Itemize
14003
14004 callee_saves
14005 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14006
14007 \end_inset
14008
14009
14010 \begin_inset LatexCommand \index{function prologue}
14011
14012 \end_inset
14013
14014  function1[,function2[,function3...]] - The compiler by default uses a caller
14015  saves convention for register saving across function calls, however this
14016  can cause unnecessary register pushing & popping
14017 \begin_inset LatexCommand \index{push/pop}
14018
14019 \end_inset
14020
14021  when calling small functions from larger functions.
14022  This option can be used to switch off the register saving convention for
14023  the function names specified.
14024  The compiler will not save registers when calling these functions, extra
14025  code need to be manually inserted at the entry & exit for these functions
14026  to save & restore the registers used by these functions, this can SUBSTANTIALLY
14027  reduce code & improve run time performance of the generated code.
14028  In the future the compiler (with inter procedural analysis) may be able
14029  to determine the appropriate scheme to use for each function call.
14030  If -
14031 \begin_inset ERT
14032 status Collapsed
14033
14034 \layout Standard
14035
14036 \backslash
14037 /
14038 \end_inset
14039
14040 -callee-saves command line option is used, the function names specified
14041  in #pragma\SpecialChar ~
14042 callee_saves
14043 \begin_inset LatexCommand \index{\#pragma callee\_saves}
14044
14045 \end_inset
14046
14047  is appended to the list of functions specified in the command line.
14048 \layout Itemize
14049
14050 exclude
14051 \begin_inset LatexCommand \index{\#pragma exclude}
14052
14053 \end_inset
14054
14055  none | {acc[,b[,dpl[,dph]]] - The exclude pragma disables the generation
14056  of pairs of push/pop
14057 \begin_inset LatexCommand \index{push/pop}
14058
14059 \end_inset
14060
14061  instructions in
14062 \emph on
14063 I
14064 \emph default
14065 nterrupt
14066 \begin_inset LatexCommand \index{interrupt}
14067
14068 \end_inset
14069
14070
14071 \emph on
14072 S
14073 \emph default
14074 ervice
14075 \emph on
14076 R
14077 \emph default
14078 outines.
14079  The directive should be placed immediately before the ISR function definition
14080  and it affects ALL ISR functions following it.
14081  To enable the normal register saving for ISR functions use #pragma\SpecialChar ~
14082 exclude\SpecialChar ~
14083 none
14084 \begin_inset LatexCommand \index{\#pragma exclude}
14085
14086 \end_inset
14087
14088 .
14089  See also the related keyword _naked
14090 \begin_inset LatexCommand \index{\_naked}
14091
14092 \end_inset
14093
14094 .
14095 \layout Itemize
14096
14097 less_pedantic
14098 \begin_inset LatexCommand \index{\#pragma less\_pedantic}
14099
14100 \end_inset
14101
14102  - the compiler will not warn you anymore for obvious mistakes, you'r on
14103  your own now ;-(
14104 \layout Itemize
14105
14106 nogcse
14107 \begin_inset LatexCommand \index{\#pragma nogcse}
14108
14109 \end_inset
14110
14111  - will stop global common subexpression elimination.
14112 \layout Itemize
14113
14114 noinduction
14115 \begin_inset LatexCommand \index{\#pragma noinduction}
14116
14117 \end_inset
14118
14119  - will stop loop induction optimizations.
14120 \layout Itemize
14121
14122 noinvariant
14123 \begin_inset LatexCommand \index{\#pragma noinvariant}
14124
14125 \end_inset
14126
14127  - will not do loop invariant optimizations.
14128  For more details see Loop Invariants in section
14129 \begin_inset LatexCommand \ref{sub:Loop-Optimizations}
14130
14131 \end_inset
14132
14133 .
14134 \layout Itemize
14135
14136 noiv
14137 \begin_inset LatexCommand \index{\#pragma noiv}
14138
14139 \end_inset
14140
14141  - Do not generate interrupt
14142 \begin_inset LatexCommand \index{interrupt}
14143
14144 \end_inset
14145
14146  vector table entries for all ISR functions defined after the pragma.
14147  This is useful in cases where the interrupt vector table must be defined
14148  manually, or when there is a secondary, manually defined interrupt vector
14149  table (e.g.
14150  for the autovector feature of the Cypress EZ-USB FX2).
14151  More elegantly this can be achieved by obmitting the optional interrupt
14152  number after the interrupt keyword, see section
14153 \begin_inset LatexCommand \ref{sub:Interrupt-Service-Routines}
14154
14155 \end_inset
14156
14157 \SpecialChar ~
14158 about interrupts.
14159 \layout Itemize
14160
14161 nojtbound
14162 \begin_inset LatexCommand \index{\#pragma nojtbound}
14163
14164 \end_inset
14165
14166  - will not generate code for boundary value checking, when switch statements
14167  are turned into jump-tables (dangerous).
14168  For more details see section
14169 \begin_inset LatexCommand \ref{sub:'switch'-Statements}
14170
14171 \end_inset
14172
14173 .
14174 \layout Itemize
14175
14176 noloopreverse
14177 \begin_inset LatexCommand \index{\#pragma noloopreverse}
14178
14179 \end_inset
14180
14181  - Will not do loop reversal optimization
14182 \layout Itemize
14183
14184 nooverlay
14185 \begin_inset LatexCommand \index{\#pragma nooverlay}
14186
14187 \end_inset
14188
14189  - the compiler will not overlay the parameters and local variables of a
14190  function.
14191 \layout Itemize
14192
14193 stackauto
14194 \begin_inset LatexCommand \index{\#pragma stackauto}
14195
14196 \end_inset
14197
14198 - See option -
14199 \begin_inset ERT
14200 status Collapsed
14201
14202 \layout Standard
14203
14204 \backslash
14205 /
14206 \end_inset
14207
14208 -stack-auto
14209 \begin_inset LatexCommand \index{-\/-stack-auto}
14210
14211 \end_inset
14212
14213  and section
14214 \begin_inset LatexCommand \ref{sec:Parameters-and-Local-Variables}
14215
14216 \end_inset
14217
14218  Parameters and Local Variables.
14219 \layout Standard
14220
14221 SDCPP supports the following #pragma directives:
14222 \layout Itemize
14223
14224 preproc_asm
14225 \begin_inset LatexCommand \index{\#pragma preproc\_asm}
14226
14227 \end_inset
14228
14229  (+ | -) - switch _asm _endasm block preprocessing on / off.
14230  Default is on.
14231 \layout Standard
14232
14233 The pragma's are intended to be used to turn-on or off certain optimizations
14234  which might cause the compiler to generate extra stack / data space to
14235  store compiler generated temporary variables.
14236  This usually happens in large functions.
14237  Pragma directives should be used as shown in the following example, they
14238  are used to control options & optimizations for a given function; pragmas
14239  should be placed before and/or after a function, placing pragma's inside
14240  a function body could have unpredictable results.
14241 \layout Verse
14242
14243
14244 \family typewriter
14245 #pragma save
14246 \begin_inset LatexCommand \index{\#pragma save}
14247
14248 \end_inset
14249
14250  \SpecialChar ~
14251 \SpecialChar ~
14252 \SpecialChar ~
14253 \SpecialChar ~
14254 \SpecialChar ~
14255 \SpecialChar ~
14256 \SpecialChar ~
14257 /* save the current settings */
14258 \newline
14259 #pragma nogcse
14260 \begin_inset LatexCommand \index{\#pragma nogcse}
14261
14262 \end_inset
14263
14264  \SpecialChar ~
14265 \SpecialChar ~
14266 \SpecialChar ~
14267 \SpecialChar ~
14268 \SpecialChar ~
14269 /* turnoff global subexpression elimination */
14270 \newline
14271 #pragma noinduction
14272 \begin_inset LatexCommand \index{\#pragma noinduction}
14273
14274 \end_inset
14275
14276  /* turn off induction optimizations */
14277 \newline
14278 int foo ()
14279 \newline
14280 {
14281 \newline
14282 \SpecialChar ~
14283  \SpecialChar ~
14284  ...
14285
14286 \newline
14287 \SpecialChar ~
14288  \SpecialChar ~
14289  /* large code */
14290 \newline
14291 \SpecialChar ~
14292  \SpecialChar ~
14293  ...
14294
14295 \newline
14296 }
14297 \newline
14298 #pragma restore
14299 \begin_inset LatexCommand \index{\#pragma restore}
14300
14301 \end_inset
14302
14303  /* turn the optimizations back on */
14304 \layout Standard
14305
14306 The compiler will generate a warning message when extra space is allocated.
14307  It is strongly recommended that the save and restore pragma's be used when
14308  changing options for a function.
14309 \layout Section
14310
14311 Defines Created by the Compiler
14312 \layout Standard
14313
14314 The compiler creates the following #defines
14315 \begin_inset LatexCommand \index{\#defines}
14316
14317 \end_inset
14318
14319
14320 \begin_inset LatexCommand \index{Defines created by the compiler}
14321
14322 \end_inset
14323
14324 :
14325 \newline
14326
14327 \layout Standard
14328
14329
14330 \begin_inset  Tabular
14331 <lyxtabular version="3" rows="10" columns="2">
14332 <features>
14333 <column alignment="center" valignment="top" leftline="true" width="0">
14334 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
14335 <row topline="true" bottomline="true">
14336 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14337 \begin_inset Text
14338
14339 \layout Standard
14340
14341
14342 \series bold
14343 #define
14344 \end_inset
14345 </cell>
14346 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14347 \begin_inset Text
14348
14349 \layout Standard
14350
14351
14352 \series bold
14353 Description
14354 \end_inset
14355 </cell>
14356 </row>
14357 <row topline="true">
14358 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14359 \begin_inset Text
14360
14361 \layout Standard
14362
14363 SDCC
14364 \begin_inset LatexCommand \index{SDCC}
14365
14366 \end_inset
14367
14368
14369 \end_inset
14370 </cell>
14371 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14372 \begin_inset Text
14373
14374 \layout Standard
14375
14376 this Symbol is always defined
14377 \end_inset
14378 </cell>
14379 </row>
14380 <row topline="true">
14381 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14382 \begin_inset Text
14383
14384 \layout Standard
14385
14386 SDCC_mcs51
14387 \begin_inset LatexCommand \index{SDCC\_mcs51}
14388
14389 \end_inset
14390
14391  or SDCC_ds390
14392 \begin_inset LatexCommand \index{SDCC\_ds390}
14393
14394 \end_inset
14395
14396  or SDCC_z80
14397 \begin_inset LatexCommand \index{SDCC\_z80}
14398
14399 \end_inset
14400
14401 , etc
14402 \end_inset
14403 </cell>
14404 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14405 \begin_inset Text
14406
14407 \layout Standard
14408
14409 depending on the model used (e.g.: -mds390
14410 \end_inset
14411 </cell>
14412 </row>
14413 <row topline="true">
14414 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14415 \begin_inset Text
14416
14417 \layout Standard
14418
14419 __mcs51
14420 \begin_inset LatexCommand \index{\_\_mcs51}
14421
14422 \end_inset
14423
14424 , __ds390
14425 \begin_inset LatexCommand \index{\_\_ds390}
14426
14427 \end_inset
14428
14429 , __hc08
14430 \begin_inset LatexCommand \index{\_\_hc08}
14431
14432 \end_inset
14433
14434 , __z80
14435 \begin_inset LatexCommand \index{\_\_z80}
14436
14437 \end_inset
14438
14439 , etc
14440 \end_inset
14441 </cell>
14442 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14443 \begin_inset Text
14444
14445 \layout Standard
14446
14447 depending on the model used (e.g.
14448  -mz80)
14449 \end_inset
14450 </cell>
14451 </row>
14452 <row topline="true">
14453 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14454 \begin_inset Text
14455
14456 \layout Standard
14457
14458 SDCC_STACK_AUTO
14459 \begin_inset LatexCommand \index{SDCC\_STACK\_AUTO}
14460
14461 \end_inset
14462
14463
14464 \end_inset
14465 </cell>
14466 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14467 \begin_inset Text
14468
14469 \layout Standard
14470
14471 when
14472 \emph on
14473 -
14474 \begin_inset ERT
14475 status Collapsed
14476
14477 \layout Standard
14478
14479 \backslash
14480 /
14481 \end_inset
14482
14483 -stack-auto
14484 \emph default
14485  option is used
14486 \end_inset
14487 </cell>
14488 </row>
14489 <row topline="true">
14490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14491 \begin_inset Text
14492
14493 \layout Standard
14494
14495 SDCC_MODEL_SMALL
14496 \begin_inset LatexCommand \index{SDCC\_MODEL\_SMALL}
14497
14498 \end_inset
14499
14500
14501 \end_inset
14502 </cell>
14503 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14504 \begin_inset Text
14505
14506 \layout Standard
14507
14508 when
14509 \emph on
14510 -
14511 \begin_inset ERT
14512 status Collapsed
14513
14514 \layout Standard
14515
14516 \backslash
14517 /
14518 \end_inset
14519
14520 -model-small
14521 \emph default
14522  is used
14523 \end_inset
14524 </cell>
14525 </row>
14526 <row topline="true">
14527 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14528 \begin_inset Text
14529
14530 \layout Standard
14531
14532 SDCC_MODEL_LARGE
14533 \begin_inset LatexCommand \index{SDCC\_MODEL\_LARGE}
14534
14535 \end_inset
14536
14537
14538 \end_inset
14539 </cell>
14540 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14541 \begin_inset Text
14542
14543 \layout Standard
14544
14545 when
14546 \emph on
14547 -
14548 \begin_inset ERT
14549 status Collapsed
14550
14551 \layout Standard
14552
14553 \backslash
14554 /
14555 \end_inset
14556
14557 -model-large
14558 \emph default
14559  is used
14560 \end_inset
14561 </cell>
14562 </row>
14563 <row topline="true">
14564 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14565 \begin_inset Text
14566
14567 \layout Standard
14568
14569 SDCC_USE_XSTACK
14570 \begin_inset LatexCommand \index{SDCC\_USE\_XSTACK}
14571
14572 \end_inset
14573
14574
14575 \end_inset
14576 </cell>
14577 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14578 \begin_inset Text
14579
14580 \layout Standard
14581
14582 when
14583 \emph on
14584 -
14585 \begin_inset ERT
14586 status Collapsed
14587
14588 \layout Standard
14589
14590 \backslash
14591 /
14592 \end_inset
14593
14594 -xstack
14595 \emph default
14596  option is used
14597 \end_inset
14598 </cell>
14599 </row>
14600 <row topline="true">
14601 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14602 \begin_inset Text
14603
14604 \layout Standard
14605
14606 SDCC_STACK_TENBIT
14607 \begin_inset LatexCommand \index{SDCC\_STACK\_TENBIT}
14608
14609 \end_inset
14610
14611
14612 \end_inset
14613 </cell>
14614 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14615 \begin_inset Text
14616
14617 \layout Standard
14618
14619 when
14620 \emph on
14621 -mds390
14622 \emph default
14623  is used
14624 \end_inset
14625 </cell>
14626 </row>
14627 <row topline="true" bottomline="true">
14628 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
14629 \begin_inset Text
14630
14631 \layout Standard
14632
14633 SDCC_MODEL_FLAT24
14634 \begin_inset LatexCommand \index{SDCC\_MODEL\_FLAT24}
14635
14636 \end_inset
14637
14638
14639 \end_inset
14640 </cell>
14641 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
14642 \begin_inset Text
14643
14644 \layout Standard
14645
14646 when
14647 \emph on
14648 -mds390
14649 \emph default
14650  is used
14651 \end_inset
14652 </cell>
14653 </row>
14654 </lyxtabular>
14655
14656 \end_inset
14657
14658
14659 \layout Chapter
14660
14661 Notes on supported Processors
14662 \layout Section
14663
14664 MCS51 variants
14665 \begin_inset LatexCommand \label{sub:MCS51-variants}
14666
14667 \end_inset
14668
14669
14670 \begin_inset LatexCommand \index{MCS51 variants}
14671
14672 \end_inset
14673
14674
14675 \layout Standard
14676
14677 MCS51 processors are available from many vendors and come in many different
14678  flavours.
14679  While they might differ considerably in respect to Special Function Registers
14680  the core MCS51 is usually not modified or is kept compatible.
14681
14682 \layout Subsection
14683
14684 pdata access by SFR
14685 \layout Standard
14686
14687 With the upcome of devices with internal xdata and flash memory devices
14688  using port P2
14689 \begin_inset LatexCommand \index{P2 (mcs51 sfr)}
14690
14691 \end_inset
14692
14693  as dedicated I/O port is becoming more popular.
14694  Switching the high byte for pdata
14695 \begin_inset LatexCommand \index{pdata (mcs51, ds390 storage class)}
14696
14697 \end_inset
14698
14699  access which was formerly done by port P2 is then achieved by a Special
14700  Function Register
14701 \begin_inset LatexCommand \index{sfr}
14702
14703 \end_inset
14704
14705 .
14706  In well-established MCS51 tradition the address of this
14707 \emph on
14708 sfr
14709 \emph default
14710  is where the chip designers decided to put it.
14711  Needless to say that they didn't agree on a common name either.
14712  So that the startup code can correctly initialize xdata variables, you
14713  should define an sfr with the name _XPAGE
14714 \family typewriter
14715
14716 \begin_inset LatexCommand \index{\_XPAGE (mcs51)}
14717
14718 \end_inset
14719
14720
14721 \family default
14722  at the appropriate location if the default, port P2, is not used for this.
14723  Some examples are:
14724 \layout Verse
14725
14726
14727 \family typewriter
14728 sfr at 0x92 _XPAGE; /* Cypress EZ-USB family */
14729 \layout Verse
14730
14731
14732 \family typewriter
14733 sfr at 0xaf _XPAGE; /* some Silicon Labs (Cygnal) chips */
14734 \layout Verse
14735
14736
14737 \family typewriter
14738 sfr at 0xaa _XPAGE; /* some Silicon Labs (Cygnal) chips */
14739 \layout Standard
14740
14741 For more exotic implementations further customizations may be needed.
14742  See section
14743 \begin_inset LatexCommand \ref{sub:Startup-Code}
14744
14745 \end_inset
14746
14747  for other possibilities.
14748 \layout Subsection
14749
14750 Other Features available by SFR
14751 \layout Standard
14752
14753 Some MCS51 variants offer features like Double DPTR
14754 \begin_inset LatexCommand \index{DPTR}
14755
14756 \end_inset
14757
14758 , multiple DPTR, decrementing DPTR, 16x16 Multiply.
14759  These are currently not used for the MCS51 port.
14760  If you absolutely need them you can fall back to inline assembly or submit
14761  a patch to SDCC.
14762 \layout Section
14763
14764 DS400 port
14765 \layout Standard
14766
14767 The DS80C400 microcontroller has a rich set of peripherals.
14768  In its built-in ROM library it includes functions to access some of the
14769  features, among them is a TCP stack with IP4 and IP6 support.
14770  Library headers (currently in beta status) and other files are provided
14771  at
14772 \size footnotesize
14773
14774 \begin_inset LatexCommand \url{ftp://ftp.dalsemi.com/pub/tini/ds80c400/c_libraries/sdcc/index.html}
14775
14776 \end_inset
14777
14778 .
14779
14780 \layout Section
14781
14782 The Z80 and gbz80 port
14783 \layout Standard
14784
14785 SDCC can target both the Zilog
14786 \begin_inset LatexCommand \index{Z80}
14787
14788 \end_inset
14789
14790  and the Nintendo Gameboy's Z80-like gbz80
14791 \begin_inset LatexCommand \index{gbz80 (GameBoy Z80)}
14792
14793 \end_inset
14794
14795 .
14796  The Z80 port is passed through the same
14797 \emph on
14798 regressions tests
14799 \begin_inset LatexCommand \index{Regression test}
14800
14801 \end_inset
14802
14803
14804 \emph default
14805  as the MCS51 and DS390 ports, so floating point support, support for long
14806  variables and bitfield support is fine.
14807  See mailing lists and forums about interrupt routines.
14808 \layout Standard
14809
14810 As always, the code is the authoritative reference - see z80/ralloc.c and
14811  z80/gen.c.
14812  The stack
14813 \begin_inset LatexCommand \index{stack}
14814
14815 \end_inset
14816
14817  frame is similar to that generated by the IAR Z80 compiler.
14818  IX is used as the base pointer, HL and IY are used as a temporary registers,
14819  and BC and DE are available for holding variables.
14820  Return values
14821 \begin_inset LatexCommand \index{return value}
14822
14823 \end_inset
14824
14825  for the Z80 port are stored in L (one byte), HL (two bytes), or DEHL (four
14826  bytes).
14827  The gbz80 port use the same set of registers for the return values, but
14828  in a different order of significance: E (one byte), DE (two bytes), or
14829  HLDE (four bytes).
14830 \layout Section
14831
14832 The HC08 port
14833 \layout Standard
14834
14835 The port to the Motorola HC08
14836 \begin_inset LatexCommand \index{HC08}
14837
14838 \end_inset
14839
14840  family has been added in October 2003, and is still undergoing some basic
14841  development.
14842  The code generator is complete, but the register allocation is still quite
14843  unoptimized.
14844  Some of the SDCC's standard C library functions have embedded non-HC08
14845  inline assembly and so are not yet usable.
14846 \newline
14847
14848 \newline
14849
14850 \layout Section
14851
14852 The PIC14 port
14853 \layout Standard
14854
14855 The 14bit PIC
14856 \begin_inset LatexCommand \index{PIC14}
14857
14858 \end_inset
14859
14860  port still requires a major effort from the development community.
14861  However it can work for very simple code.
14862 \layout Subsection
14863
14864 C code and 14bit PIC code page
14865 \begin_inset LatexCommand \index{code page (pic14)}
14866
14867 \end_inset
14868
14869  and RAM banks
14870 \begin_inset LatexCommand \index{RAM bank (pic14)}
14871
14872 \end_inset
14873
14874
14875 \layout Standard
14876
14877 The linker organizes allocation for the code page and RAM banks.
14878  It does not have intimate knowledge of the code flow.
14879  It will put all the code section of a single asm file into a single code
14880  page.
14881  In order to make use of multiple code pages, separate asm files must be
14882  used.
14883  The compiler treats all functions of a single C file as being in the same
14884  code page unless it is non static.
14885  The compiler treats all local variables of a single C file as being in
14886  the same RAM bank unless it is an extern.
14887 \newline
14888
14889 \newline
14890 To get the best follow these guide lines:
14891 \layout Enumerate
14892
14893 make local functions static, as non static functions require code page selection
14894  overhead.
14895 \layout Enumerate
14896
14897 Make local variables static as extern variables require RAM bank selection
14898  overhead.
14899 \layout Enumerate
14900
14901 For devices that have multiple code pages it is more efficient to use the
14902  same number of files as pages, i.e.
14903  for the 16F877 use 4 separate files and i.e.
14904  for the 16F874 use 2 separate files.
14905  This way the linker can put the code for each file into different code
14906  pages and the compiler can allocate reusable variables more efficiently
14907  and there's less page selection overhead.
14908  And as for any 8 bit micro (especially for PIC 14 as they have a very simple
14909  instruction set) use 'unsigned char' whereever possible instead of 'int'.
14910 \layout Subsection
14911
14912 Creating a device include file
14913 \layout Standard
14914
14915 For generating a device include file use the support perl script inc2h.pl
14916  kept in directory support/script.
14917 \layout Subsection
14918
14919 Interrupt code
14920 \layout Standard
14921
14922 For the interrupt function, use the keyword 'interrupt'
14923 \begin_inset LatexCommand \index{interrupt}
14924
14925 \end_inset
14926
14927  with level number of 0 (PIC14 only has 1 interrupt so this number is only
14928  there to avoid a syntax error - it ought to be fixed).
14929  E.g.:
14930 \layout Verse
14931
14932
14933 \family typewriter
14934 void Intr(void) interrupt 0
14935 \newline
14936 {
14937 \newline
14938 \SpecialChar ~
14939 \SpecialChar ~
14940 T0IF = 0; /* Clear timer interrupt */
14941 \newline
14942 }
14943 \layout Subsection
14944
14945 Linking and assembling
14946 \layout Standard
14947
14948 For assembling you can use either GPUTILS'
14949 \begin_inset LatexCommand \index{gputils (pic tools)}
14950
14951 \end_inset
14952
14953  gpasm.exe or MPLAB's mpasmwin.exe.
14954  GPUTILS is available from
14955 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
14956
14957 \end_inset
14958
14959 .
14960  For linking you can use either GPUTIL's gplink or MPLAB's mplink.exe.
14961  If you use MPLAB and an interrupt function then the linker script file
14962  vectors section will need to be enlarged to link with mplink.
14963 \newline
14964
14965 \newline
14966 Here is a
14967 \family typewriter
14968 Makefile
14969 \family default
14970  using GPUTILS:
14971 \layout Verse
14972
14973
14974 \family typewriter
14975 .c.o:
14976 \newline
14977 \SpecialChar ~
14978 \SpecialChar ~
14979 \SpecialChar ~
14980 \SpecialChar ~
14981 \SpecialChar ~
14982 \SpecialChar ~
14983 \SpecialChar ~
14984 \SpecialChar ~
14985 sdcc -S -V -mpic14 -p16F877 $<
14986 \newline
14987 \SpecialChar ~
14988 \SpecialChar ~
14989 \SpecialChar ~
14990 \SpecialChar ~
14991 \SpecialChar ~
14992 \SpecialChar ~
14993 \SpecialChar ~
14994 \SpecialChar ~
14995 gpasm -c $*.asm
14996 \newline
14997
14998 \newline
14999 $(PRJ).hex: $(OBJS)
15000 \newline
15001 \SpecialChar ~
15002 \SpecialChar ~
15003 \SpecialChar ~
15004 \SpecialChar ~
15005 \SpecialChar ~
15006 \SpecialChar ~
15007 \SpecialChar ~
15008 \SpecialChar ~
15009 gplink -m -s $(PRJ).lkr -o $(PRJ).hex $(OBJS)
15010 \layout Standard
15011
15012 Here is a
15013 \family typewriter
15014 Makefile
15015 \family default
15016  using MPLAB:
15017 \layout Verse
15018
15019
15020 \family typewriter
15021 .c.o:
15022 \newline
15023 \SpecialChar ~
15024 \SpecialChar ~
15025 \SpecialChar ~
15026 \SpecialChar ~
15027 \SpecialChar ~
15028 \SpecialChar ~
15029 \SpecialChar ~
15030 \SpecialChar ~
15031 sdcc -S -V -mpic14 -p16F877 $<
15032 \newline
15033 \SpecialChar ~
15034 \SpecialChar ~
15035 \SpecialChar ~
15036 \SpecialChar ~
15037 \SpecialChar ~
15038 \SpecialChar ~
15039 \SpecialChar ~
15040 \SpecialChar ~
15041 mpasmwin /q /o $*.asm
15042 \newline
15043
15044 \newline
15045 $(PRJ).hex: $(OBJS)
15046 \newline
15047 \SpecialChar ~
15048 \SpecialChar ~
15049 \SpecialChar ~
15050 \SpecialChar ~
15051 \SpecialChar ~
15052 \SpecialChar ~
15053 \SpecialChar ~
15054 \SpecialChar ~
15055 mplink /v $(PRJ).lkr /m $(PRJ).map /o $(PRJ).hex $(OBJS)
15056 \layout Standard
15057
15058 Please note that indentations within a
15059 \family typewriter
15060  Makefile
15061 \family default
15062  have to be done with a tabulator character.
15063 \layout Section
15064
15065 The PIC16
15066 \begin_inset LatexCommand \index{PIC16}
15067
15068 \end_inset
15069
15070  port
15071 \layout Standard
15072
15073 The PIC16
15074 \begin_inset LatexCommand \index{PIC16}
15075
15076 \end_inset
15077
15078  port is the portion of SDCC that is responsible to produce code for the
15079  Microchip
15080 \begin_inset LatexCommand \index{Microchip}
15081
15082 \end_inset
15083
15084 (TM) microcontrollers with 16 bit core.
15085  Currently this family of microcontrollers contains the PIC18Fxxx and PIC18Fxxxx.
15086 \layout Subsection
15087
15088 Global Options
15089 \layout Standard
15090
15091 PIC16 port supports the standard command line arguments as supposed, with
15092  the exception of certain cases that will be mentioned in the following
15093  list:
15094 \layout List
15095 \labelwidthstring 00.00.0000
15096
15097 -
15098 \begin_inset ERT
15099 status Collapsed
15100
15101 \layout Standard
15102
15103 \backslash
15104 /
15105 \end_inset
15106
15107 -stack-auto Auto variables that are function parameters, will be saved on
15108  stack by default.
15109
15110 \emph on
15111 There is no need to specify this in the command line.
15112 \layout List
15113 \labelwidthstring 00.00.0000
15114
15115 -
15116 \begin_inset ERT
15117 status Collapsed
15118
15119 \layout Standard
15120
15121 \backslash
15122 /
15123 \end_inset
15124
15125 -float-reent All floating point functions are reentrant by default.
15126
15127 \emph on
15128 There is no need to specifiy this in the command line.
15129 \layout List
15130 \labelwidthstring 00.00.0000
15131
15132 -
15133 \begin_inset ERT
15134 status Collapsed
15135
15136 \layout Standard
15137
15138 \backslash
15139 /
15140 \end_inset
15141
15142 -callee-saves See -
15143 \begin_inset ERT
15144 status Collapsed
15145
15146 \layout Standard
15147
15148 \backslash
15149 /
15150 \end_inset
15151
15152 -all-callee-saves
15153 \layout List
15154 \labelwidthstring 00.00.0000
15155
15156 -
15157 \begin_inset ERT
15158 status Collapsed
15159
15160 \layout Standard
15161
15162 \backslash
15163 /
15164 \end_inset
15165
15166 -all-callee-saves All function arguments are passed on stack by default.
15167
15168 \emph on
15169 There is no need to specify this in the command line.
15170 \layout List
15171 \labelwidthstring 00.00.0000
15172
15173 -
15174 \begin_inset ERT
15175 status Collapsed
15176
15177 \layout Standard
15178
15179 \backslash
15180 /
15181 \end_inset
15182
15183 -fommit-frame-pointer Frame pointer will be omitted when the function uses
15184  no local variables.
15185 \layout Subsection
15186
15187 Port Specific Options
15188 \begin_inset LatexCommand \index{Options PIC16}
15189
15190 \end_inset
15191
15192
15193 \layout Standard
15194
15195 The port specific options appear after the global options in the sdcc --help
15196  output.
15197 \layout Subsubsection
15198
15199 General Options
15200 \layout Standard
15201
15202 General options enable certain port features and optimizations.
15203 \layout List
15204 \labelwidthstring 00.00.0000
15205
15206 -
15207 \begin_inset ERT
15208 status Collapsed
15209
15210 \layout Standard
15211
15212 \backslash
15213 /
15214 \end_inset
15215
15216 -pgen-bank Instructs the port to insert BANKSEL directives before instructions
15217  that use the Bank Select Register (BSR).
15218 \layout List
15219 \labelwidthstring 00.00.0000
15220
15221 -
15222 \begin_inset ERT
15223 status Collapsed
15224
15225 \layout Standard
15226
15227 \backslash
15228 /
15229 \end_inset
15230
15231 -pomit-config-words Instructs the port to omit the generation of the configurati
15232 on words.
15233 \layout List
15234 \labelwidthstring 00.00.0000
15235
15236 -
15237 \begin_inset ERT
15238 status Collapsed
15239
15240 \layout Standard
15241
15242 \backslash
15243 /
15244 \end_inset
15245
15246 -pomit-ivt Instructs the port to omit the generation of the interrupt vectors
15247 \layout List
15248 \labelwidthstring 00.00.0000
15249
15250 -
15251 \begin_inset ERT
15252 status Collapsed
15253
15254 \layout Standard
15255
15256 \backslash
15257 /
15258 \end_inset
15259
15260 -pleave-reset-vector Used in conjuction with the previous command, instructs
15261  the port NOT to omit the reset vector.
15262 \layout List
15263 \labelwidthstring 00.00.0000
15264
15265 -
15266 \begin_inset ERT
15267 status Collapsed
15268
15269 \layout Standard
15270
15271 \backslash
15272 /
15273 \end_inset
15274
15275 -stack-model=[model] Used in conjuction with the command above.
15276  Defines the stack model to be used, valid stack models are :
15277 \begin_deeper
15278 \layout List
15279 \labelwidthstring 00.00.0000
15280
15281
15282 \emph on
15283 small
15284 \emph default
15285  Selects small stack model.
15286  8 bit stack and frame pointers.
15287  Supports 256 bytes stack size.
15288 \layout List
15289 \labelwidthstring 00.00.0000
15290
15291
15292 \emph on
15293 large
15294 \emph default
15295  Selects large stack model.
15296  16 bit stack and frame pointers.
15297  Supports 65536 bytes stack size.
15298 \end_deeper
15299 \layout List
15300 \labelwidthstring 00.00.0000
15301
15302 -
15303 \begin_inset ERT
15304 status Collapsed
15305
15306 \layout Standard
15307
15308 \backslash
15309 /
15310 \end_inset
15311
15312 -preplace-udata-with=[kword] Replaces the default udata keyword for allocating
15313  unitialized data variables with [kword].
15314  Valid keywords are: "udata_acs", "udata_shr", "udata_ovr".
15315 \layout List
15316 \labelwidthstring 00.00.0000
15317
15318 -
15319 \begin_inset ERT
15320 status Collapsed
15321
15322 \layout Standard
15323
15324 \backslash
15325 /
15326 \end_inset
15327
15328 -ivt-loc <nnnn> positions the Interrupt Vector Table at location <nnnn>.
15329  Useful for bootloaders.
15330 \layout List
15331 \labelwidthstring 00.00.0000
15332
15333 -
15334 \begin_inset ERT
15335 status Collapsed
15336
15337 \layout Standard
15338
15339 \backslash
15340 /
15341 \end_inset
15342
15343 -asm= sets the full path and name of an external assembler to call.
15344 \layout List
15345 \labelwidthstring 00.00.0000
15346
15347 -
15348 \begin_inset ERT
15349 status Collapsed
15350
15351 \layout Standard
15352
15353 \backslash
15354 /
15355 \end_inset
15356
15357 -link= sets the full path and name of an external linker to call.
15358 \layout Subsubsection
15359
15360 Debugging Options
15361 \layout Standard
15362
15363 Debugging options enable extra debugging information in the output files.
15364 \layout List
15365 \labelwidthstring 00.00.0000
15366
15367 -
15368 \begin_inset ERT
15369 status Collapsed
15370
15371 \layout Standard
15372
15373 \backslash
15374 /
15375 \end_inset
15376
15377 -debug-xtra Similar to -
15378 \begin_inset ERT
15379 status Collapsed
15380
15381 \layout Standard
15382
15383 \backslash
15384 /
15385 \end_inset
15386
15387 -debug
15388 \begin_inset LatexCommand \index{-\/-debug}
15389
15390 \end_inset
15391
15392 , but dumps more information.
15393 \layout List
15394 \labelwidthstring 00.00.0000
15395
15396 -
15397 \begin_inset ERT
15398 status Collapsed
15399
15400 \layout Standard
15401
15402 \backslash
15403 /
15404 \end_inset
15405
15406 -debug-ralloc Force register allocator to dump <source>.d file with debugging
15407  information.
15408  <source> is the name of the file compiled.
15409 \layout List
15410 \labelwidthstring 00.00.0000
15411
15412 -
15413 \begin_inset ERT
15414 status Collapsed
15415
15416 \layout Standard
15417
15418 \backslash
15419 /
15420 \end_inset
15421
15422 -pcode-verbose Enable pcode debugging information in translation.
15423 \layout Subsection
15424
15425 Preprocessor Macros
15426 \layout Standard
15427
15428 PIC16 port defines the following preprocessor macros while translating a
15429  source.
15430 \layout Standard
15431 \align center
15432
15433 \begin_inset  Tabular
15434 <lyxtabular version="3" rows="2" columns="2">
15435 <features>
15436 <column alignment="center" valignment="top" leftline="true" width="0">
15437 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15438 <row topline="true" bottomline="true">
15439 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15440 \begin_inset Text
15441
15442 \layout Standard
15443
15444 Macro
15445 \end_inset
15446 </cell>
15447 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15448 \begin_inset Text
15449
15450 \layout Standard
15451
15452 Description
15453 \end_inset
15454 </cell>
15455 </row>
15456 <row topline="true" bottomline="true">
15457 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15458 \begin_inset Text
15459
15460 \layout Standard
15461
15462 pic18fxxxx
15463 \end_inset
15464 </cell>
15465 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15466 \begin_inset Text
15467
15468 \layout Standard
15469
15470 MCU Identification.
15471
15472 \emph on
15473 xxxx
15474 \emph default
15475  is the microcontrol identification number, i.e.
15476  452, 6620, etc
15477 \end_inset
15478 </cell>
15479 </row>
15480 </lyxtabular>
15481
15482 \end_inset
15483
15484
15485 \layout Subsection
15486
15487 Directories
15488 \layout Standard
15489
15490 PIC16
15491 \begin_inset LatexCommand \index{PIC16}
15492
15493 \end_inset
15494
15495  port uses the following directories for searching header files and libraries.
15496 \layout Standard
15497 \align center
15498
15499 \begin_inset  Tabular
15500 <lyxtabular version="3" rows="3" columns="4">
15501 <features>
15502 <column alignment="center" valignment="top" leftline="true" width="0">
15503 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15504 <column alignment="center" valignment="top" width="0">
15505 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15506 <row topline="true" bottomline="true">
15507 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15508 \begin_inset Text
15509
15510 \layout Standard
15511
15512 Directory
15513 \end_inset
15514 </cell>
15515 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15516 \begin_inset Text
15517
15518 \layout Standard
15519
15520 Description
15521 \end_inset
15522 </cell>
15523 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15524 \begin_inset Text
15525
15526 \layout Standard
15527
15528 Target
15529 \end_inset
15530 </cell>
15531 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15532 \begin_inset Text
15533
15534 \layout Standard
15535
15536 Command prefix
15537 \end_inset
15538 </cell>
15539 </row>
15540 <row topline="true">
15541 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15542 \begin_inset Text
15543
15544 \layout Standard
15545
15546 PREFIX/sdcc/include/pic16
15547 \end_inset
15548 </cell>
15549 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15550 \begin_inset Text
15551
15552 \layout Standard
15553
15554 PIC16 specific headers
15555 \end_inset
15556 </cell>
15557 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15558 \begin_inset Text
15559
15560 \layout Standard
15561
15562 Compiler
15563 \end_inset
15564 </cell>
15565 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15566 \begin_inset Text
15567
15568 \layout Standard
15569
15570 -I
15571 \end_inset
15572 </cell>
15573 </row>
15574 <row topline="true" bottomline="true">
15575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15576 \begin_inset Text
15577
15578 \layout Standard
15579
15580 PREFIX/sdcc/lib/pic16
15581 \end_inset
15582 </cell>
15583 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15584 \begin_inset Text
15585
15586 \layout Standard
15587
15588 PIC16 specific libraries
15589 \end_inset
15590 </cell>
15591 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15592 \begin_inset Text
15593
15594 \layout Standard
15595
15596 Linker
15597 \end_inset
15598 </cell>
15599 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15600 \begin_inset Text
15601
15602 \layout Standard
15603
15604 -L
15605 \end_inset
15606 </cell>
15607 </row>
15608 </lyxtabular>
15609
15610 \end_inset
15611
15612
15613 \layout Subsection
15614
15615 Pragmas
15616 \begin_inset LatexCommand \label{sub:PIC16_Pragmas}
15617
15618 \end_inset
15619
15620
15621 \layout Standard
15622
15623 PIC16 port currently supports the following pragmas:
15624 \layout List
15625 \labelwidthstring 00.00.0000
15626
15627 stack pragma stack forces the code generator to initialize the stack & frame
15628  pointers at a specific address.
15629  This is an adhoc solution since gplink does not support yet stack.
15630  When the gplink issue is resolved the pragma will be deprecated
15631 \begin_inset Foot
15632 collapsed true
15633
15634 \layout Standard
15635
15636
15637 \emph on
15638 It is important to initialize the stack, otherwise strange things can happen.
15639  Stack is not initialized by default because there are some sources that
15640  do not require it.
15641  (like library sources)
15642 \end_inset
15643
15644 .
15645 \newline
15646 The stack pragma should be used only once in a project.
15647  Multiple pragmas may result in indeterminate behaviour of the program.
15648 \layout LyX-Code
15649
15650 Example:
15651 \layout LyX-Code
15652
15653 \layout LyX-Code
15654
15655 /* initializes stack at RAM address 0x5ff */
15656 \layout LyX-Code
15657
15658 #pragma stack 0x5ff
15659 \layout List
15660 \labelwidthstring 00.00.0000
15661
15662 udata pragma udata instructs the compiler to emit code so that linker will
15663  place a variable at a specific memory bank
15664 \layout LyX-Code
15665
15666 Example:
15667 \layout LyX-Code
15668
15669 \layout LyX-Code
15670
15671 /* places variable foo at bank2 */
15672 \layout LyX-Code
15673
15674 #pragma udata bank2 foo
15675 \layout LyX-Code
15676
15677 char foo;
15678 \layout Standard
15679
15680 In order for this pragma to work there are some changes that must be made
15681  in the .lkr script used in link stage.
15682  In the following example a sample .lkr file is shown:
15683 \layout LyX-Code
15684
15685 \layout LyX-Code
15686
15687 // Sample linker script for the PIC18F452 processor
15688 \layout LyX-Code
15689
15690 LIBPATH .
15691 \layout LyX-Code
15692
15693 CODEPAGE   NAME=vectors    START=0x0            END=0x29           PROTECTED
15694 \layout LyX-Code
15695
15696 CODEPAGE   NAME=page       START=0x2A           END=0x7FFF
15697 \layout LyX-Code
15698
15699 CODEPAGE   NAME=idlocs     START=0x200000       END=0x200007       PROTECTED
15700 \layout LyX-Code
15701
15702 CODEPAGE   NAME=config     START=0x300000       END=0x30000D       PROTECTED
15703 \layout LyX-Code
15704
15705 CODEPAGE   NAME=devid      START=0x3FFFFE       END=0x3FFFFF       PROTECTED
15706 \layout LyX-Code
15707
15708 CODEPAGE   NAME=eedata     START=0xF00000       END=0xF000FF       PROTECTED
15709 \layout LyX-Code
15710
15711 ACCESSBANK NAME=accessram  START=0x0            END=0x7F
15712 \layout LyX-Code
15713
15714 \layout LyX-Code
15715
15716 DATABANK   NAME=gpr0       START=0x80           END=0xFF
15717 \layout LyX-Code
15718
15719 DATABANK   NAME=gpr1       START=0x100          END=0x1FF
15720 \layout LyX-Code
15721
15722 DATABANK   NAME=gpr2       START=0x200          END=0x2FF
15723 \layout LyX-Code
15724
15725 DATABANK   NAME=gpr3       START=0x300          END=0x3FF
15726 \layout LyX-Code
15727
15728 DATABANK   NAME=gpr4       START=0x400          END=0x4FF
15729 \layout LyX-Code
15730
15731 DATABANK   NAME=gpr5       START=0x500          END=0x5FF
15732 \layout LyX-Code
15733
15734 ACCESSBANK NAME=accesssfr  START=0xF80          END=0xFFF          PROTECTED
15735 \layout LyX-Code
15736
15737 \layout LyX-Code
15738
15739 SECTION    NAME=CONFIG     ROM=config
15740 \layout LyX-Code
15741
15742 \layout LyX-Code
15743
15744 SECTION    NAME=bank0      RAM=gpr0
15745 \layout LyX-Code
15746
15747 SECTION    NAME=bank1      RAM=gpr1
15748 \layout LyX-Code
15749
15750 SECTION    NAME=bank2      RAM=gpr2
15751 \layout LyX-Code
15752
15753 SECTION    NAME=bank3      RAM=gpr3
15754 \layout LyX-Code
15755
15756 SECTION    NAME=bank4      RAM=gpr4
15757 \layout LyX-Code
15758
15759 SECTION    NAME=bank5      RAM=gpr5
15760 \layout Standard
15761
15762 The linker will recognise the section name set in the pragma statement and
15763  will position the variable at the memory bank set with the RAM field at
15764  the SECTION line in the linker script file.
15765 \layout Subsection
15766
15767 Header Files
15768 \begin_inset LatexCommand \label{sub:PIC16_Header-Files}
15769
15770 \end_inset
15771
15772
15773 \layout Standard
15774
15775 There is one main header file that can be included to the source files using
15776  the pic16 port.
15777  That file is the
15778 \series bold
15779 pic18fregs.h
15780 \series default
15781 .
15782  This header file contains the definitions for the processor special registers,
15783  so it is necessary if the source accesses them.
15784  It can be included by adding the following line in the beginning of the
15785  file:
15786 \layout LyX-Code
15787
15788 #include <pic18fregs.h>
15789 \layout Standard
15790
15791 The specific microcontroller is selected within the pic18fregs.h automatically,
15792  so the same source can be used with a variety of devices.
15793 \layout Subsection
15794
15795 Libraries
15796 \layout Standard
15797
15798 The libraries that PIC16
15799 \begin_inset LatexCommand \index{PIC16}
15800
15801 \end_inset
15802
15803  port depends on are the microcontroller device libraries which contain
15804  the symbol definitions for the microcontroller special function registers.
15805  These libraries have the format pic18fxxxx.lib, where
15806 \emph on
15807 xxxx
15808 \emph default
15809  is the microcontroller identification number.
15810  The specific library is selected automatically by the compiler at link
15811  stage according to the selected device.
15812 \layout Standard
15813
15814 Libraries are created with gplib which is part of the gputils package
15815 \begin_inset LatexCommand \url{http://gputils.sourceforge.net}
15816
15817 \end_inset
15818
15819 .
15820 \layout Subsection
15821
15822 Memory Models
15823 \layout Standard
15824
15825 The following memory models are supported by the PIC16 port:
15826 \layout Itemize
15827
15828 small model
15829 \layout Itemize
15830
15831 large model
15832 \layout Standard
15833
15834 Memory model affects the default size of pointers within the source.
15835  The sizes are shown in the next table:
15836 \layout Standard
15837 \align center
15838
15839 \begin_inset  Tabular
15840 <lyxtabular version="3" rows="3" columns="3">
15841 <features>
15842 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15843 <column alignment="center" valignment="top" leftline="true" width="0">
15844 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
15845 <row topline="true" bottomline="true">
15846 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15847 \begin_inset Text
15848
15849 \layout Standard
15850
15851 Pointer sizes according to memory model
15852 \end_inset
15853 </cell>
15854 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15855 \begin_inset Text
15856
15857 \layout Standard
15858
15859 small model
15860 \end_inset
15861 </cell>
15862 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15863 \begin_inset Text
15864
15865 \layout Standard
15866
15867 large model
15868 \end_inset
15869 </cell>
15870 </row>
15871 <row topline="true" bottomline="true">
15872 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15873 \begin_inset Text
15874
15875 \layout Standard
15876
15877 code pointers
15878 \end_inset
15879 </cell>
15880 <cell multicolumn="1" alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15881 \begin_inset Text
15882
15883 \layout Standard
15884
15885 16-bits
15886 \end_inset
15887 </cell>
15888 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15889 \begin_inset Text
15890
15891 \layout Standard
15892
15893 24-bits
15894 \end_inset
15895 </cell>
15896 </row>
15897 <row topline="true" bottomline="true">
15898 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
15899 \begin_inset Text
15900
15901 \layout Standard
15902
15903 data pointers
15904 \end_inset
15905 </cell>
15906 <cell multicolumn="1" alignment="center" valignment="top" topline="true" bottomline="true" leftline="true" usebox="none">
15907 \begin_inset Text
15908
15909 \layout Standard
15910
15911 16-bits
15912 \end_inset
15913 </cell>
15914 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
15915 \begin_inset Text
15916
15917 \layout Standard
15918
15919 16-bits
15920 \end_inset
15921 </cell>
15922 </row>
15923 </lyxtabular>
15924
15925 \end_inset
15926
15927
15928 \layout Standard
15929
15930 It is advisable that all sources within a project are compiled with the
15931  same memory model.
15932  If one wants to override the default memory model, this can be done by
15933  declaring a pointer as
15934 \series bold
15935 far
15936 \series default
15937  or
15938 \series bold
15939 near
15940 \series default
15941 .
15942  Far selects large memory model's pointers, while near selects small memory
15943  model's pointers.
15944 \layout Standard
15945
15946 The standard device libraries (see
15947 \begin_inset LatexCommand \ref{sub:PIC16_Header-Files}
15948
15949 \end_inset
15950
15951 ) contain no reference to pointers, so they can be used with both memory
15952  models.
15953 \layout Subsection
15954
15955 Stack
15956 \layout Standard
15957
15958 The stack implementation for the PIC16 port uses two indirect registers,
15959  FSR1 and FSR2.
15960 \layout List
15961 \labelwidthstring 00.00.0000
15962
15963 FSR1 is assigned as stack pointer
15964 \layout List
15965 \labelwidthstring 00.00.0000
15966
15967 FSR2 is assigned as frame pointer
15968 \layout Standard
15969
15970 The following stack models are supported by the PIC16 port
15971 \layout Itemize
15972
15973 small model
15974 \layout Itemize
15975
15976 large model
15977 \layout Standard
15978
15979
15980 \noun on
15981 Small
15982 \noun default
15983  model means that only the FSRxL byte is used to access stack and frame,
15984  while
15985 \emph on
15986 \noun on
15987 large
15988 \emph default
15989 \noun default
15990  uses both FSRxL and FSRxH registers.
15991  The following table shows the stack/frame pointers sizes according to stack
15992  model and the maximum space they can address:
15993 \layout Standard
15994 \align center
15995
15996 \begin_inset  Tabular
15997 <lyxtabular version="3" rows="3" columns="3">
15998 <features>
15999 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16000 <column alignment="center" valignment="top" leftline="true" width="0">
16001 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16002 <row topline="true" bottomline="true">
16003 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16004 \begin_inset Text
16005
16006 \layout Standard
16007
16008 Stack & Frame pointer sizes according to stack model
16009 \end_inset
16010 </cell>
16011 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16012 \begin_inset Text
16013
16014 \layout Standard
16015
16016 small
16017 \end_inset
16018 </cell>
16019 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16020 \begin_inset Text
16021
16022 \layout Standard
16023
16024 large
16025 \end_inset
16026 </cell>
16027 </row>
16028 <row topline="true">
16029 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16030 \begin_inset Text
16031
16032 \layout Standard
16033
16034 Stack pointer FSR1
16035 \end_inset
16036 </cell>
16037 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16038 \begin_inset Text
16039
16040 \layout Standard
16041
16042 8-bits
16043 \end_inset
16044 </cell>
16045 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16046 \begin_inset Text
16047
16048 \layout Standard
16049
16050 16-bits
16051 \end_inset
16052 </cell>
16053 </row>
16054 <row topline="true" bottomline="true">
16055 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16056 \begin_inset Text
16057
16058 \layout Standard
16059
16060 Frame pointer FSR2
16061 \end_inset
16062 </cell>
16063 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16064 \begin_inset Text
16065
16066 \layout Standard
16067
16068 8-bits
16069 \end_inset
16070 </cell>
16071 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16072 \begin_inset Text
16073
16074 \layout Standard
16075
16076 16-bits
16077 \end_inset
16078 </cell>
16079 </row>
16080 </lyxtabular>
16081
16082 \end_inset
16083
16084
16085 \layout Standard
16086
16087
16088 \series bold
16089 Currently stack and frame pointers should be initialized explicit by the
16090  user at the desired Data RAM position (see
16091 \begin_inset LatexCommand \ref{sub:PIC16_Pragmas}
16092
16093 \end_inset
16094
16095  Pragma stack).
16096  Uninitialized stack and frame pointers can result in unexpected behavior
16097  of the resulting binary.
16098 \layout Subsection
16099
16100 Function return values
16101 \layout Standard
16102
16103 Return values from functions are placed to the appropriate registers following
16104  a modified Microchip policy optimized for SDCC.
16105  The following table shows these registers:
16106 \layout Standard
16107 \align center
16108
16109 \begin_inset  Tabular
16110 <lyxtabular version="3" rows="6" columns="2">
16111 <features>
16112 <column alignment="center" valignment="top" leftline="true" width="0">
16113 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0">
16114 <row topline="true" bottomline="true">
16115 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16116 \begin_inset Text
16117
16118 \layout Standard
16119
16120 size
16121 \end_inset
16122 </cell>
16123 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16124 \begin_inset Text
16125
16126 \layout Standard
16127
16128 destination register
16129 \end_inset
16130 </cell>
16131 </row>
16132 <row topline="true">
16133 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16134 \begin_inset Text
16135
16136 \layout Standard
16137
16138 8 bits
16139 \end_inset
16140 </cell>
16141 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16142 \begin_inset Text
16143
16144 \layout Standard
16145
16146 WREG
16147 \end_inset
16148 </cell>
16149 </row>
16150 <row topline="true">
16151 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16152 \begin_inset Text
16153
16154 \layout Standard
16155
16156 16 bits
16157 \end_inset
16158 </cell>
16159 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16160 \begin_inset Text
16161
16162 \layout Standard
16163
16164 PRODL:WREG
16165 \end_inset
16166 </cell>
16167 </row>
16168 <row topline="true">
16169 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16170 \begin_inset Text
16171
16172 \layout Standard
16173
16174 24 bits
16175 \end_inset
16176 </cell>
16177 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16178 \begin_inset Text
16179
16180 \layout Standard
16181
16182 PRODH:PRODL:WREG
16183 \end_inset
16184 </cell>
16185 </row>
16186 <row topline="true">
16187 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16188 \begin_inset Text
16189
16190 \layout Standard
16191
16192 32 bits
16193 \end_inset
16194 </cell>
16195 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16196 \begin_inset Text
16197
16198 \layout Standard
16199
16200 FSR0L:PRODH:PRODL:WREG
16201 \end_inset
16202 </cell>
16203 </row>
16204 <row topline="true" bottomline="true">
16205 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
16206 \begin_inset Text
16207
16208 \layout Standard
16209
16210 >32 bits
16211 \end_inset
16212 </cell>
16213 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
16214 \begin_inset Text
16215
16216 \layout Standard
16217
16218 on stack, FSR0 points to the beginning
16219 \end_inset
16220 </cell>
16221 </row>
16222 </lyxtabular>
16223
16224 \end_inset
16225
16226
16227 \layout Subsection
16228
16229 Interrupts
16230 \layout Standard
16231
16232 When entering an interrupt, currently the PIC16
16233 \begin_inset LatexCommand \index{PIC16}
16234
16235 \end_inset
16236
16237  port automatically saves the following registers:
16238 \layout Itemize
16239
16240 WREG
16241 \layout Itemize
16242
16243 STATUS
16244 \layout Itemize
16245
16246 BSR
16247 \layout Itemize
16248
16249 PROD (PRODL and PRODH)
16250 \layout Itemize
16251
16252 FSR0 (FSR0L and FSR0H)
16253 \layout Standard
16254
16255 These registers are restored upon return from the interrupt routine.
16256
16257 \layout Standard
16258
16259 When entering a high priority interrupt WREG, STATUS and BSR are not explicit
16260  saved by software.
16261  The hardware shadow registers for WREG, STATUS and BSR are used in these
16262  cases.
16263 \layout Standard
16264
16265
16266 \begin_inset Foot
16267 collapsed false
16268
16269 \layout Standard
16270
16271 NOTE that when the _naked attribute is specified for an interrupt routine,
16272  then NO registers are stored or restored.
16273 \end_inset
16274
16275 .
16276 \layout Chapter
16277
16278 Debugging with SDCDB
16279 \begin_inset LatexCommand \label{cha:Debugging-with-SDCDB}
16280
16281 \end_inset
16282
16283
16284 \begin_inset LatexCommand \index{sdcdb (debugger)}
16285
16286 \end_inset
16287
16288
16289 \layout Standard
16290
16291 SDCC is distributed with a source level debugger
16292 \begin_inset LatexCommand \index{Debugger}
16293
16294 \end_inset
16295
16296 .
16297  The debugger uses a command line interface, the command repertoire of the
16298  debugger has been kept as close to gdb
16299 \begin_inset LatexCommand \index{gdb}
16300
16301 \end_inset
16302
16303  (the GNU debugger) as possible.
16304  The configuration and build process is part of the standard compiler installati
16305 on, which also builds and installs the debugger in the target directory
16306  specified during configuration.
16307  The debugger allows you debug BOTH at the C source and at the ASM source
16308  level.
16309  Sdcdb is available on Unix platforms only.
16310 \layout Section
16311
16312 Compiling for Debugging
16313 \layout Standard
16314
16315 The -
16316 \begin_inset ERT
16317 status Collapsed
16318
16319 \layout Standard
16320
16321 \backslash
16322 /
16323 \end_inset
16324
16325 -debug
16326 \begin_inset LatexCommand \index{-\/-debug}
16327
16328 \end_inset
16329
16330  option must be specified for all files for which debug information is to
16331  be generated.
16332  The complier generates a .adb file for each of these files.
16333  The linker creates the .cdb
16334 \begin_inset LatexCommand \index{<file>.cdb}
16335
16336 \end_inset
16337
16338  file from the .adb
16339 \begin_inset LatexCommand \index{<file>.adb}
16340
16341 \end_inset
16342
16343  files and the address information.
16344  This .cdb is used by the debugger.
16345 \layout Section
16346
16347 How the Debugger Works
16348 \layout Standard
16349
16350 When the -
16351 \begin_inset ERT
16352 status Collapsed
16353
16354 \layout Standard
16355
16356 \backslash
16357 /
16358 \end_inset
16359
16360 -debug option is specified the compiler generates extra symbol information
16361  some of which are put into the assembler source and some are put into the
16362  .adb file.
16363   Then the linker creates the .cdb file from the individual .adb files with
16364  the address information for the symbols.
16365  The debugger reads the symbolic information generated by the compiler &
16366  the address information generated by the linker.
16367  It uses the SIMULATOR (Daniel's S51) to execute the program, the program
16368  execution is controlled by the debugger.
16369  When a command is issued for the debugger, it translates it into appropriate
16370  commands for the simulator.
16371 \layout Section
16372
16373 Starting the Debugger
16374 \layout Standard
16375
16376 The debugger can be started using the following command line.
16377  (Assume the file you are debugging has the file name foo).
16378 \newline
16379
16380 \newline
16381
16382 \family sans
16383 \series bold
16384 sdcdb foo
16385 \newline
16386
16387 \family default
16388 \series default
16389
16390 \newline
16391 The debugger will look for the following files.
16392 \layout Itemize
16393
16394 foo.c - the source file.
16395 \layout Itemize
16396
16397 foo.cdb - the debugger symbol information file.
16398 \layout Itemize
16399
16400 foo.ihx - the Intel hex format
16401 \begin_inset LatexCommand \index{Intel hex format}
16402
16403 \end_inset
16404
16405  object file.
16406 \layout Section
16407
16408 Command Line Options.
16409 \layout Itemize
16410
16411 -
16412 \begin_inset ERT
16413 status Collapsed
16414
16415 \layout Standard
16416
16417 \backslash
16418 /
16419 \end_inset
16420
16421 -directory=<source file directory> this option can used to specify the directory
16422  search list.
16423  The debugger will look into the directory list specified for source, cdb
16424  & ihx files.
16425  The items in the directory list must be separated by ':', e.g.
16426  if the source files can be in the directories /home/src1 and /home/src2,
16427  the -
16428 \begin_inset ERT
16429 status Collapsed
16430
16431 \layout Standard
16432
16433 \backslash
16434 /
16435 \end_inset
16436
16437 -directory option should be -
16438 \begin_inset ERT
16439 status Collapsed
16440
16441 \layout Standard
16442
16443 \backslash
16444 /
16445 \end_inset
16446
16447 -directory=/home/src1:/home/src2.
16448  Note there can be no spaces in the option.
16449
16450 \layout Itemize
16451
16452 -cd <directory> - change to the <directory>.
16453 \layout Itemize
16454
16455 -fullname - used by GUI front ends.
16456 \layout Itemize
16457
16458 -cpu <cpu-type> - this argument is passed to the simulator please see the
16459  simulator docs for details.
16460 \layout Itemize
16461
16462 -X <Clock frequency > this options is passed to the simulator please see
16463  the simulator docs for details.
16464 \layout Itemize
16465
16466 -s <serial port file> passed to simulator see the simulator docs for details.
16467 \layout Itemize
16468
16469 -S <serial in,out> passed to simulator see the simulator docs for details.
16470 \layout Itemize
16471
16472 -k <port number> passed to simulator see the simulator docs for details.
16473 \layout Section
16474
16475 Debugger Commands.
16476 \layout Standard
16477
16478 As mentioned earlier the command interface for the debugger has been deliberatel
16479 y kept as close the GNU debugger gdb, as possible.
16480  This will help the integration with existing graphical user interfaces
16481  (like ddd, xxgdb or xemacs) existing for the GNU debugger.
16482  If you use a graphical user interface for the debugger you can skip the
16483  next sections.
16484 \layout Subsubsection*
16485
16486 break [line | file:line | function | file:function]
16487 \layout Standard
16488
16489 Set breakpoint at specified line or function:
16490 \newline
16491
16492 \newline
16493
16494 \family sans
16495 \series bold
16496 sdcdb>break 100
16497 \newline
16498 sdcdb>break foo.c:100
16499 \newline
16500 sdcdb>break funcfoo
16501 \newline
16502 sdcdb>break foo.c:funcfoo
16503 \layout Subsubsection*
16504
16505 clear [line | file:line | function | file:function ]
16506 \layout Standard
16507
16508 Clear breakpoint at specified line or function:
16509 \newline
16510
16511 \newline
16512
16513 \family sans
16514 \series bold
16515 sdcdb>clear 100
16516 \newline
16517 sdcdb>clear foo.c:100
16518 \newline
16519 sdcdb>clear funcfoo
16520 \newline
16521 sdcdb>clear foo.c:funcfoo
16522 \layout Subsubsection*
16523
16524 continue
16525 \layout Standard
16526
16527 Continue program being debugged, after breakpoint.
16528 \layout Subsubsection*
16529
16530 finish
16531 \layout Standard
16532
16533 Execute till the end of the current function.
16534 \layout Subsubsection*
16535
16536 delete [n]
16537 \layout Standard
16538
16539 Delete breakpoint number 'n'.
16540  If used without any option clear ALL user defined break points.
16541 \layout Subsubsection*
16542
16543 info [break | stack | frame | registers ]
16544 \layout Itemize
16545
16546 info break - list all breakpoints
16547 \layout Itemize
16548
16549 info stack - show the function call stack.
16550 \layout Itemize
16551
16552 info frame - show information about the current execution frame.
16553 \layout Itemize
16554
16555 info registers - show content of all registers.
16556 \layout Subsubsection*
16557
16558 step
16559 \layout Standard
16560
16561 Step program until it reaches a different source line.
16562  Note: pressing <return> repeats the last command.
16563 \layout Subsubsection*
16564
16565 next
16566 \layout Standard
16567
16568 Step program, proceeding through subroutine calls.
16569 \layout Subsubsection*
16570
16571 run
16572 \layout Standard
16573
16574 Start debugged program.
16575 \layout Subsubsection*
16576
16577 ptype variable
16578 \layout Standard
16579
16580 Print type information of the variable.
16581 \layout Subsubsection*
16582
16583 print variable
16584 \layout Standard
16585
16586 print value of variable.
16587 \layout Subsubsection*
16588
16589 file filename
16590 \layout Standard
16591
16592 load the given file name.
16593  Note this is an alternate method of loading file for debugging.
16594 \layout Subsubsection*
16595
16596 frame
16597 \layout Standard
16598
16599 print information about current frame.
16600 \layout Subsubsection*
16601
16602 set srcmode
16603 \layout Standard
16604
16605 Toggle between C source & assembly source.
16606 \layout Subsubsection*
16607
16608 ! simulator command
16609 \layout Standard
16610
16611 Send the string following '!' to the simulator, the simulator response is
16612  displayed.
16613  Note the debugger does not interpret the command being sent to the simulator,
16614  so if a command like 'go' is sent the debugger can loose its execution
16615  context and may display incorrect values.
16616 \layout Subsubsection*
16617
16618 quit
16619 \layout Standard
16620
16621 "Watch me now.
16622  Iam going Down.
16623  My name is Bobby Brown"
16624 \layout Section
16625
16626 Interfacing with XEmacs
16627 \begin_inset LatexCommand \index{XEmacs}
16628
16629 \end_inset
16630
16631
16632 \begin_inset LatexCommand \index{Emacs}
16633
16634 \end_inset
16635
16636 .
16637 \layout Standard
16638
16639 Two files (in emacs lisp) are provided for the interfacing with XEmacs,
16640  sdcdb.el and sdcdbsrc.el.
16641  These two files can be found in the $(prefix)/bin directory after the installat
16642 ion is complete.
16643  These files need to be loaded into XEmacs for the interface to work.
16644  This can be done at XEmacs startup time by inserting the following into
16645  your '.xemacs' file (which can be found in your HOME directory):
16646 \newline
16647
16648 \newline
16649
16650 \family typewriter
16651 (load-file sdcdbsrc.el)
16652 \family default
16653
16654 \newline
16655
16656 \newline
16657 .xemacs is a lisp file so the () around the command is REQUIRED.
16658  The files can also be loaded dynamically while XEmacs is running, set the
16659  environment variable 'EMACSLOADPATH' to the installation bin directory
16660  (<installdir>/bin), then enter the following command ESC-x load-file sdcdbsrc.
16661  To start the interface enter the following command:
16662 \newline
16663
16664 \newline
16665
16666 \family sans
16667 \series bold
16668 ESC-x sdcdbsrc
16669 \family default
16670 \series default
16671
16672 \newline
16673
16674 \newline
16675 You will prompted to enter the file name to be debugged.
16676
16677 \newline
16678
16679 \newline
16680 The command line options that are passed to the simulator directly are bound
16681  to default values in the file sdcdbsrc.el.
16682  The variables are listed below, these values maybe changed as required.
16683 \layout Itemize
16684
16685 sdcdbsrc-cpu-type '51
16686 \layout Itemize
16687
16688 sdcdbsrc-frequency '11059200
16689 \layout Itemize
16690
16691 sdcdbsrc-serial nil
16692 \layout Standard
16693
16694 The following is a list of key mapping for the debugger interface.
16695 \layout Standard
16696
16697 \SpecialChar ~
16698
16699 \family typewriter
16700
16701 \newline
16702 ;;\SpecialChar ~
16703 Current Listing ::
16704 \newline
16705 ;;key\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 binding\SpecialChar ~
16720 \SpecialChar ~
16721 \SpecialChar ~
16722 \SpecialChar ~
16723 \SpecialChar ~
16724 \SpecialChar ~
16725 \SpecialChar ~
16726 \SpecialChar ~
16727 \SpecialChar ~
16728 \SpecialChar ~
16729 \SpecialChar ~
16730 \SpecialChar ~
16731 \SpecialChar ~
16732 \SpecialChar ~
16733 \SpecialChar ~
16734 \SpecialChar ~
16735 \SpecialChar ~
16736 \SpecialChar ~
16737 \SpecialChar ~
16738 \SpecialChar ~
16739 \SpecialChar ~
16740 \SpecialChar ~
16741 Comment
16742 \newline
16743 ;;---\SpecialChar ~
16744 \SpecialChar ~
16745 \SpecialChar ~
16746 \SpecialChar ~
16747 \SpecialChar ~
16748 \SpecialChar ~
16749 \SpecialChar ~
16750 \SpecialChar ~
16751 \SpecialChar ~
16752 \SpecialChar ~
16753 \SpecialChar ~
16754 \SpecialChar ~
16755 \SpecialChar ~
16756 \SpecialChar ~
16757 -------\SpecialChar ~
16758 \SpecialChar ~
16759 \SpecialChar ~
16760 \SpecialChar ~
16761 \SpecialChar ~
16762 \SpecialChar ~
16763 \SpecialChar ~
16764 \SpecialChar ~
16765 \SpecialChar ~
16766 \SpecialChar ~
16767 \SpecialChar ~
16768 \SpecialChar ~
16769 \SpecialChar ~
16770 \SpecialChar ~
16771 \SpecialChar ~
16772 \SpecialChar ~
16773 \SpecialChar ~
16774 \SpecialChar ~
16775 \SpecialChar ~
16776 \SpecialChar ~
16777 \SpecialChar ~
16778 \SpecialChar ~
16779 -------
16780 \newline
16781 ;;
16782 \newline
16783 ;;\SpecialChar ~
16784 n\SpecialChar ~
16785 \SpecialChar ~
16786 \SpecialChar ~
16787 \SpecialChar ~
16788 \SpecialChar ~
16789 \SpecialChar ~
16790 \SpecialChar ~
16791 \SpecialChar ~
16792 \SpecialChar ~
16793 \SpecialChar ~
16794 \SpecialChar ~
16795 \SpecialChar ~
16796 \SpecialChar ~
16797 \SpecialChar ~
16798 \SpecialChar ~
16799 sdcdb-next-from-src\SpecialChar ~
16800 \SpecialChar ~
16801 \SpecialChar ~
16802 \SpecialChar ~
16803 \SpecialChar ~
16804 \SpecialChar ~
16805 \SpecialChar ~
16806 \SpecialChar ~
16807 \SpecialChar ~
16808 \SpecialChar ~
16809 SDCDB next command
16810 \newline
16811 ;;\SpecialChar ~
16812 b\SpecialChar ~
16813 \SpecialChar ~
16814 \SpecialChar ~
16815 \SpecialChar ~
16816 \SpecialChar ~
16817 \SpecialChar ~
16818 \SpecialChar ~
16819 \SpecialChar ~
16820 \SpecialChar ~
16821 \SpecialChar ~
16822 \SpecialChar ~
16823 \SpecialChar ~
16824 \SpecialChar ~
16825 \SpecialChar ~
16826 \SpecialChar ~
16827 sdcdb-back-from-src\SpecialChar ~
16828 \SpecialChar ~
16829 \SpecialChar ~
16830 \SpecialChar ~
16831 \SpecialChar ~
16832 \SpecialChar ~
16833 \SpecialChar ~
16834 \SpecialChar ~
16835 \SpecialChar ~
16836 \SpecialChar ~
16837 SDCDB back command
16838 \newline
16839 ;;\SpecialChar ~
16840 c\SpecialChar ~
16841 \SpecialChar ~
16842 \SpecialChar ~
16843 \SpecialChar ~
16844 \SpecialChar ~
16845 \SpecialChar ~
16846 \SpecialChar ~
16847 \SpecialChar ~
16848 \SpecialChar ~
16849 \SpecialChar ~
16850 \SpecialChar ~
16851 \SpecialChar ~
16852 \SpecialChar ~
16853 \SpecialChar ~
16854 \SpecialChar ~
16855 sdcdb-cont-from-src\SpecialChar ~
16856 \SpecialChar ~
16857 \SpecialChar ~
16858 \SpecialChar ~
16859 \SpecialChar ~
16860 \SpecialChar ~
16861 \SpecialChar ~
16862 \SpecialChar ~
16863 \SpecialChar ~
16864 \SpecialChar ~
16865 SDCDB continue command
16866 \newline
16867 ;;\SpecialChar ~
16868 s\SpecialChar ~
16869 \SpecialChar ~
16870 \SpecialChar ~
16871 \SpecialChar ~
16872 \SpecialChar ~
16873 \SpecialChar ~
16874 \SpecialChar ~
16875 \SpecialChar ~
16876 \SpecialChar ~
16877 \SpecialChar ~
16878 \SpecialChar ~
16879 \SpecialChar ~
16880 \SpecialChar ~
16881 \SpecialChar ~
16882 \SpecialChar ~
16883 sdcdb-step-from-src\SpecialChar ~
16884 \SpecialChar ~
16885 \SpecialChar ~
16886 \SpecialChar ~
16887 \SpecialChar ~
16888 \SpecialChar ~
16889 \SpecialChar ~
16890 \SpecialChar ~
16891 \SpecialChar ~
16892 \SpecialChar ~
16893 SDCDB step command
16894 \newline
16895 ;;\SpecialChar ~
16896 ?\SpecialChar ~
16897 \SpecialChar ~
16898 \SpecialChar ~
16899 \SpecialChar ~
16900 \SpecialChar ~
16901 \SpecialChar ~
16902 \SpecialChar ~
16903 \SpecialChar ~
16904 \SpecialChar ~
16905 \SpecialChar ~
16906 \SpecialChar ~
16907 \SpecialChar ~
16908 \SpecialChar ~
16909 \SpecialChar ~
16910 \SpecialChar ~
16911 sdcdb-whatis-c-sexp\SpecialChar ~
16912 \SpecialChar ~
16913 \SpecialChar ~
16914 \SpecialChar ~
16915 \SpecialChar ~
16916 \SpecialChar ~
16917 \SpecialChar ~
16918 \SpecialChar ~
16919 \SpecialChar ~
16920 \SpecialChar ~
16921 SDCDB ptypecommand for data at
16922 \newline
16923 ;;\SpecialChar ~
16924 \SpecialChar ~
16925 \SpecialChar ~
16926 \SpecialChar ~
16927 \SpecialChar ~
16928 \SpecialChar ~
16929 \SpecialChar ~
16930 \SpecialChar ~
16931 \SpecialChar ~
16932 \SpecialChar ~
16933 \SpecialChar ~
16934 \SpecialChar ~
16935 \SpecialChar ~
16936 \SpecialChar ~
16937 \SpecialChar ~
16938 \SpecialChar ~
16939 \SpecialChar ~
16940 \SpecialChar ~
16941 \SpecialChar ~
16942 \SpecialChar ~
16943 \SpecialChar ~
16944 \SpecialChar ~
16945 \SpecialChar ~
16946 \SpecialChar ~
16947 \SpecialChar ~
16948 \SpecialChar ~
16949 \SpecialChar ~
16950 \SpecialChar ~
16951 \SpecialChar ~
16952 \SpecialChar ~
16953 \SpecialChar ~
16954 \SpecialChar ~
16955 \SpecialChar ~
16956 \SpecialChar ~
16957 \SpecialChar ~
16958 \SpecialChar ~
16959 \SpecialChar ~
16960 \SpecialChar ~
16961 \SpecialChar ~
16962 \SpecialChar ~
16963 \SpecialChar ~
16964 \SpecialChar ~
16965 \SpecialChar ~
16966 \SpecialChar ~
16967 \SpecialChar ~
16968 \SpecialChar ~
16969 \SpecialChar ~
16970 buffer point
16971 \newline
16972 ;;\SpecialChar ~
16973 x\SpecialChar ~
16974 \SpecialChar ~
16975 \SpecialChar ~
16976 \SpecialChar ~
16977 \SpecialChar ~
16978 \SpecialChar ~
16979 \SpecialChar ~
16980 \SpecialChar ~
16981 \SpecialChar ~
16982 \SpecialChar ~
16983 \SpecialChar ~
16984 \SpecialChar ~
16985 \SpecialChar ~
16986 \SpecialChar ~
16987 \SpecialChar ~
16988 sdcdbsrc-delete\SpecialChar ~
16989 \SpecialChar ~
16990 \SpecialChar ~
16991 \SpecialChar ~
16992 \SpecialChar ~
16993 \SpecialChar ~
16994 \SpecialChar ~
16995 \SpecialChar ~
16996 \SpecialChar ~
16997 \SpecialChar ~
16998 \SpecialChar ~
16999 \SpecialChar ~
17000 \SpecialChar ~
17001 \SpecialChar ~
17002 SDCDB Delete all breakpoints if no arg
17003 \newline
17004 ;;\SpecialChar ~
17005 \SpecialChar ~
17006 \SpecialChar ~
17007 \SpecialChar ~
17008 \SpecialChar ~
17009 \SpecialChar ~
17010 \SpecialChar ~
17011 \SpecialChar ~
17012 \SpecialChar ~
17013 \SpecialChar ~
17014 \SpecialChar ~
17015 \SpecialChar ~
17016 \SpecialChar ~
17017 \SpecialChar ~
17018 \SpecialChar ~
17019 \SpecialChar ~
17020 \SpecialChar ~
17021 \SpecialChar ~
17022 \SpecialChar ~
17023 \SpecialChar ~
17024 \SpecialChar ~
17025 \SpecialChar ~
17026 \SpecialChar ~
17027 \SpecialChar ~
17028 \SpecialChar ~
17029 \SpecialChar ~
17030 \SpecialChar ~
17031 \SpecialChar ~
17032 \SpecialChar ~
17033 \SpecialChar ~
17034 \SpecialChar ~
17035 \SpecialChar ~
17036 \SpecialChar ~
17037 \SpecialChar ~
17038 \SpecialChar ~
17039 \SpecialChar ~
17040 \SpecialChar ~
17041 \SpecialChar ~
17042 \SpecialChar ~
17043 \SpecialChar ~
17044 \SpecialChar ~
17045 \SpecialChar ~
17046 \SpecialChar ~
17047 \SpecialChar ~
17048 \SpecialChar ~
17049 \SpecialChar ~
17050 \SpecialChar ~
17051 given or delete arg (C-u arg x)
17052 \newline
17053 ;;\SpecialChar ~
17054 m\SpecialChar ~
17055 \SpecialChar ~
17056 \SpecialChar ~
17057 \SpecialChar ~
17058 \SpecialChar ~
17059 \SpecialChar ~
17060 \SpecialChar ~
17061 \SpecialChar ~
17062 \SpecialChar ~
17063 \SpecialChar ~
17064 \SpecialChar ~
17065 \SpecialChar ~
17066 \SpecialChar ~
17067 \SpecialChar ~
17068 \SpecialChar ~
17069 sdcdbsrc-frame\SpecialChar ~
17070 \SpecialChar ~
17071 \SpecialChar ~
17072 \SpecialChar ~
17073 \SpecialChar ~
17074 \SpecialChar ~
17075 \SpecialChar ~
17076 \SpecialChar ~
17077 \SpecialChar ~
17078 \SpecialChar ~
17079 \SpecialChar ~
17080 \SpecialChar ~
17081 \SpecialChar ~
17082 \SpecialChar ~
17083 \SpecialChar ~
17084 SDCDB Display current frame if no arg,
17085 \newline
17086 ;;\SpecialChar ~
17087 \SpecialChar ~
17088 \SpecialChar ~
17089 \SpecialChar ~
17090 \SpecialChar ~
17091 \SpecialChar ~
17092 \SpecialChar ~
17093 \SpecialChar ~
17094 \SpecialChar ~
17095 \SpecialChar ~
17096 \SpecialChar ~
17097 \SpecialChar ~
17098 \SpecialChar ~
17099 \SpecialChar ~
17100 \SpecialChar ~
17101 \SpecialChar ~
17102 \SpecialChar ~
17103 \SpecialChar ~
17104 \SpecialChar ~
17105 \SpecialChar ~
17106 \SpecialChar ~
17107 \SpecialChar ~
17108 \SpecialChar ~
17109 \SpecialChar ~
17110 \SpecialChar ~
17111 \SpecialChar ~
17112 \SpecialChar ~
17113 \SpecialChar ~
17114 \SpecialChar ~
17115 \SpecialChar ~
17116 \SpecialChar ~
17117 \SpecialChar ~
17118 \SpecialChar ~
17119 \SpecialChar ~
17120 \SpecialChar ~
17121 \SpecialChar ~
17122 \SpecialChar ~
17123 \SpecialChar ~
17124 \SpecialChar ~
17125 \SpecialChar ~
17126 \SpecialChar ~
17127 \SpecialChar ~
17128 \SpecialChar ~
17129 \SpecialChar ~
17130 \SpecialChar ~
17131 \SpecialChar ~
17132 \SpecialChar ~
17133 given or display frame arg
17134 \newline
17135 ;;\SpecialChar ~
17136 \SpecialChar ~
17137 \SpecialChar ~
17138 \SpecialChar ~
17139 \SpecialChar ~
17140 \SpecialChar ~
17141 \SpecialChar ~
17142 \SpecialChar ~
17143 \SpecialChar ~
17144 \SpecialChar ~
17145 \SpecialChar ~
17146 \SpecialChar ~
17147 \SpecialChar ~
17148 \SpecialChar ~
17149 \SpecialChar ~
17150 \SpecialChar ~
17151 \SpecialChar ~
17152 \SpecialChar ~
17153 \SpecialChar ~
17154 \SpecialChar ~
17155 \SpecialChar ~
17156 \SpecialChar ~
17157 \SpecialChar ~
17158 \SpecialChar ~
17159 \SpecialChar ~
17160 \SpecialChar ~
17161 \SpecialChar ~
17162 \SpecialChar ~
17163 \SpecialChar ~
17164 \SpecialChar ~
17165 \SpecialChar ~
17166 \SpecialChar ~
17167 \SpecialChar ~
17168 \SpecialChar ~
17169 \SpecialChar ~
17170 \SpecialChar ~
17171 \SpecialChar ~
17172 \SpecialChar ~
17173 \SpecialChar ~
17174 \SpecialChar ~
17175 \SpecialChar ~
17176 \SpecialChar ~
17177 \SpecialChar ~
17178 \SpecialChar ~
17179 \SpecialChar ~
17180 \SpecialChar ~
17181 \SpecialChar ~
17182 buffer point
17183 \newline
17184 ;;\SpecialChar ~
17185 !\SpecialChar ~
17186 \SpecialChar ~
17187 \SpecialChar ~
17188 \SpecialChar ~
17189 \SpecialChar ~
17190 \SpecialChar ~
17191 \SpecialChar ~
17192 \SpecialChar ~
17193 \SpecialChar ~
17194 \SpecialChar ~
17195 \SpecialChar ~
17196 \SpecialChar ~
17197 \SpecialChar ~
17198 \SpecialChar ~
17199 \SpecialChar ~
17200 sdcdbsrc-goto-sdcdb\SpecialChar ~
17201 \SpecialChar ~
17202 \SpecialChar ~
17203 \SpecialChar ~
17204 \SpecialChar ~
17205 \SpecialChar ~
17206 \SpecialChar ~
17207 \SpecialChar ~
17208 \SpecialChar ~
17209 \SpecialChar ~
17210 Goto the SDCDB output buffer
17211 \newline
17212 ;;\SpecialChar ~
17213 p\SpecialChar ~
17214 \SpecialChar ~
17215 \SpecialChar ~
17216 \SpecialChar ~
17217 \SpecialChar ~
17218 \SpecialChar ~
17219 \SpecialChar ~
17220 \SpecialChar ~
17221 \SpecialChar ~
17222 \SpecialChar ~
17223 \SpecialChar ~
17224 \SpecialChar ~
17225 \SpecialChar ~
17226 \SpecialChar ~
17227 \SpecialChar ~
17228 sdcdb-print-c-sexp\SpecialChar ~
17229 \SpecialChar ~
17230 \SpecialChar ~
17231 \SpecialChar ~
17232 \SpecialChar ~
17233 \SpecialChar ~
17234 \SpecialChar ~
17235 \SpecialChar ~
17236 \SpecialChar ~
17237 \SpecialChar ~
17238 \SpecialChar ~
17239 SDCDB print command for data at
17240 \newline
17241 ;;\SpecialChar ~
17242 \SpecialChar ~
17243 \SpecialChar ~
17244 \SpecialChar ~
17245 \SpecialChar ~
17246 \SpecialChar ~
17247 \SpecialChar ~
17248 \SpecialChar ~
17249 \SpecialChar ~
17250 \SpecialChar ~
17251 \SpecialChar ~
17252 \SpecialChar ~
17253 \SpecialChar ~
17254 \SpecialChar ~
17255 \SpecialChar ~
17256 \SpecialChar ~
17257 \SpecialChar ~
17258 \SpecialChar ~
17259 \SpecialChar ~
17260 \SpecialChar ~
17261 \SpecialChar ~
17262 \SpecialChar ~
17263 \SpecialChar ~
17264 \SpecialChar ~
17265 \SpecialChar ~
17266 \SpecialChar ~
17267 \SpecialChar ~
17268 \SpecialChar ~
17269 \SpecialChar ~
17270 \SpecialChar ~
17271 \SpecialChar ~
17272 \SpecialChar ~
17273 \SpecialChar ~
17274 \SpecialChar ~
17275 \SpecialChar ~
17276 \SpecialChar ~
17277 \SpecialChar ~
17278 \SpecialChar ~
17279 \SpecialChar ~
17280 \SpecialChar ~
17281 \SpecialChar ~
17282 \SpecialChar ~
17283 \SpecialChar ~
17284 \SpecialChar ~
17285 \SpecialChar ~
17286 \SpecialChar ~
17287 \SpecialChar ~
17288 buffer point
17289 \newline
17290 ;;\SpecialChar ~
17291 g\SpecialChar ~
17292 \SpecialChar ~
17293 \SpecialChar ~
17294 \SpecialChar ~
17295 \SpecialChar ~
17296 \SpecialChar ~
17297 \SpecialChar ~
17298 \SpecialChar ~
17299 \SpecialChar ~
17300 \SpecialChar ~
17301 \SpecialChar ~
17302 \SpecialChar ~
17303 \SpecialChar ~
17304 \SpecialChar ~
17305 \SpecialChar ~
17306 sdcdbsrc-goto-sdcdb\SpecialChar ~
17307 \SpecialChar ~
17308 \SpecialChar ~
17309 \SpecialChar ~
17310 \SpecialChar ~
17311 \SpecialChar ~
17312 \SpecialChar ~
17313 \SpecialChar ~
17314 \SpecialChar ~
17315 \SpecialChar ~
17316 Goto the SDCDB output buffer
17317 \newline
17318 ;;\SpecialChar ~
17319 t\SpecialChar ~
17320 \SpecialChar ~
17321 \SpecialChar ~
17322 \SpecialChar ~
17323 \SpecialChar ~
17324 \SpecialChar ~
17325 \SpecialChar ~
17326 \SpecialChar ~
17327 \SpecialChar ~
17328 \SpecialChar ~
17329 \SpecialChar ~
17330 \SpecialChar ~
17331 \SpecialChar ~
17332 \SpecialChar ~
17333 \SpecialChar ~
17334 sdcdbsrc-mode\SpecialChar ~
17335 \SpecialChar ~
17336 \SpecialChar ~
17337 \SpecialChar ~
17338 \SpecialChar ~
17339 \SpecialChar ~
17340 \SpecialChar ~
17341 \SpecialChar ~
17342 \SpecialChar ~
17343 \SpecialChar ~
17344 \SpecialChar ~
17345 \SpecialChar ~
17346 \SpecialChar ~
17347 \SpecialChar ~
17348 \SpecialChar ~
17349 \SpecialChar ~
17350 Toggles Sdcdbsrc mode (turns it off)
17351 \newline
17352 ;;
17353 \newline
17354 ;;\SpecialChar ~
17355 C-c\SpecialChar ~
17356 C-f\SpecialChar ~
17357 \SpecialChar ~
17358 \SpecialChar ~
17359 \SpecialChar ~
17360 \SpecialChar ~
17361 \SpecialChar ~
17362 \SpecialChar ~
17363 \SpecialChar ~
17364 \SpecialChar ~
17365 sdcdb-finish-from-src\SpecialChar ~
17366 \SpecialChar ~
17367 \SpecialChar ~
17368 \SpecialChar ~
17369 \SpecialChar ~
17370 \SpecialChar ~
17371 \SpecialChar ~
17372 \SpecialChar ~
17373 SDCDB finish command
17374 \newline
17375 ;;
17376 \newline
17377 ;;\SpecialChar ~
17378 C-x\SpecialChar ~
17379 SPC\SpecialChar ~
17380 \SpecialChar ~
17381 \SpecialChar ~
17382 \SpecialChar ~
17383 \SpecialChar ~
17384 \SpecialChar ~
17385 \SpecialChar ~
17386 \SpecialChar ~
17387 \SpecialChar ~
17388 sdcdb-break\SpecialChar ~
17389 \SpecialChar ~
17390 \SpecialChar ~
17391 \SpecialChar ~
17392 \SpecialChar ~
17393 \SpecialChar ~
17394 \SpecialChar ~
17395 \SpecialChar ~
17396 \SpecialChar ~
17397 \SpecialChar ~
17398 \SpecialChar ~
17399 \SpecialChar ~
17400 \SpecialChar ~
17401 \SpecialChar ~
17402 \SpecialChar ~
17403 \SpecialChar ~
17404 \SpecialChar ~
17405 \SpecialChar ~
17406 Set break for line with point
17407 \newline
17408 ;;\SpecialChar ~
17409 ESC\SpecialChar ~
17410 t\SpecialChar ~
17411 \SpecialChar ~
17412 \SpecialChar ~
17413 \SpecialChar ~
17414 \SpecialChar ~
17415 \SpecialChar ~
17416 \SpecialChar ~
17417 \SpecialChar ~
17418 \SpecialChar ~
17419 \SpecialChar ~
17420 \SpecialChar ~
17421 sdcdbsrc-mode\SpecialChar ~
17422 \SpecialChar ~
17423 \SpecialChar ~
17424 \SpecialChar ~
17425 \SpecialChar ~
17426 \SpecialChar ~
17427 \SpecialChar ~
17428 \SpecialChar ~
17429 \SpecialChar ~
17430 \SpecialChar ~
17431 \SpecialChar ~
17432 \SpecialChar ~
17433 \SpecialChar ~
17434 \SpecialChar ~
17435 \SpecialChar ~
17436 \SpecialChar ~
17437 Toggle Sdcdbsrc mode
17438 \newline
17439 ;;\SpecialChar ~
17440 ESC\SpecialChar ~
17441 m\SpecialChar ~
17442 \SpecialChar ~
17443 \SpecialChar ~
17444 \SpecialChar ~
17445 \SpecialChar ~
17446 \SpecialChar ~
17447 \SpecialChar ~
17448 \SpecialChar ~
17449 \SpecialChar ~
17450 \SpecialChar ~
17451 \SpecialChar ~
17452 sdcdbsrc-srcmode\SpecialChar ~
17453 \SpecialChar ~
17454 \SpecialChar ~
17455 \SpecialChar ~
17456 \SpecialChar ~
17457 \SpecialChar ~
17458 \SpecialChar ~
17459 \SpecialChar ~
17460 \SpecialChar ~
17461 \SpecialChar ~
17462 \SpecialChar ~
17463 \SpecialChar ~
17464 \SpecialChar ~
17465 Toggle list mode
17466 \newline
17467 ;;
17468 \newline
17469
17470 \layout Chapter
17471 \pagebreak_top
17472 TIPS
17473 \layout Standard
17474
17475 Here are a few guidelines that will help the compiler generate more efficient
17476  code, some of the tips are specific to this compiler others are generally
17477  good programming practice.
17478 \layout Itemize
17479
17480 Use the smallest data type to represent your data-value.
17481  If it is known in advance that the value is going to be less than 256 then
17482  use an 'unsigned char' instead of a 'short' or 'int'.
17483  Please note, that ANSI C requires both signed and unsigned chars to be
17484  promoted to 'signed int' before doing any operation.
17485  This promotion can be omitted, if the result is the same.
17486  The effect of the promotion rules together with the sign-extension is often
17487  surprising:
17488 \begin_deeper
17489 \layout Verse
17490
17491
17492 \family typewriter
17493 unsigned char uc = 0xfe;
17494 \newline
17495 if (uc * uc < 0) /* this is true! */
17496 \newline
17497 {
17498 \newline
17499 \SpecialChar ~
17500 \SpecialChar ~
17501 \SpecialChar ~
17502 \SpecialChar ~
17503 ....
17504 \newline
17505 }
17506 \layout Standard
17507
17508
17509 \family typewriter
17510 uc * uc
17511 \family default
17512  is evaluated as
17513 \family typewriter
17514 (int) uc * (int) uc = (int) 0xfe * (int) 0xfe = (int) 0xfc04 = -1024
17515 \family default
17516 .
17517
17518 \newline
17519 Another one:
17520 \layout Verse
17521
17522
17523 \family typewriter
17524 (unsigned char) -12 / (signed char) -3 = ...
17525 \layout Standard
17526
17527 No, the result is not 4:
17528 \layout Verse
17529
17530
17531 \family typewriter
17532 (int) (unsigned char) -12 / (int) (signed char) -3 =
17533 \newline
17534 (int) (unsigned char) 0xf4 / (int) (signed char) 0xfd =
17535 \newline
17536 (int) 0x00f4 / (int) 0xfffd =
17537 \newline
17538 (int) 0x00f4 / (int) 0xfffd =
17539 \newline
17540 (int) 244 / (int) -3 =
17541 \newline
17542 (int) -81 = (int) 0xffaf;
17543 \layout Standard
17544
17545 Don't complain, that gcc gives you a different result.
17546  gcc uses 32 bit ints, while SDCC uses 16 bit ints.
17547  Therefore the results are different.
17548 \newline
17549 From
17550 \begin_inset Quotes sld
17551 \end_inset
17552
17553 comp.lang.c FAQ
17554 \begin_inset Quotes srd
17555 \end_inset
17556
17557 :
17558 \layout Quote
17559
17560 If well-defined overflow characteristics are important and negative values
17561  are not, or if you want to steer clear of sign-extension problems when
17562  manipulating bits or bytes, use one of the corresponding unsigned types.
17563  (Beware when mixing signed and unsigned values in expressions, though.)
17564 \newline
17565 Although character types (especially unsigned char) can be used as "tiny"
17566  integers, doing so is sometimes more trouble than it's worth, due to unpredicta
17567 ble sign extension and increased code size.
17568 \end_deeper
17569 \layout Itemize
17570
17571 Use unsigned when it is known in advance that the value is not going to
17572  be negative.
17573  This helps especially if you are doing division or multiplication, bit-shifting
17574  or are using an array index.
17575 \layout Itemize
17576
17577 NEVER jump into a LOOP.
17578 \layout Itemize
17579
17580 Declare the variables to be local
17581 \begin_inset LatexCommand \index{local variables}
17582
17583 \end_inset
17584
17585  whenever possible, especially loop control variables (induction).
17586 \layout Itemize
17587
17588 Since the compiler does not always do implicit integral promotion, the programme
17589 r should do an explicit cast when integral promotion is required.
17590 \layout Itemize
17591
17592 Reducing the size of division, multiplication & modulus operations can reduce
17593  code size substantially.
17594  Take the following code for example.
17595 \begin_deeper
17596 \layout Verse
17597
17598
17599 \family typewriter
17600 foobar(unsigned int p1, unsigned char ch)
17601 \newline
17602 {
17603 \newline
17604 \SpecialChar ~
17605 \SpecialChar ~
17606 \SpecialChar ~
17607 \SpecialChar ~
17608 unsigned char ch1 = p1 % ch ;
17609 \newline
17610 \SpecialChar ~
17611 \SpecialChar ~
17612 \SpecialChar ~
17613 \SpecialChar ~
17614 ....
17615 \newline
17616 }
17617 \layout Standard
17618
17619 For the modulus operation the variable ch will be promoted to unsigned int
17620  first then the modulus operation will be performed (this will lead to a
17621  call to support routine _moduint()), and the result will be casted to a
17622  char.
17623  If the code is changed to
17624 \layout Verse
17625
17626
17627 \family typewriter
17628 foobar(unsigned int p1, unsigned char ch)
17629 \newline
17630 {
17631 \newline
17632 \SpecialChar ~
17633 \SpecialChar ~
17634 \SpecialChar ~
17635 \SpecialChar ~
17636 unsigned char ch1 = (unsigned char)p1 % ch ;
17637 \newline
17638 \SpecialChar ~
17639 \SpecialChar ~
17640 \SpecialChar ~
17641 \SpecialChar ~
17642 ....
17643 \newline
17644 }
17645 \layout Standard
17646
17647 It would substantially reduce the code generated (future versions of the
17648  compiler will be smart enough to detect such optimization opportunities).
17649 \end_deeper
17650 \layout Itemize
17651
17652 Have a look at the assembly listing to get a
17653 \begin_inset Quotes sld
17654 \end_inset
17655
17656 feeling
17657 \begin_inset Quotes srd
17658 \end_inset
17659
17660  for the code generation.
17661 \layout Section
17662
17663 Tools
17664 \begin_inset LatexCommand \index{Tools}
17665
17666 \end_inset
17667
17668  included in the distribution
17669 \layout Standard
17670 \align center
17671
17672 \begin_inset  Tabular
17673 <lyxtabular version="3" rows="12" columns="3">
17674 <features>
17675 <column alignment="center" valignment="top" leftline="true" width="0pt">
17676 <column alignment="center" valignment="top" leftline="true" width="0pt">
17677 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
17678 <row topline="true" bottomline="true">
17679 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17680 \begin_inset Text
17681
17682 \layout Standard
17683
17684 Name
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 Purpose
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 Directory
17701 \end_inset
17702 </cell>
17703 </row>
17704 <row topline="true">
17705 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17706 \begin_inset Text
17707
17708 \layout Standard
17709
17710 uCsim
17711 \end_inset
17712 </cell>
17713 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17714 \begin_inset Text
17715
17716 \layout Standard
17717
17718 Simulator for various architectures
17719 \end_inset
17720 </cell>
17721 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17722 \begin_inset Text
17723
17724 \layout Standard
17725
17726 sdcc/sim/ucsim
17727 \end_inset
17728 </cell>
17729 </row>
17730 <row topline="true">
17731 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17732 \begin_inset Text
17733
17734 \layout Standard
17735
17736 keil2sdcc.pl
17737 \end_inset
17738 </cell>
17739 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17740 \begin_inset Text
17741
17742 \layout Standard
17743
17744 header file conversion
17745 \end_inset
17746 </cell>
17747 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17748 \begin_inset Text
17749
17750 \layout Standard
17751
17752 sdcc/support/scripts
17753 \end_inset
17754 </cell>
17755 </row>
17756 <row topline="true">
17757 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17758 \begin_inset Text
17759
17760 \layout Standard
17761
17762 mh2h.c
17763 \end_inset
17764 </cell>
17765 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17766 \begin_inset Text
17767
17768 \layout Standard
17769
17770 header file conversion
17771 \end_inset
17772 </cell>
17773 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17774 \begin_inset Text
17775
17776 \layout Standard
17777
17778 sdcc/support/scripts
17779 \end_inset
17780 </cell>
17781 </row>
17782 <row topline="true">
17783 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17784 \begin_inset Text
17785
17786 \layout Standard
17787
17788 as-gbz80
17789 \end_inset
17790 </cell>
17791 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17792 \begin_inset Text
17793
17794 \layout Standard
17795
17796 Assembler
17797 \end_inset
17798 </cell>
17799 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17800 \begin_inset Text
17801
17802 \layout Standard
17803
17804
17805 \family roman
17806 \series medium
17807 \shape up
17808 \size normal
17809 \emph off
17810 \bar no
17811 \noun off
17812 \color none
17813 sdcc/bin
17814 \end_inset
17815 </cell>
17816 </row>
17817 <row topline="true">
17818 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17819 \begin_inset Text
17820
17821 \layout Standard
17822
17823 as-z80
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 Assembler
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 \family roman
17841 \series medium
17842 \shape up
17843 \size normal
17844 \emph off
17845 \bar no
17846 \noun off
17847 \color none
17848 sdcc/bin
17849 \end_inset
17850 </cell>
17851 </row>
17852 <row topline="true">
17853 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17854 \begin_inset Text
17855
17856 \layout Standard
17857
17858 asx8051
17859 \end_inset
17860 </cell>
17861 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17862 \begin_inset Text
17863
17864 \layout Standard
17865
17866 Assembler
17867 \end_inset
17868 </cell>
17869 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17870 \begin_inset Text
17871
17872 \layout Standard
17873
17874
17875 \family roman
17876 \series medium
17877 \shape up
17878 \size normal
17879 \emph off
17880 \bar no
17881 \noun off
17882 \color none
17883 sdcc/bin
17884 \end_inset
17885 </cell>
17886 </row>
17887 <row topline="true">
17888 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17889 \begin_inset Text
17890
17891 \layout Standard
17892
17893 sdcdb
17894 \end_inset
17895 </cell>
17896 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17897 \begin_inset Text
17898
17899 \layout Standard
17900
17901 Simulator
17902 \end_inset
17903 </cell>
17904 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17905 \begin_inset Text
17906
17907 \layout Standard
17908
17909
17910 \family roman
17911 \series medium
17912 \shape up
17913 \size normal
17914 \emph off
17915 \bar no
17916 \noun off
17917 \color none
17918 sdcc/bin
17919 \end_inset
17920 </cell>
17921 </row>
17922 <row topline="true">
17923 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17924 \begin_inset Text
17925
17926 \layout Standard
17927
17928 aslink
17929 \end_inset
17930 </cell>
17931 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17932 \begin_inset Text
17933
17934 \layout Standard
17935
17936 Linker
17937 \end_inset
17938 </cell>
17939 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17940 \begin_inset Text
17941
17942 \layout Standard
17943
17944
17945 \family roman
17946 \series medium
17947 \shape up
17948 \size normal
17949 \emph off
17950 \bar no
17951 \noun off
17952 \color none
17953 sdcc/bin
17954 \end_inset
17955 </cell>
17956 </row>
17957 <row topline="true">
17958 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17959 \begin_inset Text
17960
17961 \layout Standard
17962
17963 link-z80
17964 \end_inset
17965 </cell>
17966 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17967 \begin_inset Text
17968
17969 \layout Standard
17970
17971 Linker
17972 \end_inset
17973 </cell>
17974 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
17975 \begin_inset Text
17976
17977 \layout Standard
17978
17979
17980 \family roman
17981 \series medium
17982 \shape up
17983 \size normal
17984 \emph off
17985 \bar no
17986 \noun off
17987 \color none
17988 sdcc/bin
17989 \end_inset
17990 </cell>
17991 </row>
17992 <row topline="true">
17993 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
17994 \begin_inset Text
17995
17996 \layout Standard
17997
17998 link-gbz80
17999 \end_inset
18000 </cell>
18001 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18002 \begin_inset Text
18003
18004 \layout Standard
18005
18006 Linker
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 \family roman
18016 \series medium
18017 \shape up
18018 \size normal
18019 \emph off
18020 \bar no
18021 \noun off
18022 \color none
18023 sdcc/bin
18024 \end_inset
18025 </cell>
18026 </row>
18027 <row topline="true" bottomline="true">
18028 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18029 \begin_inset Text
18030
18031 \layout Standard
18032
18033 packihx
18034 \end_inset
18035 </cell>
18036 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18037 \begin_inset Text
18038
18039 \layout Standard
18040
18041 ihx packer
18042 \end_inset
18043 </cell>
18044 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18045 \begin_inset Text
18046
18047 \layout Standard
18048
18049
18050 \family roman
18051 \series medium
18052 \shape up
18053 \size normal
18054 \emph off
18055 \bar no
18056 \noun off
18057 \color none
18058 sdcc/bin
18059 \end_inset
18060 </cell>
18061 </row>
18062 </lyxtabular>
18063
18064 \end_inset
18065
18066
18067 \newline
18068
18069 \layout Section
18070
18071 Documentation
18072 \begin_inset LatexCommand \index{Documentation}
18073
18074 \end_inset
18075
18076  included in the distribution
18077 \layout Standard
18078 \align center
18079
18080 \begin_inset  Tabular
18081 <lyxtabular version="3" rows="10" columns="2">
18082 <features>
18083 <column alignment="left" valignment="top" leftline="true" width="0">
18084 <column alignment="left" valignment="top" leftline="true" rightline="true" width="0pt">
18085 <row topline="true" bottomline="true">
18086 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18087 \begin_inset Text
18088
18089 \layout Standard
18090
18091 Subject / Title
18092 \end_inset
18093 </cell>
18094 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18095 \begin_inset Text
18096
18097 \layout Standard
18098
18099 Where to get / filename
18100 \end_inset
18101 </cell>
18102 </row>
18103 <row topline="true">
18104 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18105 \begin_inset Text
18106
18107 \layout Standard
18108
18109 SDCC Compiler User Guide
18110 \end_inset
18111 </cell>
18112 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18113 \begin_inset Text
18114
18115 \layout Standard
18116
18117 You're reading it right now
18118 \end_inset
18119 </cell>
18120 </row>
18121 <row topline="true">
18122 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18123 \begin_inset Text
18124
18125 \layout Standard
18126
18127 Changelog of SDCC
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 sdcc/Changelog
18136 \end_inset
18137 </cell>
18138 </row>
18139 <row topline="true">
18140 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18141 \begin_inset Text
18142
18143 \layout Standard
18144
18145 ASXXXX
18146 \begin_inset LatexCommand \index{asXXXX (as-gbz80, as-hc08, asx8051, as-z80)}
18147
18148 \end_inset
18149
18150
18151 \begin_inset LatexCommand \index{Assembler documentation}
18152
18153 \end_inset
18154
18155  Assemblers and ASLINK
18156 \begin_inset LatexCommand \index{aslink}
18157
18158 \end_inset
18159
18160
18161 \begin_inset LatexCommand \index{Linker documentation}
18162
18163 \end_inset
18164
18165  Relocating Linker
18166 \end_inset
18167 </cell>
18168 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18169 \begin_inset Text
18170
18171 \layout Standard
18172
18173 sdcc/as/doc/asxhtm.html
18174 \end_inset
18175 </cell>
18176 </row>
18177 <row topline="true">
18178 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18179 \begin_inset Text
18180
18181 \layout Standard
18182
18183 SDCC regression test
18184 \begin_inset LatexCommand \index{Regression test}
18185
18186 \end_inset
18187
18188
18189 \end_inset
18190 </cell>
18191 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18192 \begin_inset Text
18193
18194 \layout Standard
18195
18196 sdcc/doc/test_suite_spec.pdf
18197 \end_inset
18198 </cell>
18199 </row>
18200 <row topline="true">
18201 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18202 \begin_inset Text
18203
18204 \layout Standard
18205
18206 Various notes
18207 \end_inset
18208 </cell>
18209 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18210 \begin_inset Text
18211
18212 \layout Standard
18213
18214 sdcc/doc/*
18215 \end_inset
18216 </cell>
18217 </row>
18218 <row topline="true">
18219 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18220 \begin_inset Text
18221
18222 \layout Standard
18223
18224 Notes on debugging with sdcdb
18225 \begin_inset LatexCommand \index{sdcdb (debugger)}
18226
18227 \end_inset
18228
18229
18230 \end_inset
18231 </cell>
18232 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18233 \begin_inset Text
18234
18235 \layout Standard
18236
18237 sdcc/debugger/README
18238 \end_inset
18239 </cell>
18240 </row>
18241 <row topline="true">
18242 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18243 \begin_inset Text
18244
18245 \layout Standard
18246
18247 Software simulator for microcontrollers
18248 \end_inset
18249 </cell>
18250 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18251 \begin_inset Text
18252
18253 \layout Standard
18254
18255
18256 \family roman
18257 \series medium
18258 \shape up
18259 \size normal
18260 \emph off
18261 \bar no
18262 \noun off
18263 \color none
18264 sdcc/sim/ucsim/doc
18265 \family default
18266 \series default
18267 \shape default
18268 \size default
18269 \emph default
18270 \bar default
18271 \noun default
18272 \color default
18273 /index.html
18274 \end_inset
18275 </cell>
18276 </row>
18277 <row topline="true">
18278 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18279 \begin_inset Text
18280
18281 \layout Standard
18282
18283 Temporary notes on the pic16
18284 \begin_inset LatexCommand \index{PIC16}
18285
18286 \end_inset
18287
18288  port
18289 \end_inset
18290 </cell>
18291 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18292 \begin_inset Text
18293
18294 \layout Standard
18295
18296 sdcc/src/pic16/NOTES
18297 \end_inset
18298 </cell>
18299 </row>
18300 <row topline="true" bottomline="true">
18301 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18302 \begin_inset Text
18303
18304 \layout Standard
18305
18306 SDCC internal documentation (debugging file format)
18307 \end_inset
18308 </cell>
18309 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18310 \begin_inset Text
18311
18312 \layout Standard
18313
18314 sdcc/doc/
18315 \family roman
18316 \series medium
18317 \shape up
18318 \size normal
18319 \emph off
18320 \bar no
18321 \noun off
18322 \color none
18323 cdbfileformat.pd
18324 \family default
18325 \series default
18326 \shape default
18327 \size default
18328 \emph default
18329 \bar default
18330 \noun default
18331 \color default
18332 f
18333 \end_inset
18334 </cell>
18335 </row>
18336 </lyxtabular>
18337
18338 \end_inset
18339
18340
18341 \newline
18342
18343 \layout Section
18344
18345 Related open source tools
18346 \begin_inset LatexCommand \index{Related tools}
18347
18348 \end_inset
18349
18350
18351 \layout Standard
18352 \align center
18353
18354 \begin_inset  Tabular
18355 <lyxtabular version="3" rows="11" columns="3">
18356 <features>
18357 <column alignment="center" valignment="top" leftline="true" width="0pt">
18358 <column alignment="block" valignment="top" leftline="true" width="30line%">
18359 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18360 <row topline="true" bottomline="true">
18361 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18362 \begin_inset Text
18363
18364 \layout Standard
18365
18366 Name
18367 \end_inset
18368 </cell>
18369 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18370 \begin_inset Text
18371
18372 \layout Standard
18373
18374 Purpose
18375 \end_inset
18376 </cell>
18377 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18378 \begin_inset Text
18379
18380 \layout Standard
18381
18382 Where to get
18383 \end_inset
18384 </cell>
18385 </row>
18386 <row topline="true">
18387 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18388 \begin_inset Text
18389
18390 \layout Standard
18391
18392 gpsim
18393 \begin_inset LatexCommand \index{gpsim (pic simulator)}
18394
18395 \end_inset
18396
18397
18398 \end_inset
18399 </cell>
18400 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18401 \begin_inset Text
18402
18403 \layout Standard
18404
18405 PIC simulator
18406 \end_inset
18407 </cell>
18408 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18409 \begin_inset Text
18410
18411 \layout Standard
18412
18413
18414 \begin_inset LatexCommand \url{http://www.dattalo.com/gnupic/gpsim.html}
18415
18416 \end_inset
18417
18418
18419 \end_inset
18420 </cell>
18421 </row>
18422 <row topline="true">
18423 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18424 \begin_inset Text
18425
18426 \layout Standard
18427
18428 gputils
18429 \begin_inset LatexCommand \index{gputils (pic tools)}
18430
18431 \end_inset
18432
18433
18434 \end_inset
18435 </cell>
18436 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18437 \begin_inset Text
18438
18439 \layout Standard
18440
18441 GNU PIC utilities
18442 \end_inset
18443 </cell>
18444 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18445 \begin_inset Text
18446
18447 \layout Standard
18448
18449
18450 \begin_inset LatexCommand \url{http://gputils.sourceforge.net/}
18451
18452 \end_inset
18453
18454
18455 \end_inset
18456 </cell>
18457 </row>
18458 <row topline="true">
18459 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18460 \begin_inset Text
18461
18462 \layout Standard
18463
18464 flP5
18465 \end_inset
18466 </cell>
18467 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18468 \begin_inset Text
18469
18470 \layout Standard
18471
18472 PIC programmer
18473 \end_inset
18474 </cell>
18475 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18476 \begin_inset Text
18477
18478 \layout Standard
18479
18480
18481 \begin_inset LatexCommand \url{http://digilander.libero.it/fbradasc/FLP5.html}
18482
18483 \end_inset
18484
18485
18486 \end_inset
18487 </cell>
18488 </row>
18489 <row topline="true">
18490 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18491 \begin_inset Text
18492
18493 \layout Standard
18494
18495 indent
18496 \begin_inset LatexCommand \index{indent (source formatting tool)}
18497
18498 \end_inset
18499
18500
18501 \end_inset
18502 </cell>
18503 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18504 \begin_inset Text
18505
18506 \layout Standard
18507
18508 Formats C source - Master of the white spaces
18509 \end_inset
18510 </cell>
18511 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18512 \begin_inset Text
18513
18514 \layout Standard
18515
18516
18517 \begin_inset LatexCommand \url{http://home.hccnet.nl/d.ingamells/beautify.html}
18518
18519 \end_inset
18520
18521
18522 \end_inset
18523 </cell>
18524 </row>
18525 <row topline="true">
18526 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18527 \begin_inset Text
18528
18529 \layout Standard
18530
18531 srecord
18532 \begin_inset LatexCommand \index{srecord (tool)}
18533
18534 \end_inset
18535
18536
18537 \end_inset
18538 </cell>
18539 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18540 \begin_inset Text
18541
18542 \layout Standard
18543
18544 Object file conversion, checksumming, ...
18545 \end_inset
18546 </cell>
18547 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18548 \begin_inset Text
18549
18550 \layout Standard
18551
18552
18553 \begin_inset LatexCommand \url{http://srecord.sourceforge.net/}
18554
18555 \end_inset
18556
18557
18558 \end_inset
18559 </cell>
18560 </row>
18561 <row topline="true">
18562 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18563 \begin_inset Text
18564
18565 \layout Standard
18566
18567 objdump
18568 \begin_inset LatexCommand \index{objdump (tool)}
18569
18570 \end_inset
18571
18572
18573 \end_inset
18574 </cell>
18575 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18576 \begin_inset Text
18577
18578 \layout Standard
18579
18580 Object file conversion, ...
18581 \end_inset
18582 </cell>
18583 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18584 \begin_inset Text
18585
18586 \layout Standard
18587
18588 Part of binutils (should be there anyway)
18589 \end_inset
18590 </cell>
18591 </row>
18592 <row topline="true">
18593 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18594 \begin_inset Text
18595
18596 \layout Standard
18597
18598 doxygen
18599 \begin_inset LatexCommand \index{doxygen (source documentation tool)}
18600
18601 \end_inset
18602
18603
18604 \end_inset
18605 </cell>
18606 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18607 \begin_inset Text
18608
18609 \layout Standard
18610
18611 Source code documentation system
18612 \end_inset
18613 </cell>
18614 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18615 \begin_inset Text
18616
18617 \layout Standard
18618
18619
18620 \begin_inset LatexCommand \url{http://www.doxygen.org}
18621
18622 \end_inset
18623
18624
18625 \end_inset
18626 </cell>
18627 </row>
18628 <row topline="true">
18629 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18630 \begin_inset Text
18631
18632 \layout Standard
18633
18634 kdevelop
18635 \end_inset
18636 </cell>
18637 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18638 \begin_inset Text
18639
18640 \layout Standard
18641
18642 IDE (has anyone tried integrating SDCC & sdcdb? Unix only)
18643 \end_inset
18644 </cell>
18645 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18646 \begin_inset Text
18647
18648 \layout Standard
18649
18650
18651 \begin_inset LatexCommand \url{http://www.kdevelop.org}
18652
18653 \end_inset
18654
18655
18656 \end_inset
18657 </cell>
18658 </row>
18659 <row topline="true">
18660 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18661 \begin_inset Text
18662
18663 \layout Standard
18664
18665 splint
18666 \begin_inset LatexCommand \index{splint (syntax checking tool)}
18667
18668 \end_inset
18669
18670
18671 \end_inset
18672 </cell>
18673 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18674 \begin_inset Text
18675
18676 \layout Standard
18677
18678 Statically checks c sources (has anyone adapted splint for SDCC?)
18679 \end_inset
18680 </cell>
18681 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18682 \begin_inset Text
18683
18684 \layout Standard
18685
18686
18687 \begin_inset LatexCommand \url{http://www.splint.org}
18688
18689 \end_inset
18690
18691
18692 \end_inset
18693 </cell>
18694 </row>
18695 <row topline="true" bottomline="true">
18696 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18697 \begin_inset Text
18698
18699 \layout Standard
18700
18701 ddd
18702 \begin_inset LatexCommand \index{ddd (debugger)}
18703
18704 \end_inset
18705
18706
18707 \end_inset
18708 </cell>
18709 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18710 \begin_inset Text
18711
18712 \layout Standard
18713
18714 Debugger, serves nicely as GUI to sdcdb
18715 \begin_inset LatexCommand \index{sdcdb (debugger)}
18716
18717 \end_inset
18718
18719  (Unix only)
18720 \end_inset
18721 </cell>
18722 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18723 \begin_inset Text
18724
18725 \layout Standard
18726
18727
18728 \begin_inset LatexCommand \url{http://www.gnu.org/software/ddd/}
18729
18730 \end_inset
18731
18732
18733 \end_inset
18734 </cell>
18735 </row>
18736 </lyxtabular>
18737
18738 \end_inset
18739
18740
18741 \newline
18742
18743 \layout Section
18744
18745 Related documentation / recommended reading
18746 \layout Standard
18747 \align center
18748
18749 \begin_inset  Tabular
18750 <lyxtabular version="3" rows="6" columns="3">
18751 <features>
18752 <column alignment="center" valignment="top" leftline="true" width="0pt">
18753 <column alignment="block" valignment="top" leftline="true" width="30line%">
18754 <column alignment="center" valignment="top" leftline="true" rightline="true" width="0pt">
18755 <row topline="true" bottomline="true">
18756 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18757 \begin_inset Text
18758
18759 \layout Standard
18760
18761 Name
18762 \end_inset
18763 </cell>
18764 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18765 \begin_inset Text
18766
18767 \layout Standard
18768
18769 Subject / Title
18770 \end_inset
18771 </cell>
18772 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18773 \begin_inset Text
18774
18775 \layout Standard
18776
18777 Where to get
18778 \end_inset
18779 </cell>
18780 </row>
18781 <row topline="true">
18782 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18783 \begin_inset Text
18784
18785 \layout Standard
18786
18787
18788 \family roman
18789 \series medium
18790 \shape up
18791 \size normal
18792 \emph off
18793 \bar no
18794 \noun off
18795 \color none
18796 c-refcard.pdf
18797 \end_inset
18798 </cell>
18799 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18800 \begin_inset Text
18801
18802 \layout Standard
18803
18804 C Reference Card
18805 \begin_inset LatexCommand \index{C Reference card}
18806
18807 \end_inset
18808
18809 , 2 pages
18810 \end_inset
18811 </cell>
18812 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18813 \begin_inset Text
18814
18815 \layout Standard
18816
18817
18818 \begin_inset LatexCommand \url{http://www.refcards.com/about/c.html}
18819
18820 \end_inset
18821
18822
18823 \end_inset
18824 </cell>
18825 </row>
18826 <row topline="true">
18827 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18828 \begin_inset Text
18829
18830 \layout Standard
18831
18832 c-faq
18833 \end_inset
18834 </cell>
18835 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18836 \begin_inset Text
18837
18838 \layout Standard
18839
18840 C-FAQ-list
18841 \end_inset
18842 </cell>
18843 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18844 \begin_inset Text
18845
18846 \layout Standard
18847
18848
18849 \begin_inset LatexCommand \url{http://www.eskimo.com/~scs/C-faq/top.html}
18850
18851 \end_inset
18852
18853
18854 \end_inset
18855 </cell>
18856 </row>
18857 <row topline="true">
18858 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18859 \begin_inset Text
18860
18861 \layout Standard
18862
18863 \end_inset
18864 </cell>
18865 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18866 \begin_inset Text
18867
18868 \layout Standard
18869
18870 Latest datasheet of the target CPU
18871 \end_inset
18872 </cell>
18873 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18874 \begin_inset Text
18875
18876 \layout Standard
18877
18878 vendor
18879 \end_inset
18880 </cell>
18881 </row>
18882 <row topline="true">
18883 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18884 \begin_inset Text
18885
18886 \layout Standard
18887
18888 \end_inset
18889 </cell>
18890 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18891 \begin_inset Text
18892
18893 \layout Standard
18894
18895 Revision history of datasheet
18896 \end_inset
18897 </cell>
18898 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18899 \begin_inset Text
18900
18901 \layout Standard
18902
18903 vendor
18904 \end_inset
18905 </cell>
18906 </row>
18907 <row topline="true" bottomline="true">
18908 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18909 \begin_inset Text
18910
18911 \layout Standard
18912
18913 S.
18914  S.
18915  Muchnick
18916 \end_inset
18917 </cell>
18918 <cell alignment="center" valignment="top" topline="true" leftline="true" usebox="none">
18919 \begin_inset Text
18920
18921 \layout Standard
18922
18923 Advanced Compiler Design and Implementation
18924 \end_inset
18925 </cell>
18926 <cell alignment="center" valignment="top" topline="true" leftline="true" rightline="true" usebox="none">
18927 \begin_inset Text
18928
18929 \layout Standard
18930
18931 bookstore (very dedicated, probably read other books first)
18932 \end_inset
18933 </cell>
18934 </row>
18935 </lyxtabular>
18936
18937 \end_inset
18938
18939
18940 \newline
18941
18942 \layout Section
18943
18944 Some Questions
18945 \layout Standard
18946
18947 Some questions answered, some pointers given - it might be time to in turn
18948  ask
18949 \emph on
18950 you
18951 \emph default
18952  some questions:
18953 \layout Itemize
18954
18955 can you solve your project with the selected microcontroller? Would you
18956  find out early or rather late that your target is too small/slow/whatever?
18957  Can you switch to a slightly better device if it doesn't fit?
18958 \layout Itemize
18959
18960 should you solve the problem with an 8 bit CPU? Or would a 16/32 bit CPU
18961  and/or another programming language be more adequate? Would an operating
18962  system on the target device help?
18963 \layout Itemize
18964
18965 if you solved the problem, will the marketing department be happy?
18966 \layout Itemize
18967
18968 if the marketing department is happy, will customers be happy?
18969 \layout Itemize
18970
18971 if you're the project manager, marketing department and maybe even the customer
18972  in one person, have you tried to see the project from the outside?
18973 \layout Itemize
18974
18975 is the project done if you think it is done? Or is just that other interface/pro
18976 tocol/feature/configuration/option missing? How about website, manual(s),
18977  internationali(z|s)ation, packaging, labels, 2nd source for components,
18978  electromagnetic compatability/interference, documentation for production,
18979  production test software, update mechanism, patent issues?
18980 \layout Itemize
18981
18982 is your project adequately positioned in that magic triangle: fame, fortune,
18983  fun?
18984 \layout Standard
18985
18986 Maybe not all answers to these questions are known and some answers may
18987  even be
18988 \emph on
18989 no
18990 \emph default
18991 , nevertheless knowing these questions may help you to avoid burnout
18992 \begin_inset Foot
18993 collapsed false
18994
18995 \layout Standard
18996
18997 burnout is bad for electronic devices, programmers and motorcycle tyres
18998 \end_inset
18999
19000 .
19001  Chances are you didn't want to hear some of them...
19002 \layout Chapter
19003
19004 Support
19005 \begin_inset LatexCommand \index{Support}
19006
19007 \end_inset
19008
19009
19010 \layout Standard
19011
19012 SDCC has grown to be a large project.
19013  The compiler alone (without the preprocessor, assembler and linker) is
19014  well over 100,000 lines of code (blank stripped).
19015  The open source nature of this project is a key to its continued growth
19016  and support.
19017  You gain the benefit and support of many active software developers and
19018  end users.
19019  Is SDCC perfect? No, that's why we need your help.
19020  The developers take pride in fixing reported bugs.
19021  You can help by reporting the bugs and helping other SDCC users.
19022  There are lots of ways to contribute, and we encourage you to take part
19023  in making SDCC a great software package.
19024
19025 \layout Standard
19026
19027 The SDCC project is hosted on the SDCC sourceforge site at
19028 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/projects/sdcc}
19029
19030 \end_inset
19031
19032 .
19033  You'll find the complete set of mailing lists
19034 \begin_inset LatexCommand \index{Mailing list(s)}
19035
19036 \end_inset
19037
19038 , forums, bug reporting system, patch submission
19039 \begin_inset LatexCommand \index{Patch submission}
19040
19041 \end_inset
19042
19043  system, download
19044 \begin_inset LatexCommand \index{download}
19045
19046 \end_inset
19047
19048  area and cvs code repository
19049 \begin_inset LatexCommand \index{cvs code repository}
19050
19051 \end_inset
19052
19053  there.
19054 \layout Section
19055
19056 Reporting Bugs
19057 \begin_inset LatexCommand \index{Bug reporting}
19058
19059 \end_inset
19060
19061
19062 \begin_inset LatexCommand \index{Reporting bugs}
19063
19064 \end_inset
19065
19066
19067 \layout Standard
19068
19069 The recommended way of reporting bugs is using the infrastructure of the
19070  sourceforge site.
19071  You can follow the status of bug reports there and have an overview about
19072  the known bugs.
19073 \layout Standard
19074
19075 Bug reports are automatically forwarded to the developer mailing list and
19076  will be fixed ASAP.
19077  When reporting a bug, it is very useful to include a small test program
19078  (the smaller the better) which reproduces the problem.
19079  If you can isolate the problem by looking at the generated assembly code,
19080  this can be very helpful.
19081  Compiling your program with the -
19082 \begin_inset ERT
19083 status Collapsed
19084
19085 \layout Standard
19086
19087 \backslash
19088 /
19089 \end_inset
19090
19091 -dumpall
19092 \begin_inset LatexCommand \index{-\/-dumpall}
19093
19094 \end_inset
19095
19096  option can sometimes be useful in locating optimization problems.
19097  When reporting a bug please maker sure you:
19098 \layout Enumerate
19099
19100 Attach the code you are compiling with SDCC.
19101
19102 \layout Enumerate
19103
19104 Specify the exact command you use to run SDCC, or attach your Makefile.
19105
19106 \layout Enumerate
19107
19108 Specify the SDCC version (type "
19109 \family sans
19110 \series bold
19111 sdcc -v
19112 \family default
19113 \series default
19114 "), your platform, and operating system.
19115
19116 \layout Enumerate
19117
19118 Provide an exact copy of any error message or incorrect output.
19119
19120 \layout Enumerate
19121
19122 Put something meaningful in the subject of your message.
19123 \layout Standard
19124
19125 Please attempt to include these 5 important parts, as applicable, in all
19126  requests for support or when reporting any problems or bugs with SDCC.
19127  Though this will make your message lengthy, it will greatly improve your
19128  chance that SDCC users and developers will be able to help you.
19129  Some SDCC developers are frustrated by bug reports without code provided
19130  that they can use to reproduce and ultimately fix the problem, so please
19131  be sure to provide sample code if you are reporting a bug!
19132 \layout Standard
19133
19134 Please have a short check that you are using a recent version of SDCC and
19135  the bug is not yet known.
19136  This is the link for reporting bugs:
19137 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=100599}
19138
19139 \end_inset
19140
19141 .
19142 \layout Section
19143
19144 Requesting Features
19145 \begin_inset LatexCommand \label{sub:Requesting-Features}
19146
19147 \end_inset
19148
19149
19150 \begin_inset LatexCommand \index{Feature request}
19151
19152 \end_inset
19153
19154
19155 \begin_inset LatexCommand \index{Requesting features}
19156
19157 \end_inset
19158
19159
19160 \layout Standard
19161
19162 Like bug reports feature requests are forwarded to the developer mailing
19163  list.
19164  This is the link for requesting features:
19165 \begin_inset LatexCommand \htmlurl{http://sourceforge.net/tracker/?group_id=599&atid=350599}
19166
19167 \end_inset
19168
19169 .
19170 \layout Section
19171
19172 Submitting patches
19173 \layout Standard
19174
19175 Like bug reports contributed patches are forwarded to the developer mailing
19176  list.
19177  This is the link for submitting patches
19178 \begin_inset LatexCommand \index{Patch submission}
19179
19180 \end_inset
19181
19182 :
19183 \begin_inset LatexCommand \url{http://sourceforge.net/tracker/?group_id=599&atid=300599}
19184
19185 \end_inset
19186
19187 .
19188 \layout Standard
19189
19190 You need to specify some parameters to the
19191 \family typewriter
19192 diff
19193 \family default
19194  command for the patches to be useful.
19195  If you modified more than one file a patch created f.e.
19196  with
19197 \family sans
19198 \series bold
19199
19200 \begin_inset Quotes sld
19201 \end_inset
19202
19203 diff -Naur unmodified_directory modified_directory >my_changes.patch
19204 \begin_inset Quotes srd
19205 \end_inset
19206
19207
19208 \family default
19209 \series default
19210  will be fine, otherwise
19211 \family sans
19212 \series bold
19213
19214 \begin_inset Quotes sld
19215 \end_inset
19216
19217 diff -u sourcefile.c.orig sourcefile.c >my_changes.patch
19218 \begin_inset Quotes srd
19219 \end_inset
19220
19221
19222 \series default
19223
19224 \family default
19225 will do.
19226 \layout Section
19227
19228 Getting Help
19229 \layout Standard
19230
19231 These links should take you directly to the
19232 \begin_inset LatexCommand \url[Mailing lists]{http://sourceforge.net/mail/?group_id=599}
19233
19234 \end_inset
19235
19236
19237 \begin_inset Foot
19238 collapsed false
19239
19240 \layout Standard
19241
19242 Traffic on sdcc-devel and sdcc-user is about 100 mails/month each not counting
19243  automated messages (mid 2003)
19244 \end_inset
19245
19246  and the
19247 \begin_inset LatexCommand \url[Forums]{http://sourceforge.net/forum/?group_id=599}
19248
19249 \end_inset
19250
19251 , lists
19252 \begin_inset LatexCommand \index{Mailing list(s)}
19253
19254 \end_inset
19255
19256  and forums are archived and searchable so if you are lucky someone already
19257  had a similar problem.
19258  While mails to the lists themselves are delivered promptly their web front
19259  end on sourceforge sometimes shows a severe time lag (up to several weeks),
19260  if you're seriously using SDCC please consider subscribing to the lists.
19261 \layout Section
19262
19263 ChangeLog
19264 \layout Standard
19265
19266 You can follow the status of the cvs version
19267 \begin_inset LatexCommand \index{version}
19268
19269 \end_inset
19270
19271  of SDCC by watching the Changelog
19272 \begin_inset LatexCommand \index{Changelog}
19273
19274 \end_inset
19275
19276  in the cvs-repository
19277 \newline
19278
19279 \size footnotesize
19280
19281 \begin_inset LatexCommand \htmlurl{http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/*checkout*/sdcc/sdcc/ChangeLog?rev=HEAD&content-type=text/plain}
19282
19283 \end_inset
19284
19285 .
19286 \layout Section
19287
19288 Release policy
19289 \begin_inset LatexCommand \index{Release policy}
19290
19291 \end_inset
19292
19293
19294 \layout Standard
19295
19296 Historically there often were long delays between official releases and
19297  the sourceforge download area tends to get not updated at all.
19298  Excuses in the past might have referred to problems with live range analysis,
19299  but as this was fixed a while ago, the current problem is that another
19300  excuse has to be found.
19301  Kidding aside, we have to get better there! On the other hand there are
19302  daily snapshots available at
19303 \begin_inset LatexCommand \htmlurl[snap]{http://sdcc.sourceforge.net/snap.php}
19304
19305 \end_inset
19306
19307 , and you can always build the very last version (hopefully with many bugs
19308  fixed, and features added) from the source code available at
19309 \begin_inset LatexCommand \htmlurl[Source]{http://sdcc.sourceforge.net/snap.php#Source}
19310
19311 \end_inset
19312
19313 .
19314 \layout Section
19315
19316 Examples
19317 \begin_inset LatexCommand \index{Examples}
19318
19319 \end_inset
19320
19321
19322 \layout Standard
19323
19324 You'll find some small examples in the directory
19325 \emph on
19326 sdcc/device/examples/.
19327
19328 \emph default
19329 More examples and libraries are available at
19330 \emph on
19331  The SDCC Open Knowledge Resource
19332 \begin_inset LatexCommand \url{http://www.qsl.net/dl9sec/SDCC_OKR.html}
19333
19334 \end_inset
19335
19336
19337 \emph default
19338 web site or at
19339 \begin_inset LatexCommand \url{http://www.pjrc.com/tech/8051/}
19340
19341 \end_inset
19342
19343 .
19344 \layout Comment
19345
19346 I did insert a reference to Paul's web site here although it seems rather
19347  dedicated to a specific 8032 board (I think it's okay because it f.e.
19348  shows LCD/Harddisc interface and has a free 8051 monitor.
19349  Independent 8032 board vendors face hard competition of heavily subsidized
19350  development boards anyway).
19351 \layout Comment
19352
19353 Maybe we should include some links to real world applications.
19354  Preferably pointer to pointers (one for each architecture) so this stays
19355  manageable here?
19356 \layout Section
19357
19358 Quality control
19359 \begin_inset LatexCommand \index{Quality control}
19360
19361 \end_inset
19362
19363
19364 \layout Standard
19365
19366 The compiler is passed through nightly compile and build checks.
19367  The so called
19368 \shape italic
19369 regression tests
19370 \shape default
19371
19372 \begin_inset LatexCommand \index{Regression test}
19373
19374 \end_inset
19375
19376  check that SDCC itself compiles flawlessly on several platforms and checks
19377  the quality of the code generated by SDCC by running the code through simulator
19378 s.
19379  There is a separate document
19380 \shape italic
19381 test_suite.pdf
19382 \begin_inset LatexCommand \index{Test suite}
19383
19384 \end_inset
19385
19386
19387 \shape default
19388  about this.
19389 \layout Standard
19390
19391 You'll find the test code in the directory
19392 \shape italic
19393 sdcc/support/regression
19394 \shape default
19395 .
19396  You can run these tests manually by running
19397 \family sans
19398 make
19399 \family default
19400  in this directory (or f.e.
19401
19402 \family sans
19403 \series bold
19404
19405 \begin_inset Quotes sld
19406 \end_inset
19407
19408 make test-mcs51
19409 \begin_inset Quotes srd
19410 \end_inset
19411
19412
19413 \family default
19414 \series default
19415  if you don't want to run the complete tests).
19416  The test code might also be interesting if you want to look for examples
19417 \begin_inset LatexCommand \index{Examples}
19418
19419 \end_inset
19420
19421  checking corner cases of SDCC or if you plan to submit patches
19422 \begin_inset LatexCommand \index{Patch submission}
19423
19424 \end_inset
19425
19426 .
19427 \layout Standard
19428
19429 The pic port uses a different set of regression tests, you'll find them
19430  in the directory
19431 \shape italic
19432 sdcc/src/regression
19433 \shape default
19434 .
19435 \layout Chapter
19436 \pagebreak_top
19437 SDCC Technical Data
19438 \layout Section
19439
19440 Optimizations
19441 \begin_inset LatexCommand \index{Optimizations}
19442
19443 \end_inset
19444
19445
19446 \layout Standard
19447
19448 SDCC performs a host of standard optimizations in addition to some MCU specific
19449  optimizations.
19450
19451 \layout Subsection
19452
19453 Sub-expression Elimination
19454 \begin_inset LatexCommand \index{Subexpression elimination}
19455
19456 \end_inset
19457
19458
19459 \layout Standard
19460
19461 The compiler does local and
19462 \emph on
19463 g
19464 \emph default
19465 lobal
19466 \emph on
19467 c
19468 \emph default
19469 ommon
19470 \emph on
19471 s
19472 \emph default
19473 ubexpression
19474 \emph on
19475 e
19476 \emph default
19477 limination, e.g.:
19478 \layout Verse
19479
19480
19481 \family typewriter
19482 i = x + y + 1;
19483 \newline
19484 j = x + y;
19485 \layout Standard
19486
19487 will be translated to
19488 \layout Verse
19489
19490
19491 \family typewriter
19492 iTemp = x + y;
19493 \newline
19494 i = iTemp + 1;
19495 \newline
19496 j = iTemp;
19497 \layout Standard
19498
19499 Some subexpressions are not as obvious as the above example, e.g.:
19500 \layout Verse
19501
19502
19503 \family typewriter
19504 a->b[i].c = 10;
19505 \newline
19506 a->b[i].d = 11;
19507 \layout Standard
19508
19509 In this case the address arithmetic a->b[i] will be computed only once;
19510  the equivalent code in C would be.
19511 \layout Verse
19512
19513
19514 \family typewriter
19515 iTemp = a->b[i];
19516 \newline
19517 iTemp.c = 10;
19518 \newline
19519 iTemp.d = 11;
19520 \layout Standard
19521
19522 The compiler will try to keep these temporary variables in registers.
19523 \layout Subsection
19524
19525 Dead-Code Elimination
19526 \begin_inset LatexCommand \index{Dead-code elimination}
19527
19528 \end_inset
19529
19530
19531 \layout Verse
19532
19533
19534 \family typewriter
19535 int global;
19536 \newline
19537
19538 \newline
19539 void f () {
19540 \newline
19541 \SpecialChar ~
19542 \SpecialChar ~
19543 int i;
19544 \newline
19545 \SpecialChar ~
19546 \SpecialChar ~
19547 i = 1; \SpecialChar ~
19548 \SpecialChar ~
19549 \SpecialChar ~
19550 \SpecialChar ~
19551 \SpecialChar ~
19552 /* dead store */
19553 \newline
19554 \SpecialChar ~
19555 \SpecialChar ~
19556 global = 1;\SpecialChar ~
19557 /* dead store */
19558 \newline
19559 \SpecialChar ~
19560 \SpecialChar ~
19561 global = 2;
19562 \newline
19563 \SpecialChar ~
19564 \SpecialChar ~
19565 return;
19566 \newline
19567 \SpecialChar ~
19568 \SpecialChar ~
19569 global = 3;\SpecialChar ~
19570 /* unreachable */
19571 \newline
19572 }
19573 \layout Standard
19574
19575 will be changed to
19576 \layout Verse
19577
19578
19579 \family typewriter
19580 int global;
19581 \newline
19582
19583 \newline
19584 void f () {
19585 \newline
19586 \SpecialChar ~
19587 \SpecialChar ~
19588 global = 2;
19589 \newline
19590 }
19591 \layout Subsection
19592
19593 Copy-Propagation
19594 \begin_inset LatexCommand \index{Copy propagation}
19595
19596 \end_inset
19597
19598
19599 \layout Verse
19600
19601
19602 \family typewriter
19603 int f() {
19604 \newline
19605 \SpecialChar ~
19606 \SpecialChar ~
19607 int i, j;
19608 \newline
19609 \SpecialChar ~
19610 \SpecialChar ~
19611 i = 10;
19612 \newline
19613 \SpecialChar ~
19614 \SpecialChar ~
19615 j = i;
19616 \newline
19617 \SpecialChar ~
19618 \SpecialChar ~
19619 return j;
19620 \newline
19621 }
19622 \layout Standard
19623
19624 will be changed to
19625 \layout Verse
19626
19627
19628 \family typewriter
19629 int f() {
19630 \newline
19631 \SpecialChar ~
19632 \SpecialChar ~
19633 int i, j;
19634 \newline
19635 \SpecialChar ~
19636 \SpecialChar ~
19637 i = 10;
19638 \newline
19639 \SpecialChar ~
19640 \SpecialChar ~
19641 j = 10;
19642 \newline
19643 \SpecialChar ~
19644 \SpecialChar ~
19645 return 10;
19646 \newline
19647 }
19648 \layout Standard
19649
19650 Note: the dead stores created by this copy propagation will be eliminated
19651  by dead-code elimination.
19652 \layout Subsection
19653
19654 Loop Optimizations
19655 \begin_inset LatexCommand \index{Loop optimization}
19656
19657 \end_inset
19658
19659
19660 \begin_inset LatexCommand \label{sub:Loop-Optimizations}
19661
19662 \end_inset
19663
19664
19665 \layout Standard
19666
19667 Two types of loop optimizations are done by SDCC
19668 \emph on
19669 loop invariant
19670 \emph default
19671  lifting and
19672 \emph on
19673  strength reduction
19674 \emph default
19675  of loop induction variables.
19676  In addition to the strength reduction the optimizer marks the induction
19677  variables and the register allocator tries to keep the induction variables
19678  in registers for the duration of the loop.
19679  Because of this preference of the register allocator
19680 \begin_inset LatexCommand \index{Register allocation}
19681
19682 \end_inset
19683
19684 , loop induction optimization causes an increase in register pressure, which
19685  may cause unwanted spilling of other temporary variables into the stack
19686 \begin_inset LatexCommand \index{stack}
19687
19688 \end_inset
19689
19690  / data space.
19691  The compiler will generate a warning message when it is forced to allocate
19692  extra space either on the stack or data space.
19693  If this extra space allocation is undesirable then induction optimization
19694  can be eliminated either for the entire source file (with -
19695 \begin_inset ERT
19696 status Collapsed
19697
19698 \layout Standard
19699
19700 \backslash
19701 /
19702 \end_inset
19703
19704 -noinduction option) or for a given function only using #pragma\SpecialChar ~
19705 noinduction
19706 \begin_inset LatexCommand \index{\#pragma noinduction}
19707
19708 \end_inset
19709
19710 .
19711 \newline
19712
19713 \newline
19714 Loop Invariant:
19715 \layout Verse
19716
19717
19718 \family typewriter
19719 for (i = 0 ; i < 100 ; i ++)
19720 \newline
19721 \SpecialChar ~
19722 \SpecialChar ~
19723 \SpecialChar ~
19724 \SpecialChar ~
19725 f += k + l;
19726 \layout Standard
19727
19728 changed to
19729 \layout Verse
19730
19731
19732 \family typewriter
19733 itemp = k + l;
19734 \newline
19735 for (i = 0; i < 100; i++)
19736 \newline
19737 \SpecialChar ~
19738 \SpecialChar ~
19739 \SpecialChar ~
19740 \SpecialChar ~
19741 f += itemp;
19742 \layout Standard
19743
19744 As mentioned previously some loop invariants are not as apparent, all static
19745  address computations are also moved out of the loop.
19746 \newline
19747
19748 \newline
19749 Strength Reduction
19750 \begin_inset LatexCommand \index{Strength reduction}
19751
19752 \end_inset
19753
19754 , this optimization substitutes an expression by a cheaper expression:
19755 \layout Verse
19756
19757
19758 \family typewriter
19759 for (i=0;i < 100; i++)
19760 \newline
19761 \SpecialChar ~
19762 \SpecialChar ~
19763 \SpecialChar ~
19764 \SpecialChar ~
19765 ar[i*5] = i*3;
19766 \layout Standard
19767
19768 changed to
19769 \layout Verse
19770
19771
19772 \family typewriter
19773 itemp1 = 0;
19774 \newline
19775 itemp2 = 0;
19776 \newline
19777 for (i=0;i< 100;i++) {
19778 \newline
19779 \SpecialChar ~
19780 \SpecialChar ~
19781 \SpecialChar ~
19782 \SpecialChar ~
19783 ar[itemp1] = itemp2;
19784 \newline
19785 \SpecialChar ~
19786 \SpecialChar ~
19787 \SpecialChar ~
19788 \SpecialChar ~
19789 itemp1 += 5;
19790 \newline
19791 \SpecialChar ~
19792 \SpecialChar ~
19793 \SpecialChar ~
19794 \SpecialChar ~
19795 itemp2 += 3;
19796 \newline
19797 }
19798 \layout Standard
19799
19800 The more expensive multiplication
19801 \begin_inset LatexCommand \index{Multiplication}
19802
19803 \end_inset
19804
19805  is changed to a less expensive addition.
19806 \layout Subsection
19807
19808 Loop Reversing
19809 \begin_inset LatexCommand \index{Loop reversing}
19810
19811 \end_inset
19812
19813
19814 \layout Standard
19815
19816 This optimization is done to reduce the overhead of checking loop boundaries
19817  for every iteration.
19818  Some simple loops can be reversed and implemented using a
19819 \begin_inset Quotes eld
19820 \end_inset
19821
19822 decrement and jump if not zero
19823 \begin_inset Quotes erd
19824 \end_inset
19825
19826  instruction.
19827  SDCC checks for the following criterion to determine if a loop is reversible
19828  (note: more sophisticated compilers use data-dependency analysis to make
19829  this determination, SDCC uses a more simple minded analysis).
19830 \layout Itemize
19831
19832 The 'for' loop is of the form
19833 \newline
19834
19835 \newline
19836
19837 \family typewriter
19838 for(<symbol> = <expression>; <sym> [< | <=] <expression>; [<sym>++ | <sym>
19839  += 1])
19840 \newline
19841 \SpecialChar ~
19842 \SpecialChar ~
19843 \SpecialChar ~
19844 \SpecialChar ~
19845 <for body>
19846 \layout Itemize
19847
19848 The <for body> does not contain
19849 \begin_inset Quotes eld
19850 \end_inset
19851
19852 continue
19853 \begin_inset Quotes erd
19854 \end_inset
19855
19856  or 'break
19857 \begin_inset Quotes erd
19858 \end_inset
19859
19860 .
19861 \layout Itemize
19862
19863 All goto's are contained within the loop.
19864 \layout Itemize
19865
19866 No function calls within the loop.
19867 \layout Itemize
19868
19869 The loop control variable <sym> is not assigned any value within the loop
19870 \layout Itemize
19871
19872 The loop control variable does NOT participate in any arithmetic operation
19873  within the loop.
19874 \layout Itemize
19875
19876 There are NO switch statements in the loop.
19877 \layout Subsection
19878
19879 Algebraic Simplifications
19880 \layout Standard
19881
19882 SDCC does numerous algebraic simplifications, the following is a small sub-set
19883  of these optimizations.
19884 \layout Verse
19885
19886
19887 \family typewriter
19888 i = j + 0;\SpecialChar ~
19889 \SpecialChar ~
19890 \SpecialChar ~
19891 \SpecialChar ~
19892  /* changed to: */\SpecialChar ~
19893 \SpecialChar ~
19894 \SpecialChar ~
19895 \SpecialChar ~
19896  i = j;
19897 \newline
19898 i /= 2;\SpecialChar ~
19899 \SpecialChar ~
19900 \SpecialChar ~
19901 \SpecialChar ~
19902 \SpecialChar ~
19903 \SpecialChar ~
19904 \SpecialChar ~
19905  /* changed to: */\SpecialChar ~
19906 \SpecialChar ~
19907 \SpecialChar ~
19908 \SpecialChar ~
19909  i >>= 1;
19910 \newline
19911 i = j - j;\SpecialChar ~
19912 \SpecialChar ~
19913 \SpecialChar ~
19914 \SpecialChar ~
19915  /* changed to: */\SpecialChar ~
19916 \SpecialChar ~
19917 \SpecialChar ~
19918 \SpecialChar ~
19919  i = 0;
19920 \newline
19921 i = j / 1;\SpecialChar ~
19922 \SpecialChar ~
19923 \SpecialChar ~
19924 \SpecialChar ~
19925  /* changed to: */\SpecialChar ~
19926 \SpecialChar ~
19927 \SpecialChar ~
19928 \SpecialChar ~
19929  i = j;
19930 \layout Standard
19931
19932 Note the subexpressions
19933 \begin_inset LatexCommand \index{Subexpression}
19934
19935 \end_inset
19936
19937  given above are generally introduced by macro expansions or as a result
19938  of copy/constant propagation.
19939 \layout Subsection
19940
19941 'switch' Statements
19942 \begin_inset LatexCommand \label{sub:'switch'-Statements}
19943
19944 \end_inset
19945
19946
19947 \begin_inset LatexCommand \index{switch statement}
19948
19949 \end_inset
19950
19951
19952 \layout Standard
19953
19954 SDCC can optimize switch statements to jump tables
19955 \begin_inset LatexCommand \index{jump tables}
19956
19957 \end_inset
19958
19959 .
19960  It makes the decision based on an estimate of the generated code size.
19961  SDCC is quite liberal in the requirements for jump table generation:
19962 \layout Itemize
19963
19964 The labels need not be in order, and the starting number need not be one
19965  or zero, the case labels are in numerical sequence or not too many case
19966  labels are missing.
19967 \begin_deeper
19968 \layout Verse
19969
19970
19971 \family typewriter
19972 switch(i) {\SpecialChar ~
19973 \SpecialChar ~
19974 \SpecialChar ~
19975 \SpecialChar ~
19976 \SpecialChar ~
19977 \SpecialChar ~
19978 \SpecialChar ~
19979 \SpecialChar ~
19980 \SpecialChar ~
19981 \SpecialChar ~
19982 \SpecialChar ~
19983 \SpecialChar ~
19984 \SpecialChar ~
19985 \SpecialChar ~
19986 \SpecialChar ~
19987 \SpecialChar ~
19988 \SpecialChar ~
19989 \SpecialChar ~
19990 \SpecialChar ~
19991 \SpecialChar ~
19992 \SpecialChar ~
19993 \SpecialChar ~
19994 \SpecialChar ~
19995 \SpecialChar ~
19996 \SpecialChar ~
19997 \SpecialChar ~
19998 switch (i) {
19999 \newline
20000 \SpecialChar ~
20001 \SpecialChar ~
20002 \SpecialChar ~
20003 case 4: ...\SpecialChar ~
20004 \SpecialChar ~
20005 \SpecialChar ~
20006 \SpecialChar ~
20007 \SpecialChar ~
20008 \SpecialChar ~
20009 \SpecialChar ~
20010 \SpecialChar ~
20011 \SpecialChar ~
20012 \SpecialChar ~
20013 \SpecialChar ~
20014 \SpecialChar ~
20015 \SpecialChar ~
20016 \SpecialChar ~
20017 \SpecialChar ~
20018 \SpecialChar ~
20019 \SpecialChar ~
20020 \SpecialChar ~
20021 \SpecialChar ~
20022 \SpecialChar ~
20023 \SpecialChar ~
20024 \SpecialChar ~
20025 \SpecialChar ~
20026 \SpecialChar ~
20027 \SpecialChar ~
20028 \SpecialChar ~
20029 case 0: ...
20030
20031 \newline
20032 \SpecialChar ~
20033 \SpecialChar ~
20034 \SpecialChar ~
20035 case 5: ...\SpecialChar ~
20036 \SpecialChar ~
20037 \SpecialChar ~
20038 \SpecialChar ~
20039 \SpecialChar ~
20040 \SpecialChar ~
20041 \SpecialChar ~
20042 \SpecialChar ~
20043 \SpecialChar ~
20044 \SpecialChar ~
20045 \SpecialChar ~
20046 \SpecialChar ~
20047 \SpecialChar ~
20048 \SpecialChar ~
20049 \SpecialChar ~
20050 \SpecialChar ~
20051 \SpecialChar ~
20052 \SpecialChar ~
20053 \SpecialChar ~
20054 \SpecialChar ~
20055 \SpecialChar ~
20056 \SpecialChar ~
20057 \SpecialChar ~
20058 \SpecialChar ~
20059 \SpecialChar ~
20060 \SpecialChar ~
20061 case 1: ...
20062
20063 \newline
20064 \SpecialChar ~
20065 \SpecialChar ~
20066 \SpecialChar ~
20067 case 3: ...\SpecialChar ~
20068 \SpecialChar ~
20069 \SpecialChar ~
20070 \SpecialChar ~
20071 \SpecialChar ~
20072 \SpecialChar ~
20073 \SpecialChar ~
20074 \SpecialChar ~
20075 \SpecialChar ~
20076 \SpecialChar ~
20077 \SpecialChar ~
20078 \SpecialChar ~
20079 \SpecialChar ~
20080 \SpecialChar ~
20081 \SpecialChar ~
20082 \SpecialChar ~
20083 \SpecialChar ~
20084 \SpecialChar ~
20085 \SpecialChar ~
20086 \SpecialChar ~
20087 \SpecialChar ~
20088 \SpecialChar ~
20089 \SpecialChar ~
20090 \SpecialChar ~
20091 \SpecialChar ~
20092 \SpecialChar ~
20093
20094 \newline
20095 \SpecialChar ~
20096 \SpecialChar ~
20097 \SpecialChar ~
20098 case 6: ...\SpecialChar ~
20099 \SpecialChar ~
20100 \SpecialChar ~
20101 \SpecialChar ~
20102 \SpecialChar ~
20103 \SpecialChar ~
20104 \SpecialChar ~
20105 \SpecialChar ~
20106 \SpecialChar ~
20107 \SpecialChar ~
20108 \SpecialChar ~
20109 \SpecialChar ~
20110 \SpecialChar ~
20111 \SpecialChar ~
20112 \SpecialChar ~
20113 \SpecialChar ~
20114 \SpecialChar ~
20115 \SpecialChar ~
20116 \SpecialChar ~
20117 \SpecialChar ~
20118 \SpecialChar ~
20119 \SpecialChar ~
20120 \SpecialChar ~
20121 \SpecialChar ~
20122 \SpecialChar ~
20123 \SpecialChar ~
20124 case 3: ...
20125
20126 \newline
20127 \SpecialChar ~
20128 \SpecialChar ~
20129 \SpecialChar ~
20130 case 7: ...\SpecialChar ~
20131 \SpecialChar ~
20132 \SpecialChar ~
20133 \SpecialChar ~
20134 \SpecialChar ~
20135 \SpecialChar ~
20136 \SpecialChar ~
20137 \SpecialChar ~
20138 \SpecialChar ~
20139 \SpecialChar ~
20140 \SpecialChar ~
20141 \SpecialChar ~
20142 \SpecialChar ~
20143 \SpecialChar ~
20144 \SpecialChar ~
20145 \SpecialChar ~
20146 \SpecialChar ~
20147 \SpecialChar ~
20148 \SpecialChar ~
20149 \SpecialChar ~
20150 \SpecialChar ~
20151 \SpecialChar ~
20152 \SpecialChar ~
20153 \SpecialChar ~
20154 \SpecialChar ~
20155 \SpecialChar ~
20156 case 4: ...
20157
20158 \newline
20159 \SpecialChar ~
20160 \SpecialChar ~
20161 \SpecialChar ~
20162 case 8: ...\SpecialChar ~
20163 \SpecialChar ~
20164 \SpecialChar ~
20165 \SpecialChar ~
20166 \SpecialChar ~
20167 \SpecialChar ~
20168 \SpecialChar ~
20169 \SpecialChar ~
20170 \SpecialChar ~
20171 \SpecialChar ~
20172 \SpecialChar ~
20173 \SpecialChar ~
20174 \SpecialChar ~
20175 \SpecialChar ~
20176 \SpecialChar ~
20177 \SpecialChar ~
20178 \SpecialChar ~
20179 \SpecialChar ~
20180 \SpecialChar ~
20181 \SpecialChar ~
20182 \SpecialChar ~
20183 \SpecialChar ~
20184 \SpecialChar ~
20185 \SpecialChar ~
20186 \SpecialChar ~
20187 \SpecialChar ~
20188 case 5: ...
20189
20190 \newline
20191 \SpecialChar ~
20192 \SpecialChar ~
20193 \SpecialChar ~
20194 case 9: ...\SpecialChar ~
20195 \SpecialChar ~
20196 \SpecialChar ~
20197 \SpecialChar ~
20198 \SpecialChar ~
20199 \SpecialChar ~
20200 \SpecialChar ~
20201 \SpecialChar ~
20202 \SpecialChar ~
20203 \SpecialChar ~
20204 \SpecialChar ~
20205 \SpecialChar ~
20206 \SpecialChar ~
20207 \SpecialChar ~
20208 \SpecialChar ~
20209 \SpecialChar ~
20210 \SpecialChar ~
20211 \SpecialChar ~
20212 \SpecialChar ~
20213 \SpecialChar ~
20214 \SpecialChar ~
20215 \SpecialChar ~
20216 \SpecialChar ~
20217 \SpecialChar ~
20218 \SpecialChar ~
20219 \SpecialChar ~
20220 case 6: ...
20221
20222 \newline
20223 \SpecialChar ~
20224 \SpecialChar ~
20225 \SpecialChar ~
20226 case 10: ...\SpecialChar ~
20227 \SpecialChar ~
20228 \SpecialChar ~
20229 \SpecialChar ~
20230 \SpecialChar ~
20231 \SpecialChar ~
20232 \SpecialChar ~
20233 \SpecialChar ~
20234 \SpecialChar ~
20235 \SpecialChar ~
20236 \SpecialChar ~
20237 \SpecialChar ~
20238 \SpecialChar ~
20239 \SpecialChar ~
20240 \SpecialChar ~
20241 \SpecialChar ~
20242 \SpecialChar ~
20243 \SpecialChar ~
20244 \SpecialChar ~
20245 \SpecialChar ~
20246 \SpecialChar ~
20247 \SpecialChar ~
20248 \SpecialChar ~
20249 \SpecialChar ~
20250 \SpecialChar ~
20251 case 7: ...
20252
20253 \newline
20254 \SpecialChar ~
20255 \SpecialChar ~
20256 \SpecialChar ~
20257 case 11: ...\SpecialChar ~
20258 \SpecialChar ~
20259 \SpecialChar ~
20260 \SpecialChar ~
20261 \SpecialChar ~
20262 \SpecialChar ~
20263 \SpecialChar ~
20264 \SpecialChar ~
20265 \SpecialChar ~
20266 \SpecialChar ~
20267 \SpecialChar ~
20268 \SpecialChar ~
20269 \SpecialChar ~
20270 \SpecialChar ~
20271 \SpecialChar ~
20272 \SpecialChar ~
20273 \SpecialChar ~
20274 \SpecialChar ~
20275 \SpecialChar ~
20276 \SpecialChar ~
20277 \SpecialChar ~
20278 \SpecialChar ~
20279 \SpecialChar ~
20280 \SpecialChar ~
20281 \SpecialChar ~
20282 case 8: ...
20283
20284 \newline
20285 }\SpecialChar ~
20286 \SpecialChar ~
20287 \SpecialChar ~
20288 \SpecialChar ~
20289 \SpecialChar ~
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 \SpecialChar ~
20305 \SpecialChar ~
20306 \SpecialChar ~
20307 \SpecialChar ~
20308 \SpecialChar ~
20309 \SpecialChar ~
20310 \SpecialChar ~
20311 \SpecialChar ~
20312 \SpecialChar ~
20313 \SpecialChar ~
20314 \SpecialChar ~
20315 \SpecialChar ~
20316 \SpecialChar ~
20317 \SpecialChar ~
20318 \SpecialChar ~
20319 \SpecialChar ~
20320 \SpecialChar ~
20321 }
20322 \layout Standard
20323
20324 Both the above switch statements will be implemented using a jump-table.
20325  The example to the right side is slightly more efficient as the check for
20326  the lower boundary of the jump-table is not needed.
20327 \end_deeper
20328 \layout Itemize
20329
20330 The number of case labels is not larger than supported by the target architectur
20331 e.
20332 \layout Itemize
20333
20334 If the case labels are not in numerical sequence ('gaps' between cases)
20335  SDCC checks whether a jump table with additionally inserted dummy cases
20336  is still attractive.
20337
20338 \layout Itemize
20339
20340 If the starting number is not zero and a check for the lower boundary of
20341  the jump-table can thus be eliminated SDCC might insert dummy cases 0,
20342  ...
20343  .
20344 \layout Standard
20345
20346 Switch statements which have large gaps in the numeric sequence or those
20347  that have too many case labels can be split into more than one switch statement
20348  for efficient code generation, e.g.:
20349 \layout Verse
20350
20351
20352 \family typewriter
20353 switch (i) {
20354 \newline
20355 \SpecialChar ~
20356 \SpecialChar ~
20357 case 1: ...
20358
20359 \newline
20360 \SpecialChar ~
20361 \SpecialChar ~
20362 case 2: ...
20363
20364 \newline
20365 \SpecialChar ~
20366 \SpecialChar ~
20367 case 3: ...
20368
20369 \newline
20370 \SpecialChar ~
20371 \SpecialChar ~
20372 case 4: ...
20373
20374 \newline
20375 \SpecialChar ~
20376 \SpecialChar ~
20377 case 5: ...
20378
20379 \newline
20380 \SpecialChar ~
20381 \SpecialChar ~
20382 case 6: ...
20383
20384 \newline
20385 \SpecialChar ~
20386 \SpecialChar ~
20387 case 7: ...
20388
20389 \newline
20390 \SpecialChar ~
20391 \SpecialChar ~
20392 case 101: ...
20393
20394 \newline
20395 \SpecialChar ~
20396 \SpecialChar ~
20397 case 102: ...
20398
20399 \newline
20400 \SpecialChar ~
20401 \SpecialChar ~
20402 case 103: ...
20403
20404 \newline
20405 \SpecialChar ~
20406 \SpecialChar ~
20407 case 104: ...
20408
20409 \newline
20410 \SpecialChar ~
20411 \SpecialChar ~
20412 case 105: ...
20413
20414 \newline
20415 \SpecialChar ~
20416 \SpecialChar ~
20417 case 106: ...
20418
20419 \newline
20420 \SpecialChar ~
20421 \SpecialChar ~
20422 case 107: ...
20423
20424 \newline
20425 }
20426 \layout Standard
20427
20428 If the above switch statement is broken down into two switch statements
20429 \layout Verse
20430
20431
20432 \family typewriter
20433 switch (i) {
20434 \newline
20435 \SpecialChar ~
20436 \SpecialChar ~
20437 case 1: ...
20438
20439 \newline
20440 \SpecialChar ~
20441 \SpecialChar ~
20442 case 2: ...
20443
20444 \newline
20445 \SpecialChar ~
20446 \SpecialChar ~
20447 case 3: ...
20448
20449 \newline
20450 \SpecialChar ~
20451 \SpecialChar ~
20452 case 4: ...
20453
20454 \newline
20455 \SpecialChar ~
20456 \SpecialChar ~
20457 case 5: ...
20458
20459 \newline
20460 \SpecialChar ~
20461 \SpecialChar ~
20462 case 6: ...
20463
20464 \newline
20465 \SpecialChar ~
20466 \SpecialChar ~
20467 case 7: ...
20468
20469 \newline
20470 }
20471 \layout Standard
20472
20473 and
20474 \layout Verse
20475
20476
20477 \family typewriter
20478 switch (i) {
20479 \newline
20480 \SpecialChar ~
20481 \SpecialChar ~
20482 case 101: ...
20483
20484 \newline
20485 \SpecialChar ~
20486 \SpecialChar ~
20487 case 102: ...
20488
20489 \newline
20490 \SpecialChar ~
20491 \SpecialChar ~
20492 case 103: ...
20493
20494 \newline
20495 \SpecialChar ~
20496 \SpecialChar ~
20497 case 104: ...
20498
20499 \newline
20500 \SpecialChar ~
20501 \SpecialChar ~
20502 case 105: ...
20503
20504 \newline
20505 \SpecialChar ~
20506 \SpecialChar ~
20507 case 106: ...
20508
20509 \newline
20510 \SpecialChar ~
20511 \SpecialChar ~
20512 case 107: ...
20513
20514 \newline
20515 }
20516 \layout Standard
20517
20518 then both the switch statements will be implemented using jump-tables whereas
20519  the unmodified switch statement will not be.
20520 \layout Comment
20521
20522 There might be reasons which SDCC cannot know about to either favour or
20523  not favour jump tables.
20524  If the target system has to be as quick for the last switch case as for
20525  the first (pro jump table), or if the switch argument is known to be zero
20526  in the majority of the cases (contra jump table).
20527 \layout Standard
20528
20529 The pragma nojtbound
20530 \begin_inset LatexCommand \index{\#pragma nojtbound}
20531
20532 \end_inset
20533
20534  can be used to turn off checking the
20535 \emph on
20536 j
20537 \emph default
20538 ump
20539 \emph on
20540 t
20541 \emph default
20542 able
20543 \emph on
20544 bound
20545 \emph default
20546 aries.
20547  It has no effect if a default label is supplied.
20548  Use of this pragma is dangerous: if the switch argument is not matched
20549  by a case statement the processor will happily jump into Nirvana.
20550 \layout Subsection
20551
20552 Bit-shifting Operations
20553 \begin_inset LatexCommand \index{Bit shifting}
20554
20555 \end_inset
20556
20557 .
20558 \layout Standard
20559
20560 Bit shifting is one of the most frequently used operation in embedded programmin
20561 g.
20562  SDCC tries to implement bit-shift operations in the most efficient way
20563  possible, e.g.:
20564 \layout Verse
20565
20566
20567 \family typewriter
20568 unsigned char i;
20569 \newline
20570 ...
20571
20572 \newline
20573 i >>= 4;
20574 \newline
20575 ...
20576 \layout Standard
20577
20578 generates the following code:
20579 \layout Verse
20580
20581
20582 \family typewriter
20583 mov\SpecialChar ~
20584  a,_i
20585 \newline
20586 swap a
20587 \newline
20588 anl\SpecialChar ~
20589  a,#0x0f
20590 \newline
20591 mov\SpecialChar ~
20592  _i,a
20593 \layout Standard
20594
20595 In general SDCC will never setup a loop if the shift count is known.
20596  Another example:
20597 \layout Verse
20598
20599
20600 \family typewriter
20601 unsigned int i;
20602 \newline
20603 ...
20604
20605 \newline
20606 i >>= 9;
20607 \newline
20608 ...
20609 \layout Standard
20610
20611 will generate:
20612 \layout Verse
20613
20614
20615 \family typewriter
20616 mov\SpecialChar ~
20617 \SpecialChar ~
20618 a,(_i + 1)
20619 \newline
20620 mov\SpecialChar ~
20621 \SpecialChar ~
20622 (_i + 1),#0x00
20623 \newline
20624 clr\SpecialChar ~
20625 \SpecialChar ~
20626 c
20627 \newline
20628 rrc\SpecialChar ~
20629 \SpecialChar ~
20630 a
20631 \newline
20632 mov\SpecialChar ~
20633 \SpecialChar ~
20634 _i,a
20635 \layout Subsection
20636
20637 Bit-rotation
20638 \begin_inset LatexCommand \index{Bit rotation}
20639
20640 \end_inset
20641
20642
20643 \layout Standard
20644
20645 A special case of the bit-shift operation is bit rotation
20646 \begin_inset LatexCommand \index{rotating bits}
20647
20648 \end_inset
20649
20650 , SDCC recognizes the following expression to be a left bit-rotation:
20651 \layout Verse
20652
20653
20654 \family typewriter
20655 \series bold
20656 unsigned
20657 \series default
20658 \SpecialChar ~
20659 \SpecialChar ~
20660 char i;\SpecialChar ~
20661 \SpecialChar ~
20662 \SpecialChar ~
20663 \SpecialChar ~
20664 \SpecialChar ~
20665 \SpecialChar ~
20666 \SpecialChar ~
20667 \SpecialChar ~
20668 \SpecialChar ~
20669 \SpecialChar ~
20670 \SpecialChar ~
20671 /* unsigned is needed for rotation */
20672 \newline
20673 ...
20674
20675 \newline
20676 i = ((i << 1) | (i >> 7));
20677 \family default
20678
20679 \newline
20680
20681 \family typewriter
20682 ...
20683 \layout Standard
20684
20685 will generate the following code:
20686 \layout Verse
20687
20688
20689 \family typewriter
20690 mov\SpecialChar ~
20691 \SpecialChar ~
20692 a,_i
20693 \newline
20694 rl\SpecialChar ~
20695 \SpecialChar ~
20696 \SpecialChar ~
20697 a
20698 \newline
20699 mov\SpecialChar ~
20700 \SpecialChar ~
20701 _i,a
20702 \layout Standard
20703
20704 SDCC uses pattern matching on the parse tree to determine this operation.Variatio
20705 ns of this case will also be recognized as bit-rotation, i.e.:
20706 \layout Verse
20707
20708
20709 \family typewriter
20710 i = ((i >> 7) | (i << 1)); /* left-bit rotation */
20711 \layout Subsection
20712
20713 Nibble and Byte Swapping
20714 \layout Standard
20715
20716 Other special cases of the bit-shift operations are nibble or byte swapping
20717 \begin_inset LatexCommand \index{swapping nibbles/bytes}
20718
20719 \end_inset
20720
20721 , SDCC recognizes the following expressions:
20722 \layout Verse
20723
20724
20725 \family typewriter
20726 \series bold
20727 unsigned
20728 \series default
20729 \SpecialChar ~
20730 \SpecialChar ~
20731 char i;
20732 \newline
20733
20734 \series bold
20735 unsigned
20736 \series default
20737 \SpecialChar ~
20738 \SpecialChar ~
20739 int j;
20740 \newline
20741 ...
20742
20743 \newline
20744 i = ((i << 4) | (i >> 4));
20745 \family default
20746
20747 \newline
20748
20749 \family typewriter
20750 j = ((j << 8) | (j >> 8));
20751 \layout Standard
20752
20753 and generates a swap instruction for the nibble swapping
20754 \begin_inset LatexCommand \index{Nibble swapping}
20755
20756 \end_inset
20757
20758  or move instructions for the byte swapping
20759 \begin_inset LatexCommand \index{Byte swapping}
20760
20761 \end_inset
20762
20763 .
20764  The
20765 \begin_inset Quotes sld
20766 \end_inset
20767
20768 j
20769 \begin_inset Quotes srd
20770 \end_inset
20771
20772  example can be used to convert from little to big-endian or vice versa.
20773  If you want to change the endianness of a
20774 \emph on
20775 signed
20776 \emph default
20777  integer you have to cast to
20778 \family typewriter
20779 (unsigned int)
20780 \family default
20781  first.
20782 \layout Standard
20783
20784 Note that SDCC stores numbers in little-endian
20785 \begin_inset Foot
20786 collapsed false
20787
20788 \layout Standard
20789
20790 Usually 8-bit processors don't care much about endianness.
20791  This is not the case for the standard 8051 which only has an instruction
20792  to increment its
20793 \emph on
20794 dptr
20795 \emph default
20796
20797 \begin_inset LatexCommand \index{DPTR}
20798
20799 \end_inset
20800
20801 -datapointer
20802 \emph on
20803
20804 \emph default
20805 so little-endian is the more efficient byte order.
20806 \end_inset
20807
20808
20809 \begin_inset LatexCommand \index{little-endian}
20810
20811 \end_inset
20812
20813
20814 \begin_inset LatexCommand \index{Endianness}
20815
20816 \end_inset
20817
20818  format (i.e.
20819  lowest order first).
20820 \layout Subsection
20821
20822 Highest Order Bit
20823 \begin_inset LatexCommand \index{Highest Order Bit}
20824
20825 \end_inset
20826
20827
20828 \layout Standard
20829
20830 It is frequently required to obtain the highest order bit of an integral
20831  type (long, int, short or char types).
20832  SDCC recognizes the following expression to yield the highest order bit
20833  and generates optimized code for it, e.g.:
20834 \layout Verse
20835
20836
20837 \family typewriter
20838 unsigned int gint;
20839 \newline
20840
20841 \newline
20842 foo () {
20843 \newline
20844 \SpecialChar ~
20845 \SpecialChar ~
20846 unsigned char hob;
20847 \newline
20848 \SpecialChar ~
20849 \SpecialChar ~
20850 ...
20851
20852 \newline
20853 \SpecialChar ~
20854 \SpecialChar ~
20855 hob = (gint >> 15) & 1;
20856 \newline
20857 \SpecialChar ~
20858 \SpecialChar ~
20859 ..
20860
20861 \newline
20862 }
20863 \layout Standard
20864
20865 will generate the following code:
20866 \layout Verse
20867
20868
20869 \family typewriter
20870 \SpecialChar ~
20871 \SpecialChar ~
20872 \SpecialChar ~
20873 \SpecialChar ~
20874 \SpecialChar ~
20875 \SpecialChar ~
20876 \SpecialChar ~
20877 \SpecialChar ~
20878 \SpecialChar ~
20879 \SpecialChar ~
20880 \SpecialChar ~
20881 \SpecialChar ~
20882 \SpecialChar ~
20883 \SpecialChar ~
20884 \SpecialChar ~
20885 \SpecialChar ~
20886 \SpecialChar ~
20887 \SpecialChar ~
20888 \SpecialChar ~
20889 \SpecialChar ~
20890 \SpecialChar ~
20891 \SpecialChar ~
20892 \SpecialChar ~
20893 \SpecialChar ~
20894 \SpecialChar ~
20895  61 ;\SpecialChar ~
20896  hob.c 7
20897 \newline
20898 000A E5*01\SpecialChar ~
20899 \SpecialChar ~
20900 \SpecialChar ~
20901 \SpecialChar ~
20902 \SpecialChar ~
20903 \SpecialChar ~
20904 \SpecialChar ~
20905 \SpecialChar ~
20906 \SpecialChar ~
20907 \SpecialChar ~
20908 \SpecialChar ~
20909 \SpecialChar ~
20910 \SpecialChar ~
20911 \SpecialChar ~
20912 \SpecialChar ~
20913  62\SpecialChar ~
20914 \SpecialChar ~
20915 \SpecialChar ~
20916 \SpecialChar ~
20917 \SpecialChar ~
20918 \SpecialChar ~
20919 \SpecialChar ~
20920 \SpecialChar ~
20921  mov\SpecialChar ~
20922 \SpecialChar ~
20923  a,(_gint + 1)
20924 \newline
20925 000C 23\SpecialChar ~
20926 \SpecialChar ~
20927 \SpecialChar ~
20928 \SpecialChar ~
20929 \SpecialChar ~
20930 \SpecialChar ~
20931 \SpecialChar ~
20932 \SpecialChar ~
20933 \SpecialChar ~
20934 \SpecialChar ~
20935 \SpecialChar ~
20936 \SpecialChar ~
20937 \SpecialChar ~
20938 \SpecialChar ~
20939 \SpecialChar ~
20940 \SpecialChar ~
20941 \SpecialChar ~
20942 \SpecialChar ~
20943  63\SpecialChar ~
20944 \SpecialChar ~
20945 \SpecialChar ~
20946 \SpecialChar ~
20947 \SpecialChar ~
20948 \SpecialChar ~
20949 \SpecialChar ~
20950 \SpecialChar ~
20951  rl\SpecialChar ~
20952 \SpecialChar ~
20953 \SpecialChar ~
20954  a
20955 \newline
20956 000D 54 01\SpecialChar ~
20957 \SpecialChar ~
20958 \SpecialChar ~
20959 \SpecialChar ~
20960 \SpecialChar ~
20961 \SpecialChar ~
20962 \SpecialChar ~
20963 \SpecialChar ~
20964 \SpecialChar ~
20965 \SpecialChar ~
20966 \SpecialChar ~
20967 \SpecialChar ~
20968 \SpecialChar ~
20969 \SpecialChar ~
20970 \SpecialChar ~
20971  64\SpecialChar ~
20972 \SpecialChar ~
20973 \SpecialChar ~
20974 \SpecialChar ~
20975 \SpecialChar ~
20976 \SpecialChar ~
20977 \SpecialChar ~
20978 \SpecialChar ~
20979  anl\SpecialChar ~
20980 \SpecialChar ~
20981  a,#0x01
20982 \newline
20983 000F F5*02\SpecialChar ~
20984 \SpecialChar ~
20985 \SpecialChar ~
20986 \SpecialChar ~
20987 \SpecialChar ~
20988 \SpecialChar ~
20989 \SpecialChar ~
20990 \SpecialChar ~
20991 \SpecialChar ~
20992 \SpecialChar ~
20993 \SpecialChar ~
20994 \SpecialChar ~
20995 \SpecialChar ~
20996 \SpecialChar ~
20997 \SpecialChar ~
20998  65\SpecialChar ~
20999 \SpecialChar ~
21000 \SpecialChar ~
21001 \SpecialChar ~
21002 \SpecialChar ~
21003 \SpecialChar ~
21004 \SpecialChar ~
21005 \SpecialChar ~
21006  mov\SpecialChar ~
21007 \SpecialChar ~
21008  _foo_hob_1_1,a
21009 \layout Standard
21010
21011 Variations of this case however will
21012 \emph on
21013 not
21014 \emph default
21015  be recognized.
21016  It is a standard C expression, so I heartily recommend this be the only
21017  way to get the highest order bit, (it is portable).
21018  Of course it will be recognized even if it is embedded in other expressions,
21019  e.g.:
21020 \layout Verse
21021
21022
21023 \family typewriter
21024 xyz = gint + ((gint >> 15) & 1);
21025 \layout Standard
21026
21027 will still be recognized.
21028 \layout Subsection
21029
21030 Peephole Optimizer
21031 \begin_inset LatexCommand \label{sub:Peephole-Optimizer}
21032
21033 \end_inset
21034
21035
21036 \begin_inset LatexCommand \index{Peephole optimizer}
21037
21038 \end_inset
21039
21040
21041 \layout Standard
21042
21043 The compiler uses a rule based, pattern matching and re-writing mechanism
21044  for peep-hole optimization.
21045  It is inspired by
21046 \emph on
21047 copt
21048 \emph default
21049  a peep-hole optimizer by Christopher W.
21050  Fraser (cwfraser@microsoft.com).
21051  A default set of rules are compiled into the compiler, additional rules
21052  may be added with the
21053 \emph on
21054 -
21055 \begin_inset ERT
21056 status Collapsed
21057
21058 \layout Standard
21059
21060 \backslash
21061 /
21062 \end_inset
21063
21064 -peep-file
21065 \begin_inset LatexCommand \index{-\/-peep-file}
21066
21067 \end_inset
21068
21069  <filename>
21070 \emph default
21071  option.
21072  The rule language is best illustrated with examples.
21073 \layout Verse
21074
21075
21076 \family typewriter
21077 replace {
21078 \newline
21079 \SpecialChar ~
21080 \SpecialChar ~
21081 mov %1,a
21082 \newline
21083 \SpecialChar ~
21084 \SpecialChar ~
21085 mov a,%1
21086 \newline
21087 } by {
21088 \newline
21089 \SpecialChar ~
21090 \SpecialChar ~
21091 mov %1,a
21092 \newline
21093 }
21094 \layout Standard
21095
21096 The above rule will change the following assembly
21097 \begin_inset LatexCommand \index{Assembler routines}
21098
21099 \end_inset
21100
21101  sequence:
21102 \layout Verse
21103
21104
21105 \family typewriter
21106 mov r1,a
21107 \newline
21108 mov a,r1
21109 \layout Standard
21110
21111 to
21112 \layout Verse
21113
21114
21115 \family typewriter
21116 mov r1,a
21117 \layout Standard
21118
21119 Note: All occurrences of a
21120 \emph on
21121 %n
21122 \emph default
21123  (pattern variable) must denote the same string.
21124  With the above rule, the assembly sequence:
21125 \layout Verse
21126
21127
21128 \family typewriter
21129 mov r1,a
21130 \newline
21131 mov a,r2
21132 \layout Standard
21133
21134 will remain unmodified.
21135 \newline
21136
21137 \newline
21138 Other special case optimizations may be added by the user (via
21139 \emph on
21140 -
21141 \begin_inset ERT
21142 status Collapsed
21143
21144 \layout Standard
21145
21146 \backslash
21147 /
21148 \end_inset
21149
21150 -peep-file option
21151 \emph default
21152 ).
21153  E.g.
21154  some variants of the 8051 MCU
21155 \begin_inset LatexCommand \index{MCS51 variants}
21156
21157 \end_inset
21158
21159  allow only
21160 \family typewriter
21161 ajmp
21162 \family default
21163  and
21164 \family typewriter
21165 acall
21166 \family default
21167 .
21168  The following two rules will change all
21169 \family typewriter
21170 ljmp
21171 \family default
21172  and
21173 \family typewriter
21174 lcall
21175 \family default
21176  to
21177 \family typewriter
21178 ajmp
21179 \family default
21180  and
21181 \family typewriter
21182 acall
21183 \layout Verse
21184
21185
21186 \family typewriter
21187 replace { lcall %1 } by { acall %1 }
21188 \newline
21189 replace { ljmp %1 } by { ajmp %1 }
21190 \layout Standard
21191
21192 The
21193 \emph on
21194 inline-assembler code
21195 \emph default
21196  is also passed through the peep hole optimizer, thus the peephole optimizer
21197  can also be used as an assembly level macro expander.
21198  The rules themselves are MCU dependent whereas the rule language infra-structur
21199 e is MCU independent.
21200  Peephole optimization rules for other MCU can be easily programmed using
21201  the rule language.
21202 \newline
21203
21204 \newline
21205 The syntax for a rule is as follows:
21206 \layout Verse
21207
21208
21209 \family typewriter
21210 rule := replace [ restart ] '{' <assembly sequence> '
21211 \backslash
21212 n'
21213 \newline
21214 \SpecialChar ~
21215  \SpecialChar ~
21216  \SpecialChar ~
21217  \SpecialChar ~
21218  \SpecialChar ~
21219  \SpecialChar ~
21220  \SpecialChar ~
21221  \SpecialChar ~
21222  \SpecialChar ~
21223  \SpecialChar ~
21224  \SpecialChar ~
21225  \SpecialChar ~
21226  \SpecialChar ~
21227  \SpecialChar ~
21228  '}' by '{' '
21229 \backslash
21230 n'
21231 \newline
21232 \SpecialChar ~
21233  \SpecialChar ~
21234  \SpecialChar ~
21235  \SpecialChar ~
21236  \SpecialChar ~
21237  \SpecialChar ~
21238  \SpecialChar ~
21239  \SpecialChar ~
21240  \SpecialChar ~
21241  \SpecialChar ~
21242  \SpecialChar ~
21243  \SpecialChar ~
21244  \SpecialChar ~
21245  \SpecialChar ~
21246  \SpecialChar ~
21247  \SpecialChar ~
21248  <assembly sequence> '
21249 \backslash
21250 n'
21251 \newline
21252 \SpecialChar ~
21253  \SpecialChar ~
21254  \SpecialChar ~
21255  \SpecialChar ~
21256  \SpecialChar ~
21257  \SpecialChar ~
21258  \SpecialChar ~
21259  \SpecialChar ~
21260  \SpecialChar ~
21261  \SpecialChar ~
21262  \SpecialChar ~
21263  \SpecialChar ~
21264  \SpecialChar ~
21265  \SpecialChar ~
21266  '}' [if <functionName> ] '
21267 \backslash
21268 n'
21269 \layout Standard
21270
21271 <assembly sequence> := assembly instruction (each instruction including
21272  labels must be on a separate line).
21273 \newline
21274
21275 \newline
21276 The optimizer will apply to the rules one by one from the top in the sequence
21277  of their appearance, it will terminate when all rules are exhausted.
21278  If the 'restart' option is specified, then the optimizer will start matching
21279  the rules again from the top, this option for a rule is expensive (performance)
21280 , it is intended to be used in situations where a transformation will trigger
21281  the same rule again.
21282  An example of this (not a good one, it has side effects) is the following
21283  rule:
21284 \layout Verse
21285
21286
21287 \family typewriter
21288 replace restart {
21289 \newline
21290 \SpecialChar ~
21291 \SpecialChar ~
21292 pop %1
21293 \newline
21294 \SpecialChar ~
21295 \SpecialChar ~
21296 push %1 } by {
21297 \newline
21298 \SpecialChar ~
21299 \SpecialChar ~
21300 ; nop
21301 \newline
21302 }
21303 \layout Standard
21304
21305 Note that the replace pattern cannot be a blank, but can be a comment line.
21306  Without the 'restart' option only the innermost 'pop' 'push' pair would
21307  be eliminated, i.e.:
21308 \layout Verse
21309
21310
21311 \family typewriter
21312 pop ar1
21313 \newline
21314 pop ar2
21315 \newline
21316 push ar2
21317 \newline
21318 push ar1
21319 \layout Standard
21320
21321 would result in:
21322 \layout Verse
21323
21324
21325 \family typewriter
21326 pop ar1
21327 \newline
21328 ; nop
21329 \newline
21330 push ar1
21331 \layout Standard
21332
21333
21334 \emph on
21335 with
21336 \emph default
21337  the restart option the rule will be applied again to the resulting code
21338  and then all the pop-push pairs will be eliminated to yield:
21339 \layout Verse
21340
21341
21342 \family typewriter
21343 ; nop
21344 \newline
21345 ; nop
21346 \layout Standard
21347
21348 A conditional function can be attached to a rule.
21349  Attaching rules are somewhat more involved, let me illustrate this with
21350  an example.
21351 \layout Verse
21352
21353
21354 \family typewriter
21355 replace {
21356 \newline
21357 \SpecialChar ~
21358  \SpecialChar ~
21359  \SpecialChar ~
21360 ljmp %5
21361 \newline
21362 %2:
21363 \newline
21364 } by {
21365 \newline
21366 \SpecialChar ~
21367  \SpecialChar ~
21368  \SpecialChar ~
21369 sjmp %5
21370 \newline
21371 %2:
21372 \newline
21373 } if labelInRange
21374 \layout Standard
21375
21376 The optimizer does a look-up of a function name table defined in function
21377
21378 \emph on
21379 callFuncByName
21380 \emph default
21381  in the source file SDCCpeeph.c, with the name
21382 \emph on
21383 labelInRange
21384 \emph default
21385 .
21386  If it finds a corresponding entry the function is called.
21387  Note there can be no parameters specified for these functions, in this
21388  case the use of
21389 \emph on
21390 %5
21391 \emph default
21392  is crucial, since the function
21393 \emph on
21394 labelInRange
21395 \emph default
21396  expects to find the label in that particular variable (the hash table containin
21397 g the variable bindings is passed as a parameter).
21398  If you want to code more such functions, take a close look at the function
21399  labelInRange and the calling mechanism in source file SDCCpeeph.c.
21400  Currently implemented are
21401 \emph on
21402 labelInRange, labelRefCount, labelIsReturnOnly, operandsNotSame, xramMovcOption,
21403  24bitMode, portIsDS390, 24bitModeAndPortDS390
21404 \emph default
21405 and
21406 \emph on
21407  notVolatile
21408 \emph default
21409 .
21410 \layout Standard
21411
21412 I know this whole thing is a little kludgey, but maybe some day we will
21413  have some better means.
21414  If you are looking at this file, you will see the default rules that are
21415  compiled into the compiler, you can add your own rules in the default set
21416  there if you get tired of specifying the -
21417 \begin_inset ERT
21418 status Collapsed
21419
21420 \layout Standard
21421
21422 \backslash
21423 /
21424 \end_inset
21425
21426 -peep-file option.
21427 \layout Section
21428
21429 ANSI-Compliance
21430 \begin_inset LatexCommand \index{ANSI-compliance}
21431
21432 \end_inset
21433
21434
21435 \begin_inset LatexCommand \label{sub:ANSI-Compliance}
21436
21437 \end_inset
21438
21439
21440 \layout Standard
21441
21442 Deviations from the compliance:
21443 \layout Itemize
21444
21445 functions are not always reentrant
21446 \begin_inset LatexCommand \index{reentrant}
21447
21448 \end_inset
21449
21450 .
21451 \layout Itemize
21452
21453 structures cannot be assigned values directly, cannot be passed as function
21454  parameters or assigned to each other and cannot be a return value from
21455  a function, e.g.:
21456 \begin_deeper
21457 \layout Verse
21458
21459
21460 \family typewriter
21461 struct s { ...
21462  };
21463 \newline
21464 struct s s1, s2;
21465 \newline
21466 foo()
21467 \newline
21468 {
21469 \newline
21470 \SpecialChar ~
21471 \SpecialChar ~
21472 \SpecialChar ~
21473 \SpecialChar ~
21474 ...
21475
21476 \newline
21477 \SpecialChar ~
21478 \SpecialChar ~
21479 \SpecialChar ~
21480 \SpecialChar ~
21481 s1 = s2 ; /* is invalid in SDCC although allowed in ANSI */
21482 \newline
21483 \SpecialChar ~
21484 \SpecialChar ~
21485 \SpecialChar ~
21486 \SpecialChar ~
21487 ...
21488
21489 \newline
21490 }
21491 \newline
21492 struct s foo1 (struct s parms) /* invalid in SDCC although allowed in ANSI
21493  */
21494 \newline
21495 {
21496 \newline
21497 \SpecialChar ~
21498 \SpecialChar ~
21499 \SpecialChar ~
21500 \SpecialChar ~
21501 struct s rets;
21502 \newline
21503 \SpecialChar ~
21504 \SpecialChar ~
21505 \SpecialChar ~
21506 \SpecialChar ~
21507 ...
21508
21509 \newline
21510 \SpecialChar ~
21511 \SpecialChar ~
21512 \SpecialChar ~
21513 \SpecialChar ~
21514 return rets;/* is invalid in SDCC although allowed in ANSI */
21515 \newline
21516 }
21517 \end_deeper
21518 \layout Itemize
21519
21520 'long long
21521 \begin_inset LatexCommand \index{long long (not supported)}
21522
21523 \end_inset
21524
21525 ' (64 bit integers
21526 \begin_inset LatexCommand \index{int (64 bit) (not supported)}
21527
21528 \end_inset
21529
21530 ) not supported.
21531 \layout Itemize
21532
21533 'double
21534 \begin_inset LatexCommand \index{double (not supported)}
21535
21536 \end_inset
21537
21538 ' precision floating point
21539 \begin_inset LatexCommand \index{Floating point support}
21540
21541 \end_inset
21542
21543 not supported.
21544 \layout Itemize
21545
21546 No support for setjmp
21547 \begin_inset LatexCommand \index{setjmp (not supported)}
21548
21549 \end_inset
21550
21551  and longjmp
21552 \begin_inset LatexCommand \index{longjmp (not supported)}
21553
21554 \end_inset
21555
21556  (for now).
21557 \layout Itemize
21558
21559 Old K&R style
21560 \begin_inset LatexCommand \index{K\&R style}
21561
21562 \end_inset
21563
21564  function declarations are NOT allowed.
21565 \begin_deeper
21566 \layout Verse
21567
21568
21569 \family typewriter
21570 foo(i,j) /* this old style of function declarations */
21571 \newline
21572 int i,j; /* are valid in ANSI but not valid in SDCC */
21573 \newline
21574 {
21575 \newline
21576 \SpecialChar ~
21577 \SpecialChar ~
21578 \SpecialChar ~
21579 \SpecialChar ~
21580 ...
21581
21582 \newline
21583 }
21584 \end_deeper
21585 \layout Section
21586
21587 Cyclomatic Complexity
21588 \begin_inset LatexCommand \index{Cyclomatic complexity}
21589
21590 \end_inset
21591
21592
21593 \layout Standard
21594
21595 Cyclomatic complexity of a function is defined as the number of independent
21596  paths the program can take during execution of the function.
21597  This is an important number since it defines the number test cases you
21598  have to generate to validate the function.
21599  The accepted industry standard for complexity number is 10, if the cyclomatic
21600  complexity reported by SDCC exceeds 10 you should think about simplification
21601  of the function logic.
21602  Note that the complexity level is not related to the number of lines of
21603  code in a function.
21604  Large functions can have low complexity, and small functions can have large
21605  complexity levels.
21606
21607 \newline
21608
21609 \newline
21610 SDCC uses the following formula to compute the complexity:
21611 \newline
21612
21613 \layout Standard
21614
21615 complexity = (number of edges in control flow graph) - (number of nodes
21616  in control flow graph) + 2;
21617 \newline
21618
21619 \newline
21620 Having said that the industry standard is 10, you should be aware that in
21621  some cases it be may unavoidable to have a complexity level of less than
21622  10.
21623  For example if you have switch statement with more than 10 case labels,
21624  each case label adds one to the complexity level.
21625  The complexity level is by no means an absolute measure of the algorithmic
21626  complexity of the function, it does however provide a good starting point
21627  for which functions you might look at for further optimization.
21628 \layout Section
21629
21630 Retargetting for other Processors
21631 \layout Standard
21632
21633 The issues for retargetting the compiler are far too numerous to be covered
21634  by this document.
21635  What follows is a brief description of each of the seven phases of the
21636  compiler and its MCU dependency.
21637 \layout Itemize
21638
21639 Parsing the source and building the annotated parse tree.
21640  This phase is largely MCU independent (except for the language extensions).
21641  Syntax & semantic checks are also done in this phase, along with some initial
21642  optimizations like back patching labels and the pattern matching optimizations
21643  like bit-rotation etc.
21644 \layout Itemize
21645
21646 The second phase involves generating an intermediate code which can be easy
21647  manipulated during the later phases.
21648  This phase is entirely MCU independent.
21649  The intermediate code generation assumes the target machine has unlimited
21650  number of registers, and designates them with the name iTemp.
21651  The compiler can be made to dump a human readable form of the code generated
21652  by using the -
21653 \begin_inset ERT
21654 status Collapsed
21655
21656 \layout Standard
21657
21658 \backslash
21659 /
21660 \end_inset
21661
21662 -dumpraw option.
21663 \layout Itemize
21664
21665 This phase does the bulk of the standard optimizations and is also MCU independe
21666 nt.
21667  This phase can be broken down into several sub-phases:
21668 \newline
21669
21670 \newline
21671 Break down intermediate code (iCode) into basic blocks.
21672 \newline
21673 Do control flow & data flow analysis on the basic blocks.
21674 \newline
21675 Do local common subexpression elimination, then global subexpression elimination
21676 \newline
21677 Dead code elimination
21678 \newline
21679 Loop optimizations
21680 \newline
21681 If loop optimizations caused any changes then do 'global subexpression eliminati
21682 on' and 'dead code elimination' again.
21683 \layout Itemize
21684
21685 This phase determines the live-ranges; by live range I mean those iTemp
21686  variables defined by the compiler that still survive after all the optimization
21687 s.
21688  Live range analysis
21689 \begin_inset LatexCommand \index{Live range analysis}
21690
21691 \end_inset
21692
21693  is essential for register allocation, since these computation determines
21694  which of these iTemps will be assigned to registers, and for how long.
21695 \layout Itemize
21696
21697 Phase five is register allocation.
21698  There are two parts to this process.
21699 \newline
21700
21701 \newline
21702 The first part I call 'register packing' (for lack of a better term).
21703  In this case several MCU specific expression folding is done to reduce
21704  register pressure.
21705 \newline
21706
21707 \newline
21708 The second part is more MCU independent and deals with allocating registers
21709  to the remaining live ranges.
21710  A lot of MCU specific code does creep into this phase because of the limited
21711  number of index registers available in the 8051.
21712 \layout Itemize
21713
21714 The Code generation phase is (unhappily), entirely MCU dependent and very
21715  little (if any at all) of this code can be reused for other MCU.
21716  However the scheme for allocating a homogenized assembler operand for each
21717  iCode operand may be reused.
21718 \layout Itemize
21719
21720 As mentioned in the optimization section the peep-hole optimizer is rule
21721  based system, which can reprogrammed for other MCUs.
21722 \layout Chapter
21723
21724 Compiler internals
21725 \begin_inset LatexCommand \index{Compiler internals}
21726
21727 \end_inset
21728
21729
21730 \layout Section
21731
21732 The anatomy of the compiler
21733 \begin_inset LatexCommand \label{sub:The-anatomy-of}
21734
21735 \end_inset
21736
21737
21738 \layout Standard
21739
21740
21741 \shape italic
21742 This is an excerpt from an article published in Circuit Cellar Magazine
21743  in august 2000.
21744  It's a little outdated (the compiler is much more efficient now and user/develo
21745 per friendly), but pretty well exposes the guts of it all.
21746 \shape default
21747
21748 \newline
21749
21750 \newline
21751 The current version of SDCC can generate code for Intel 8051 and Z80 MCU.
21752  It is fairly easy to retarget for other 8-bit MCU.
21753  Here we take a look at some of the internals of the compiler.
21754
21755 \layout Paragraph*
21756
21757 Parsing
21758 \begin_inset LatexCommand \index{Parsing}
21759
21760 \end_inset
21761
21762
21763 \layout Standard
21764
21765 Parsing the input source file and creating an AST (Annotated Syntax Tree
21766 \begin_inset LatexCommand \index{Annotated syntax tree}
21767
21768 \end_inset
21769
21770 ).
21771  This phase also involves propagating types (annotating each node of the
21772  parse tree with type information) and semantic analysis.
21773  There are some MCU specific parsing rules.
21774  For example the storage classes, the extended storage classes are MCU specific
21775  while there may be a xdata storage class for 8051 there is no such storage
21776  class for z80 or Atmel AVR.
21777  SDCC allows MCU specific storage class extensions, i.e.
21778  xdata will be treated as a storage class specifier when parsing 8051 C
21779  code but will be treated as a C identifier when parsing z80 or ATMEL AVR
21780  C code.
21781 \layout Paragraph*
21782
21783 Generating iCode
21784 \begin_inset LatexCommand \index{iCode}
21785
21786 \end_inset
21787
21788
21789 \layout Standard
21790
21791 Intermediate code generation.
21792  In this phase the AST is broken down into three-operand form (iCode).
21793  These three operand forms are represented as doubly linked lists.
21794  ICode is the term given to the intermediate form generated by the compiler.
21795  ICode example section shows some examples of iCode generated for some simple
21796  C source functions.
21797 \layout Paragraph*
21798
21799 Optimizations
21800 \begin_inset LatexCommand \index{Optimizations}
21801
21802 \end_inset
21803
21804 .
21805 \layout Standard
21806
21807 Bulk of the target independent optimizations is performed in this phase.
21808  The optimizations include constant propagation, common sub-expression eliminati
21809 on, loop invariant code movement, strength reduction of loop induction variables
21810  and dead-code elimination.
21811 \layout Paragraph*
21812
21813 Live range analysis
21814 \begin_inset LatexCommand \index{Live range analysis}
21815
21816 \end_inset
21817
21818
21819 \layout Standard
21820
21821 During intermediate code generation phase, the compiler assumes the target
21822  machine has infinite number of registers and generates a lot of temporary
21823  variables.
21824  The live range computation determines the lifetime of each of these compiler-ge
21825 nerated temporaries.
21826  A picture speaks a thousand words.
21827  ICode example sections show the live range annotations for each of the
21828  operand.
21829  It is important to note here, each iCode is assigned a number in the order
21830  of its execution in the function.
21831  The live ranges are computed in terms of these numbers.
21832  The from number is the number of the iCode which first defines the operand
21833  and the to number signifies the iCode which uses this operand last.
21834 \layout Paragraph*
21835
21836 Register Allocation
21837 \begin_inset LatexCommand \index{Register allocation}
21838
21839 \end_inset
21840
21841
21842 \layout Standard
21843
21844 The register allocation determines the type and number of registers needed
21845  by each operand.
21846  In most MCUs only a few registers can be used for indirect addressing.
21847  In case of 8051 for example the registers R0 & R1 can be used to indirectly
21848  address the internal ram and DPTR to indirectly address the external ram.
21849  The compiler will try to allocate the appropriate register to pointer variables
21850  if it can.
21851  ICode example section shows the operands annotated with the registers assigned
21852  to them.
21853  The compiler will try to keep operands in registers as much as possible;
21854  there are several schemes the compiler uses to do achieve this.
21855  When the compiler runs out of registers the compiler will check to see
21856  if there are any live operands which is not used or defined in the current
21857  basic block being processed, if there are any found then it will push that
21858  operand and use the registers in this block, the operand will then be popped
21859  at the end of the basic block.
21860
21861 \layout Standard
21862
21863 There are other MCU specific considerations in this phase.
21864  Some MCUs have an accumulator; very short-lived operands could be assigned
21865  to the accumulator instead of a general-purpose register.
21866 \layout Paragraph*
21867
21868 Code generation
21869 \layout Standard
21870
21871 Figure II gives a table of iCode operations supported by the compiler.
21872  The code generation involves translating these operations into corresponding
21873  assembly code for the processor.
21874  This sounds overly simple but that is the essence of code generation.
21875  Some of the iCode operations are generated on a MCU specific manner for
21876  example, the z80 port does not use registers to pass parameters so the
21877  SEND and RECV iCode operations will not be generated, and it also does
21878  not support JUMPTABLES.
21879
21880 \newline
21881
21882 \series bold
21883 \shape italic
21884 \color red
21885 <Where is Figure II?>
21886 \layout Comment
21887
21888 In the original article Figure II was announced to be downloadable on
21889 \shape italic
21890 Circuit Cellar
21891 \shape default
21892 's web site.
21893  Unfortunately it never seemed to have shown up there, so: where is Figure
21894  II?
21895 \layout Paragraph*
21896
21897 ICode Example
21898 \begin_inset LatexCommand \index{iCode}
21899
21900 \end_inset
21901
21902
21903 \layout Standard
21904
21905 This section shows some details of iCode.
21906  The example C code does not do anything useful; it is used as an example
21907  to illustrate the intermediate code generated by the compiler.
21908 \layout Verse
21909
21910
21911 \family typewriter
21912 1.\SpecialChar ~
21913 xdata int * p;
21914 \newline
21915 2.\SpecialChar ~
21916 int gint;
21917 \newline
21918 3.\SpecialChar ~
21919 /* This function does nothing useful.
21920  It is used
21921 \newline
21922 4.\SpecialChar ~
21923 \SpecialChar ~
21924 \SpecialChar ~
21925 \SpecialChar ~
21926 for the purpose of explaining iCode */
21927 \newline
21928 5.\SpecialChar ~
21929 short function (data int *x)
21930 \newline
21931 6.\SpecialChar ~
21932 {
21933 \newline
21934 7.\SpecialChar ~
21935 \SpecialChar ~
21936 \SpecialChar ~
21937 short i=10; \SpecialChar ~
21938 \SpecialChar ~
21939 /* dead initialization eliminated */
21940 \newline
21941 8.\SpecialChar ~
21942 \SpecialChar ~
21943 \SpecialChar ~
21944 short sum=10; /* dead initialization eliminated */
21945 \newline
21946 9.\SpecialChar ~
21947 \SpecialChar ~
21948 \SpecialChar ~
21949 short mul;
21950 \newline
21951 10.\SpecialChar ~
21952 \SpecialChar ~
21953 int j ;
21954 \newline
21955 11.\SpecialChar ~
21956 \SpecialChar ~
21957 while (*x) *x++ = *p++;
21958 \newline
21959 12.\SpecialChar ~
21960 \SpecialChar ~
21961 \SpecialChar ~
21962 \SpecialChar ~
21963 sum = 0 ;
21964 \newline
21965 13.\SpecialChar ~
21966 \SpecialChar ~
21967 mul = 0;
21968 \newline
21969 14.\SpecialChar ~
21970 \SpecialChar ~
21971 /* compiler detects i,j to be induction variables */
21972 \newline
21973 15.\SpecialChar ~
21974 \SpecialChar ~
21975 for (i = 0, j = 10 ; i < 10 ; i++, j
21976 \family default
21977 -
21978 \begin_inset ERT
21979 status Collapsed
21980
21981 \layout Standard
21982
21983 \backslash
21984 /
21985 \end_inset
21986
21987 -
21988 \family typewriter
21989 ) {
21990 \newline
21991 16.\SpecialChar ~
21992 \SpecialChar ~
21993 \SpecialChar ~
21994 \SpecialChar ~
21995 sum += i;
21996 \newline
21997 17.\SpecialChar ~
21998 \SpecialChar ~
21999 \SpecialChar ~
22000 \SpecialChar ~
22001 mul += i * 3; \SpecialChar ~
22002 \SpecialChar ~
22003 /* this multiplication remains */
22004 \newline
22005 18.\SpecialChar ~
22006 \SpecialChar ~
22007 \SpecialChar ~
22008 \SpecialChar ~
22009 gint += j * 3;\SpecialChar ~
22010 \SpecialChar ~
22011 /* this multiplication changed to addition */
22012 \newline
22013 19.\SpecialChar ~
22014 \SpecialChar ~
22015 }
22016 \newline
22017 20.\SpecialChar ~
22018 \SpecialChar ~
22019 return sum+mul;
22020 \newline
22021 21.\SpecialChar ~
22022 }
22023 \layout Standard
22024
22025 In addition to the operands each iCode contains information about the filename
22026  and line it corresponds to in the source file.
22027  The first field in the listing should be interpreted as follows:
22028 \newline
22029
22030 \shape italic
22031 \size footnotesize
22032 Filename(linenumber: iCode Execution sequence number : ICode hash table
22033  key : loop depth of the iCode).
22034 \shape default
22035 \size default
22036
22037 \newline
22038 Then follows the human readable form of the ICode operation.
22039  Each operand of this triplet form can be of three basic types a) compiler
22040  generated temporary b) user defined variable c) a constant value.
22041  Note that local variables and parameters are replaced by compiler generated
22042  temporaries.
22043  Live ranges
22044 \begin_inset LatexCommand \index{Live range analysis}
22045
22046 \end_inset
22047
22048  are computed only for temporaries (i.e.
22049  live ranges are not computed for global variables).
22050  Registers
22051 \begin_inset LatexCommand \index{Register allocation}
22052
22053 \end_inset
22054
22055  are allocated for temporaries only.
22056  Operands are formatted in the following manner:
22057 \newline
22058
22059 \shape italic
22060 \size footnotesize
22061 Operand Name [lr live-from : live-to ] { type information } [ registers
22062  allocated ].
22063 \shape default
22064 \size default
22065
22066 \newline
22067 As mentioned earlier the live ranges are computed in terms of the execution
22068  sequence number of the iCodes, for example
22069 \newline
22070 the iTemp0 is live from (i.e.
22071  first defined in iCode with execution sequence number 3, and is last used
22072  in the iCode with sequence number 5).
22073  For induction variables such as iTemp21 the live range computation extends
22074  the lifetime from the start to the end of the loop.
22075 \newline
22076 The register allocator used the live range information to allocate registers,
22077  the same registers may be used for different temporaries if their live
22078  ranges do not overlap, for example r0 is allocated to both iTemp6 and to
22079  iTemp17 since their live ranges do not overlap.
22080  In addition the allocator also takes into consideration the type and usage
22081  of a temporary, for example itemp6 is a pointer to near space and is used
22082  as to fetch data from (i.e.
22083  used in GET_VALUE_AT_ADDRESS) so it is allocated a pointer register (r0).
22084  Some short lived temporaries are allocated to special registers which have
22085  meaning to the code generator e.g.
22086  iTemp13 is allocated to a pseudo register CC which tells the back end that
22087  the temporary is used only for a conditional jump the code generation makes
22088  use of this information to optimize a compare and jump ICode.
22089 \newline
22090 There are several loop optimizations
22091 \begin_inset LatexCommand \index{Loop optimization}
22092
22093 \end_inset
22094
22095  performed by the compiler.
22096  It can detect induction variables iTemp21(i) and iTemp23(j).
22097  Also note the compiler does selective strength reduction
22098 \begin_inset LatexCommand \index{Strength reduction}
22099
22100 \end_inset
22101
22102 , i.e.
22103  the multiplication of an induction variable in line 18 (gint = j * 3) is
22104  changed to addition, a new temporary iTemp17 is allocated and assigned
22105  a initial value, a constant 3 is then added for each iteration of the loop.
22106  The compiler does not change the multiplication
22107 \begin_inset LatexCommand \index{Multiplication}
22108
22109 \end_inset
22110
22111  in line 17 however since the processor does support an 8 * 8 bit multiplication.
22112 \newline
22113 Note the dead code elimination
22114 \begin_inset LatexCommand \index{Dead-code elimination}
22115
22116 \end_inset
22117
22118  optimization eliminated the dead assignments in line 7 & 8 to I and sum
22119  respectively.
22120 \newline
22121
22122 \layout Standard
22123
22124
22125 \size footnotesize
22126 Sample.c (5:1:0:0) _entry($9) :
22127 \layout Standard
22128
22129
22130 \size footnotesize
22131 Sample.c(5:2:1:0) proc _function [lr0:0]{function short}
22132 \layout Standard
22133
22134
22135 \size footnotesize
22136 Sample.c(11:3:2:0) iTemp0 [lr3:5]{_near * int}[r2] = recv
22137 \layout Standard
22138
22139
22140 \size footnotesize
22141 Sample.c(11:4:53:0) preHeaderLbl0($11) :
22142 \layout Standard
22143
22144
22145 \size footnotesize
22146 Sample.c(11:5:55:0) iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near
22147  * int}[r2]
22148 \layout Standard
22149
22150
22151 \size footnotesize
22152 Sample.c(11:6:5:1) _whilecontinue_0($1) :
22153 \layout Standard
22154
22155
22156 \size footnotesize
22157 Sample.c(11:7:7:1) iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near *
22158  int}[r0]]
22159 \layout Standard
22160
22161
22162 \size footnotesize
22163 Sample.c(11:8:8:1) if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
22164 \layout Standard
22165
22166
22167 \size footnotesize
22168 Sample.c(11:9:14:1) iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far
22169  * int}
22170 \layout Standard
22171
22172
22173 \size footnotesize
22174 Sample.c(11:10:15:1) _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2
22175  {short}
22176 \layout Standard
22177
22178
22179 \size footnotesize
22180 Sample.c(11:13:18:1) iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far
22181  * int}[DPTR]]
22182 \layout Standard
22183
22184
22185 \size footnotesize
22186 Sample.c(11:14:19:1) *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int
22187 }[r2 r3]
22188 \layout Standard
22189
22190
22191 \size footnotesize
22192 Sample.c(11:15:12:1) iTemp6 [lr5:16]{_near * int}[r0] = iTemp6 [lr5:16]{_near
22193  * int}[r0] + 0x2 {short}
22194 \layout Standard
22195
22196
22197 \size footnotesize
22198 Sample.c(11:16:20:1) goto _whilecontinue_0($1)
22199 \layout Standard
22200
22201
22202 \size footnotesize
22203 Sample.c(11:17:21:0)_whilebreak_0($3) :
22204 \layout Standard
22205
22206
22207 \size footnotesize
22208 Sample.c(12:18:22:0) iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22209 \layout Standard
22210
22211
22212 \size footnotesize
22213 Sample.c(13:19:23:0) iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22214 \layout Standard
22215
22216
22217 \size footnotesize
22218 Sample.c(15:20:54:0)preHeaderLbl1($13) :
22219 \layout Standard
22220
22221
22222 \size footnotesize
22223 Sample.c(15:21:56:0) iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22224 \layout Standard
22225
22226
22227 \size footnotesize
22228 Sample.c(15:22:57:0) iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22229 \layout Standard
22230
22231
22232 \size footnotesize
22233 Sample.c(15:23:58:0) iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22234 \layout Standard
22235
22236
22237 \size footnotesize
22238 Sample.c(15:24:26:1)_forcond_0($4) :
22239 \layout Standard
22240
22241
22242 \size footnotesize
22243 Sample.c(15:25:27:1) iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4]
22244  < 0xa {short}
22245 \layout Standard
22246
22247
22248 \size footnotesize
22249 Sample.c(15:26:28:1) if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22250 \layout Standard
22251
22252
22253 \size footnotesize
22254 Sample.c(16:27:31:1) iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2]
22255  + ITemp21 [lr21:38]{short}[r4]
22256 \layout Standard
22257
22258
22259 \size footnotesize
22260 Sample.c(17:29:33:1) iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4]
22261  * 0x3 {short}
22262 \layout Standard
22263
22264
22265 \size footnotesize
22266 Sample.c(17:30:34:1) iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3]
22267  + iTemp15 [lr29:30]{short}[r1]
22268 \layout Standard
22269
22270
22271 \size footnotesize
22272 Sample.c(18:32:36:1:1) iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7
22273  r0]- 0x3 {short}
22274 \layout Standard
22275
22276
22277 \size footnotesize
22278 Sample.c(18:33:37:1) _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{
22279 int}[r7 r0]
22280 \layout Standard
22281
22282
22283 \size footnotesize
22284 Sample.c(15:36:42:1) iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4]
22285  + 0x1 {short}
22286 \layout Standard
22287
22288
22289 \size footnotesize
22290 Sample.c(15:37:45:1) iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5
22291  r6]- 0x1 {short}
22292 \layout Standard
22293
22294
22295 \size footnotesize
22296 Sample.c(19:38:47:1) goto _forcond_0($4)
22297 \layout Standard
22298
22299
22300 \size footnotesize
22301 Sample.c(19:39:48:0)_forbreak_0($7) :
22302 \layout Standard
22303
22304
22305 \size footnotesize
22306 Sample.c(20:40:49:0) iTemp24 [lr40:41]{short}[DPTR] = iTemp2 [lr18:40]{short}[r2]
22307  + ITemp11 [lr19:40]{short}[r3]
22308 \layout Standard
22309
22310
22311 \size footnotesize
22312 Sample.c(20:41:50:0) ret iTemp24 [lr40:41]{short}
22313 \layout Standard
22314
22315
22316 \size footnotesize
22317 Sample.c(20:42:51:0)_return($8) :
22318 \layout Standard
22319
22320
22321 \size footnotesize
22322 Sample.c(20:43:52:0) eproc _function [lr0:0]{ ia0 re0 rm0}{function short}
22323 \size default
22324
22325 \newline
22326
22327 \newline
22328 Finally the code generated for this function:
22329 \newline
22330
22331 \layout Standard
22332
22333
22334 \size footnotesize
22335 .area DSEG (DATA)
22336 \layout Standard
22337
22338
22339 \size footnotesize
22340 _p::
22341 \layout Standard
22342
22343
22344 \size footnotesize
22345 \SpecialChar ~
22346 \SpecialChar ~
22347 .ds 2
22348 \layout Standard
22349
22350
22351 \size footnotesize
22352 _gint::
22353 \layout Standard
22354
22355
22356 \size footnotesize
22357 \SpecialChar ~
22358 \SpecialChar ~
22359 .ds 2
22360 \layout Standard
22361
22362
22363 \size footnotesize
22364 ; sample.c 5
22365 \layout Standard
22366
22367
22368 \size footnotesize
22369 ; ----------------------------------------------
22370 \layout Standard
22371
22372
22373 \size footnotesize
22374 ; function function
22375 \layout Standard
22376
22377
22378 \size footnotesize
22379 ; ----------------------------------------------
22380 \layout Standard
22381
22382
22383 \size footnotesize
22384 _function:
22385 \layout Standard
22386
22387
22388 \size footnotesize
22389 ; iTemp0 [lr3:5]{_near * int}[r2] = recv
22390 \layout Standard
22391
22392
22393 \size footnotesize
22394 \SpecialChar ~
22395 \SpecialChar ~
22396 mov r2,dpl
22397 \layout Standard
22398
22399
22400 \size footnotesize
22401 ; iTemp6 [lr5:16]{_near * int}[r0] := iTemp0 [lr3:5]{_near * int}[r2]
22402 \layout Standard
22403
22404
22405 \size footnotesize
22406 \SpecialChar ~
22407 \SpecialChar ~
22408 mov ar0,r2
22409 \layout Standard
22410
22411
22412 \size footnotesize
22413 ;_whilecontinue_0($1) :
22414 \layout Standard
22415
22416
22417 \size footnotesize
22418 00101$:
22419 \layout Standard
22420
22421
22422 \size footnotesize
22423 ; iTemp4 [lr7:8]{int}[r2 r3] = @[iTemp6 [lr5:16]{_near * int}[r0]]
22424 \layout Standard
22425
22426
22427 \size footnotesize
22428 ; if iTemp4 [lr7:8]{int}[r2 r3] == 0 goto _whilebreak_0($3)
22429 \layout Standard
22430
22431
22432 \size footnotesize
22433 \SpecialChar ~
22434 \SpecialChar ~
22435 mov ar2,@r0
22436 \layout Standard
22437
22438
22439 \size footnotesize
22440 \SpecialChar ~
22441 \SpecialChar ~
22442 inc r0
22443 \layout Standard
22444
22445
22446 \size footnotesize
22447 \SpecialChar ~
22448 \SpecialChar ~
22449 mov ar3,@r0
22450 \layout Standard
22451
22452
22453 \size footnotesize
22454 \SpecialChar ~
22455 \SpecialChar ~
22456 dec r0
22457 \layout Standard
22458
22459
22460 \size footnotesize
22461 \SpecialChar ~
22462 \SpecialChar ~
22463 mov a,r2
22464 \layout Standard
22465
22466
22467 \size footnotesize
22468 \SpecialChar ~
22469 \SpecialChar ~
22470 orl a,r3
22471 \layout Standard
22472
22473
22474 \size footnotesize
22475 \SpecialChar ~
22476 \SpecialChar ~
22477 jz 00103$
22478 \layout Standard
22479
22480
22481 \size footnotesize
22482 00114$:
22483 \layout Standard
22484
22485
22486 \size footnotesize
22487 ; iTemp7 [lr9:13]{_far * int}[DPTR] := _p [lr0:0]{_far * int}
22488 \layout Standard
22489
22490
22491 \size footnotesize
22492 \SpecialChar ~
22493 \SpecialChar ~
22494 mov dpl,_p
22495 \layout Standard
22496
22497
22498 \size footnotesize
22499 \SpecialChar ~
22500 \SpecialChar ~
22501 mov dph,(_p + 1)
22502 \layout Standard
22503
22504
22505 \size footnotesize
22506 ; _p [lr0:0]{_far * int} = _p [lr0:0]{_far * int} + 0x2 {short}
22507 \layout Standard
22508
22509
22510 \size footnotesize
22511 \SpecialChar ~
22512 \SpecialChar ~
22513 mov a,#0x02
22514 \layout Standard
22515
22516
22517 \size footnotesize
22518 \SpecialChar ~
22519 \SpecialChar ~
22520 add a,_p
22521 \layout Standard
22522
22523
22524 \size footnotesize
22525 \SpecialChar ~
22526 \SpecialChar ~
22527 mov _p,a
22528 \layout Standard
22529
22530
22531 \size footnotesize
22532 \SpecialChar ~
22533 \SpecialChar ~
22534 clr a
22535 \layout Standard
22536
22537
22538 \size footnotesize
22539 \SpecialChar ~
22540 \SpecialChar ~
22541 addc a,(_p + 1)
22542 \layout Standard
22543
22544
22545 \size footnotesize
22546 \SpecialChar ~
22547 \SpecialChar ~
22548 mov (_p + 1),a
22549 \layout Standard
22550
22551
22552 \size footnotesize
22553 ; iTemp10 [lr13:14]{int}[r2 r3] = @[iTemp7 [lr9:13]{_far * int}[DPTR]]
22554 \layout Standard
22555
22556
22557 \size footnotesize
22558 \SpecialChar ~
22559 \SpecialChar ~
22560 movx a,@dptr
22561 \layout Standard
22562
22563
22564 \size footnotesize
22565 \SpecialChar ~
22566 \SpecialChar ~
22567 mov r2,a
22568 \layout Standard
22569
22570
22571 \size footnotesize
22572 \SpecialChar ~
22573 \SpecialChar ~
22574 inc dptr
22575 \layout Standard
22576
22577
22578 \size footnotesize
22579 \SpecialChar ~
22580 \SpecialChar ~
22581 movx a,@dptr
22582 \layout Standard
22583
22584
22585 \size footnotesize
22586 \SpecialChar ~
22587 \SpecialChar ~
22588 mov r3,a
22589 \layout Standard
22590
22591
22592 \size footnotesize
22593 ; *(iTemp6 [lr5:16]{_near * int}[r0]) := iTemp10 [lr13:14]{int}[r2 r3]
22594 \layout Standard
22595
22596
22597 \size footnotesize
22598 \SpecialChar ~
22599 \SpecialChar ~
22600 mov @r0,ar2
22601 \layout Standard
22602
22603
22604 \size footnotesize
22605 \SpecialChar ~
22606 \SpecialChar ~
22607 inc r0
22608 \layout Standard
22609
22610
22611 \size footnotesize
22612 \SpecialChar ~
22613 \SpecialChar ~
22614 mov @r0,ar3
22615 \layout Standard
22616
22617
22618 \size footnotesize
22619 ; iTemp6 [lr5:16]{_near * int}[r0] =
22620 \layout Standard
22621
22622
22623 \size footnotesize
22624 ; iTemp6 [lr5:16]{_near * int}[r0] +
22625 \layout Standard
22626
22627
22628 \size footnotesize
22629 ; 0x2 {short}
22630 \layout Standard
22631
22632
22633 \size footnotesize
22634 \SpecialChar ~
22635 \SpecialChar ~
22636 inc r0
22637 \layout Standard
22638
22639
22640 \size footnotesize
22641 ; goto _whilecontinue_0($1)
22642 \layout Standard
22643
22644
22645 \size footnotesize
22646 \SpecialChar ~
22647 \SpecialChar ~
22648 sjmp 00101$
22649 \layout Standard
22650
22651
22652 \size footnotesize
22653 ; _whilebreak_0($3) :
22654 \layout Standard
22655
22656
22657 \size footnotesize
22658 00103$:
22659 \layout Standard
22660
22661
22662 \size footnotesize
22663 ; iTemp2 [lr18:40]{short}[r2] := 0x0 {short}
22664 \layout Standard
22665
22666
22667 \size footnotesize
22668 \SpecialChar ~
22669 \SpecialChar ~
22670 mov r2,#0x00
22671 \layout Standard
22672
22673
22674 \size footnotesize
22675 ; iTemp11 [lr19:40]{short}[r3] := 0x0 {short}
22676 \layout Standard
22677
22678
22679 \size footnotesize
22680 \SpecialChar ~
22681 \SpecialChar ~
22682 mov r3,#0x00
22683 \layout Standard
22684
22685
22686 \size footnotesize
22687 ; iTemp21 [lr21:38]{short}[r4] := 0x0 {short}
22688 \layout Standard
22689
22690
22691 \size footnotesize
22692 \SpecialChar ~
22693 \SpecialChar ~
22694 mov r4,#0x00
22695 \layout Standard
22696
22697
22698 \size footnotesize
22699 ; iTemp23 [lr22:38]{int}[r5 r6] := 0xa {int}
22700 \layout Standard
22701
22702
22703 \size footnotesize
22704 \SpecialChar ~
22705 \SpecialChar ~
22706 mov r5,#0x0A
22707 \layout Standard
22708
22709
22710 \size footnotesize
22711 \SpecialChar ~
22712 \SpecialChar ~
22713 mov r6,#0x00
22714 \layout Standard
22715
22716
22717 \size footnotesize
22718 ; iTemp17 [lr23:38]{int}[r7 r0] := 0x1e {int}
22719 \layout Standard
22720
22721
22722 \size footnotesize
22723 \SpecialChar ~
22724 \SpecialChar ~
22725 mov r7,#0x1E
22726 \layout Standard
22727
22728
22729 \size footnotesize
22730 \SpecialChar ~
22731 \SpecialChar ~
22732 mov r0,#0x00
22733 \layout Standard
22734
22735
22736 \size footnotesize
22737 ; _forcond_0($4) :
22738 \layout Standard
22739
22740
22741 \size footnotesize
22742 00104$:
22743 \layout Standard
22744
22745
22746 \size footnotesize
22747 ; iTemp13 [lr25:26]{char}[CC] = iTemp21 [lr21:38]{short}[r4] < 0xa {short}
22748 \layout Standard
22749
22750
22751 \size footnotesize
22752 ; if iTemp13 [lr25:26]{char}[CC] == 0 goto _forbreak_0($7)
22753 \layout Standard
22754
22755
22756 \size footnotesize
22757 \SpecialChar ~
22758 \SpecialChar ~
22759 clr c
22760 \layout Standard
22761
22762
22763 \size footnotesize
22764 \SpecialChar ~
22765 \SpecialChar ~
22766 mov a,r4
22767 \layout Standard
22768
22769
22770 \size footnotesize
22771 \SpecialChar ~
22772 \SpecialChar ~
22773 xrl a,#0x80
22774 \layout Standard
22775
22776
22777 \size footnotesize
22778 \SpecialChar ~
22779 \SpecialChar ~
22780 subb a,#0x8a
22781 \layout Standard
22782
22783
22784 \size footnotesize
22785 \SpecialChar ~
22786 \SpecialChar ~
22787 jnc 00107$
22788 \layout Standard
22789
22790
22791 \size footnotesize
22792 00115$:
22793 \layout Standard
22794
22795
22796 \size footnotesize
22797 ; iTemp2 [lr18:40]{short}[r2] = iTemp2 [lr18:40]{short}[r2] +
22798 \layout Standard
22799
22800
22801 \size footnotesize
22802 ; iTemp21 [lr21:38]{short}[r4]
22803 \layout Standard
22804
22805
22806 \size footnotesize
22807 \SpecialChar ~
22808 \SpecialChar ~
22809 mov a,r4
22810 \layout Standard
22811
22812
22813 \size footnotesize
22814 \SpecialChar ~
22815 \SpecialChar ~
22816 add a,r2
22817 \layout Standard
22818
22819
22820 \size footnotesize
22821 \SpecialChar ~
22822 \SpecialChar ~
22823 mov r2,a
22824 \layout Standard
22825
22826
22827 \size footnotesize
22828 ; iTemp15 [lr29:30]{short}[r1] = iTemp21 [lr21:38]{short}[r4] * 0x3 {short}
22829 \layout Standard
22830
22831
22832 \size footnotesize
22833 \SpecialChar ~
22834 \SpecialChar ~
22835 mov b,#0x03
22836 \layout Standard
22837
22838
22839 \size footnotesize
22840 \SpecialChar ~
22841 \SpecialChar ~
22842 mov a,r4
22843 \layout Standard
22844
22845
22846 \size footnotesize
22847 \SpecialChar ~
22848 \SpecialChar ~
22849 mul ab
22850 \layout Standard
22851
22852
22853 \size footnotesize
22854 \SpecialChar ~
22855 \SpecialChar ~
22856 mov r1,a
22857 \layout Standard
22858
22859
22860 \size footnotesize
22861 ; iTemp11 [lr19:40]{short}[r3] = iTemp11 [lr19:40]{short}[r3] +
22862 \layout Standard
22863
22864
22865 \size footnotesize
22866 ; iTemp15 [lr29:30]{short}[r1]
22867 \layout Standard
22868
22869
22870 \size footnotesize
22871 \SpecialChar ~
22872 \SpecialChar ~
22873 add a,r3
22874 \layout Standard
22875
22876
22877 \size footnotesize
22878 \SpecialChar ~
22879 \SpecialChar ~
22880 mov r3,a
22881 \layout Standard
22882
22883
22884 \size footnotesize
22885 ; iTemp17 [lr23:38]{int}[r7 r0]= iTemp17 [lr23:38]{int}[r7 r0]- 0x3 {short}
22886 \layout Standard
22887
22888
22889 \size footnotesize
22890 \SpecialChar ~
22891 \SpecialChar ~
22892 mov a,r7
22893 \layout Standard
22894
22895
22896 \size footnotesize
22897 \SpecialChar ~
22898 \SpecialChar ~
22899 add a,#0xfd
22900 \layout Standard
22901
22902
22903 \size footnotesize
22904 \SpecialChar ~
22905 \SpecialChar ~
22906 mov r7,a
22907 \layout Standard
22908
22909
22910 \size footnotesize
22911 \SpecialChar ~
22912 \SpecialChar ~
22913 mov a,r0
22914 \layout Standard
22915
22916
22917 \size footnotesize
22918 \SpecialChar ~
22919 \SpecialChar ~
22920 addc a,#0xff
22921 \layout Standard
22922
22923
22924 \size footnotesize
22925 \SpecialChar ~
22926 \SpecialChar ~
22927 mov r0,a
22928 \layout Standard
22929
22930
22931 \size footnotesize
22932 ; _gint [lr0:0]{int} = _gint [lr0:0]{int} + iTemp17 [lr23:38]{int}[r7 r0]
22933 \layout Standard
22934
22935
22936 \size footnotesize
22937 \SpecialChar ~
22938 \SpecialChar ~
22939 mov a,r7
22940 \layout Standard
22941
22942
22943 \size footnotesize
22944 \SpecialChar ~
22945 \SpecialChar ~
22946 add a,_gint
22947 \layout Standard
22948
22949
22950 \size footnotesize
22951 \SpecialChar ~
22952 \SpecialChar ~
22953 mov _gint,a
22954 \layout Standard
22955
22956
22957 \size footnotesize
22958 \SpecialChar ~
22959 \SpecialChar ~
22960 mov a,r0
22961 \layout Standard
22962
22963
22964 \size footnotesize
22965 \SpecialChar ~
22966 \SpecialChar ~
22967 addc a,(_gint + 1)
22968 \layout Standard
22969
22970
22971 \size footnotesize
22972 \SpecialChar ~
22973 \SpecialChar ~
22974 mov (_gint + 1),a
22975 \layout Standard
22976
22977
22978 \size footnotesize
22979 ; iTemp21 [lr21:38]{short}[r4] = iTemp21 [lr21:38]{short}[r4] + 0x1 {short}
22980 \layout Standard
22981
22982
22983 \size footnotesize
22984 \SpecialChar ~
22985 \SpecialChar ~
22986 inc r4
22987 \layout Standard
22988
22989
22990 \size footnotesize
22991 ; iTemp23 [lr22:38]{int}[r5 r6]= iTemp23 [lr22:38]{int}[r5 r6]- 0x1 {short}
22992 \layout Standard
22993
22994
22995 \size footnotesize
22996 \SpecialChar ~
22997 \SpecialChar ~
22998 dec r5
22999 \layout Standard
23000
23001
23002 \size footnotesize
23003 \SpecialChar ~
23004 \SpecialChar ~
23005 cjne r5,#0xff,00104$
23006 \layout Standard
23007
23008
23009 \size footnotesize
23010 \SpecialChar ~
23011 \SpecialChar ~
23012 dec r6
23013 \layout Standard
23014
23015
23016 \size footnotesize
23017 ; goto _forcond_0($4)
23018 \layout Standard
23019
23020
23021 \size footnotesize
23022 \SpecialChar ~
23023 \SpecialChar ~
23024 sjmp 00104$
23025 \layout Standard
23026
23027
23028 \size footnotesize
23029 ; _forbreak_0($7) :
23030 \layout Standard
23031
23032
23033 \size footnotesize
23034 00107$:
23035 \layout Standard
23036
23037
23038 \size footnotesize
23039 ; ret iTemp24 [lr40:41]{short}
23040 \layout Standard
23041
23042
23043 \size footnotesize
23044 \SpecialChar ~
23045 \SpecialChar ~
23046 mov a,r3
23047 \layout Standard
23048
23049
23050 \size footnotesize
23051 \SpecialChar ~
23052 \SpecialChar ~
23053 add a,r2
23054 \layout Standard
23055
23056
23057 \size footnotesize
23058 \SpecialChar ~
23059 \SpecialChar ~
23060 mov dpl,a
23061 \layout Standard
23062
23063
23064 \size footnotesize
23065 ; _return($8) :
23066 \layout Standard
23067
23068
23069 \size footnotesize
23070 00108$:
23071 \layout Standard
23072
23073
23074 \size footnotesize
23075 \SpecialChar ~
23076 \SpecialChar ~
23077 ret
23078 \newline
23079
23080 \layout Section
23081
23082 A few words about basic block successors, predecessors and dominators
23083 \layout Standard
23084
23085 Successors are basic blocks
23086 \begin_inset LatexCommand \index{Basic blocks}
23087
23088 \end_inset
23089
23090  that might execute after this basic block.
23091 \newline
23092 Predecessors are basic blocks that might execute before reaching this basic
23093  block.
23094 \newline
23095 Dominators are basic blocks that WILL execute before reaching this basic
23096  block.
23097 \newline
23098
23099 \layout Standard
23100
23101 [basic block 1]
23102 \layout Standard
23103
23104 if (something)
23105 \layout Standard
23106
23107 \SpecialChar ~
23108 \SpecialChar ~
23109 \SpecialChar ~
23110 \SpecialChar ~
23111 [basic block 2]
23112 \layout Standard
23113
23114 else
23115 \layout Standard
23116
23117 \SpecialChar ~
23118 \SpecialChar ~
23119 \SpecialChar ~
23120 \SpecialChar ~
23121 [basic block 3]
23122 \layout Standard
23123
23124 [basic block 4]
23125 \newline
23126
23127 \layout Standard
23128
23129 a) succList of [BB2] = [BB4], of [BB3] = [BB4], of [BB1] = [BB2,BB3]
23130 \layout Standard
23131
23132 b) predList of [BB2] = [BB1], of [BB3] = [BB1], of [BB4] = [BB2,BB3]
23133 \layout Standard
23134
23135 c) domVect of [BB4] = BB1 ...
23136  here we are not sure if BB2 or BB3 was executed but we are SURE that BB1
23137  was executed.
23138 \layout Chapter
23139
23140 Acknowledgments
23141 \layout Standard
23142
23143
23144 \begin_inset LatexCommand \url{http://sdcc.sourceforge.net#Who}
23145
23146 \end_inset
23147
23148
23149 \newline
23150
23151 \newline
23152
23153 \emph on
23154 Thanks to all the other volunteer developers who have helped with coding,
23155  testing, web-page creation, distribution sets, etc.
23156  You know who you are :-)
23157 \emph default
23158
23159 \newline
23160
23161 \layout Standard
23162
23163 This document was initially written by Sandeep Dutta
23164 \layout Standard
23165
23166 All product names mentioned herein may be trademarks
23167 \begin_inset LatexCommand \index{Trademarks}
23168
23169 \end_inset
23170
23171  of their respective companies.
23172
23173 \layout Section*
23174
23175 Alphabetical index
23176 \layout Standard
23177
23178 To avoid confusion, the installation and building options for SDCC itself
23179  (chapter 2) are not part of the index.
23180 \layout Standard
23181
23182
23183 \begin_inset LatexCommand \printindex{}
23184
23185 \end_inset
23186
23187
23188 \the_end